diff options
Diffstat (limited to '')
220 files changed, 36776 insertions, 0 deletions
diff --git a/src/doc/.gitignore b/src/doc/.gitignore new file mode 100644 index 0000000..3155cd2 --- /dev/null +++ b/src/doc/.gitignore @@ -0,0 +1,2 @@ +# Ignore built book +book/ diff --git a/src/doc/README.md b/src/doc/README.md new file mode 100644 index 0000000..79181b7 --- /dev/null +++ b/src/doc/README.md @@ -0,0 +1,71 @@ +# Cargo documentation + +This directory contains Cargo's documentation. There are two parts, [The Cargo +Book] which is built with [mdbook] and the man pages, which are built with +[mdman]. + +[The Cargo Book]: https://doc.rust-lang.org/cargo/ +[mdBook]: https://github.com/rust-lang/mdBook +[mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/ + +### Building the book + +Building the book requires [mdBook]. To get it: + +```console +$ cargo install mdbook +``` + +To build the book: + +```console +$ mdbook build +``` + +`mdbook` provides a variety of different commands and options to help you work +on the book: + +* `mdbook build --open`: Build the book and open it in a web browser. +* `mdbook serve`: Launches a web server on localhost. It also automatically + rebuilds the book whenever any file changes and automatically reloads your + web browser. + +The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and +every file must be linked there. + +### Building the man pages + +The man pages use a tool called [mdman] to convert markdown to a man page +format. Check out the documentation at +[`mdman/doc/`](../../crates/mdman/doc/) +for more details. + +The man pages are converted from a templated markdown (located in the +[`src/doc/man/`](man) +directory) to three different formats: + +1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man). +2. Markdown (with some HTML) for the Cargo Book, saved in + [`src/doc/src/commands/`](src/commands). +3. Plain text (needed for embedded man pages on platforms without man such as + Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt). + +To rebuild the man pages, run the script `build-man.sh` in the `src/doc` directory. + +```console +$ ./build-man.sh +``` + +### SemVer chapter tests + +There is a script to verify that the examples in the SemVer chapter work as +intended. To run the tests, go into the `semver-check` directory and run +`cargo run`. + +## Contributing + +We'd love your help with improving the documentation! Please feel free to +[open issues](https://github.com/rust-lang/cargo/issues) about anything, and +send in PRs for things you'd like to fix or change. If your change is large, +please open an issue first, so we can make sure that it's something we'd +accept before you go through the work of getting a PR together. diff --git a/src/doc/book.toml b/src/doc/book.toml new file mode 100644 index 0000000..1dd1f8e --- /dev/null +++ b/src/doc/book.toml @@ -0,0 +1,8 @@ +[book] +title = "The Cargo Book" +author = "Alex Crichton, Steve Klabnik and Carol Nichols, with contributions from the Rust community" + +[output.html] +curly-quotes = true # Enable smart-punctuation feature for more than quotes. +git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/src" +edit-url-template = "https://github.com/rust-lang/cargo/edit/master/src/doc/{path}" diff --git a/src/doc/build-man.sh b/src/doc/build-man.sh new file mode 100755 index 0000000..7b1330b --- /dev/null +++ b/src/doc/build-man.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# +# This script builds the Cargo man pages. +# +# The source for the man pages are located in src/doc/man/ in markdown format. +# These also are handlebars templates, see crates/mdman/README.md for details. +# +# The generated man pages are placed in the src/etc/man/ directory. The pages +# are also expanded into markdown (after being expanded by handlebars) and +# saved in the src/doc/src/commands/ directory. These are included in the +# Cargo book, which is converted to HTML by mdbook. + +set -e + +cd "$(dirname "${BASH_SOURCE[0]}")" + +OPTIONS="--url https://doc.rust-lang.org/cargo/commands/ \ + --man rustc:1=https://doc.rust-lang.org/rustc/index.html \ + --man rustdoc:1=https://doc.rust-lang.org/rustdoc/index.html" + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t md -o src/commands man/cargo*.md \ + $OPTIONS + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t txt -o man/generated_txt man/cargo*.md \ + $OPTIONS + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t man -o ../etc/man man/cargo*.md \ + $OPTIONS diff --git a/src/doc/contrib/README.md b/src/doc/contrib/README.md new file mode 100644 index 0000000..5775621 --- /dev/null +++ b/src/doc/contrib/README.md @@ -0,0 +1,12 @@ +# Cargo Contributor Guide + +This is the source of the Cargo Contributor Guide, published at +<https://rust-lang.github.io/cargo/contrib/>. It is written in Markdown, using +the [mdbook] tool to convert to HTML. If you are editing these pages, the best +option to view the results is to run `mdbook serve`, which will start a web +server on localhost that you can visit to view the book, and it will +automatically reload each time you edit a page. + +This is published via GitHub Actions to GitHub Pages. + +[mdbook]: https://rust-lang.github.io/mdBook/ diff --git a/src/doc/contrib/book.toml b/src/doc/contrib/book.toml new file mode 100644 index 0000000..d6697f3 --- /dev/null +++ b/src/doc/contrib/book.toml @@ -0,0 +1,10 @@ +[book] +title = "Cargo Contributor Guide" +authors = ["Eric Huss"] + +[output.html] +curly-quotes = true # Enable smart-punctuation feature for more than quotes. +git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/contrib/src" + +[output.html.redirect] +"/apidoc/cargo/index.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo/" diff --git a/src/doc/contrib/src/SUMMARY.md b/src/doc/contrib/src/SUMMARY.md new file mode 100644 index 0000000..bf0fb38 --- /dev/null +++ b/src/doc/contrib/src/SUMMARY.md @@ -0,0 +1,21 @@ +# Summary + +- [Introduction](./index.md) +- [Issue Tracker](./issues.md) +- [Process](./process/index.md) + - [Working on Cargo](./process/working-on-cargo.md) + - [Release process](./process/release.md) + - [Unstable features](./process/unstable.md) +- [Architecture](./architecture/index.md) + - [Codebase Overview](./architecture/codebase.md) + - [SubCommands](./architecture/subcommands.md) + - [Console Output](./architecture/console.md) + - [Packages and Resolution](./architecture/packages.md) + - [Compilation](./architecture/compilation.md) + - [Files](./architecture/files.md) +- [Tests](./tests/index.md) + - [Running Tests](./tests/running.md) + - [Writing Tests](./tests/writing.md) + - [Benchmarking and Profiling](./tests/profiling.md) + - [Crater](./tests/crater.md) +- [Design Principles](./design.md) diff --git a/src/doc/contrib/src/architecture/codebase.md b/src/doc/contrib/src/architecture/codebase.md new file mode 100644 index 0000000..45c6e0e --- /dev/null +++ b/src/doc/contrib/src/architecture/codebase.md @@ -0,0 +1,108 @@ +# Codebase Overview + +This is a very high-level overview of the Cargo codebase. + +* [`src/bin/cargo`](https://github.com/rust-lang/cargo/tree/master/src/bin/cargo) + --- Cargo is split in a library and a binary. This is the binary side that + handles argument parsing, and then calls into the library to perform the + appropriate subcommand. Each Cargo subcommand is a separate module here. See + [SubCommands](subcommands.md). + +* [`src/cargo/ops`](https://github.com/rust-lang/cargo/tree/master/src/cargo/ops) + --- Every major operation is implemented here. This is where the binary CLI + usually calls into to perform the appropriate action. + + * [`src/cargo/ops/cargo_compile/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs) + --- This is the entry point for all the compilation commands. This is a + good place to start if you want to follow how compilation starts and + flows to completion. + +* [`src/cargo/core/resolver`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/resolver) + --- This is the dependency and feature resolvers. + +* [`src/cargo/core/compiler`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/compiler) + --- This is the code responsible for running `rustc` and `rustdoc`. + + * [`src/cargo/core/compiler/build_context/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs) + --- The `BuildContext` is the result of the "front end" of the build + process. This contains the graph of work to perform and any settings + necessary for `rustc`. After this is built, the next stage of building + is handled in `Context`. + + * [`src/cargo/core/compiler/context`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs) + --- The `Context` is the mutable state used during the build process. This + is the core of the build process, and everything is coordinated through + this. + + * [`src/cargo/core/compiler/fingerprint.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs) + --- The `fingerprint` module contains all the code that handles detecting + if a crate needs to be recompiled. + +* [`src/cargo/core/source`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/source) + --- The `Source` trait is an abstraction over different sources of packages. + Sources are uniquely identified by a `SourceId`. Sources are implemented in + the + [`src/cargo/sources`](https://github.com/rust-lang/cargo/tree/master/src/cargo/sources) + directory. + +* [`src/cargo/util`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util) + --- This directory contains generally-useful utility modules. + +* [`src/cargo/util/config`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/config) + --- This directory contains the config parser. It makes heavy use of + [serde](https://serde.rs/) to merge and translate config values. The + `Config` is usually accessed from the + [`Workspace`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/workspace.rs), + though references to it are scattered around for more convenient access. + +* [`src/cargo/util/toml`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/toml) + --- This directory contains the code for parsing `Cargo.toml` files. + + * [`src/cargo/ops/lockfile.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/lockfile.rs) + --- This is where `Cargo.lock` files are loaded and saved. + +* [`src/doc`](https://github.com/rust-lang/cargo/tree/master/src/doc) + --- This directory contains Cargo's documentation and man pages. + +* [`src/etc`](https://github.com/rust-lang/cargo/tree/master/src/etc) + --- These are files that get distributed in the `etc` directory in the Rust release. + The man pages are auto-generated by a script in the `src/doc` directory. + +* [`crates`](https://github.com/rust-lang/cargo/tree/master/crates) + --- A collection of independent crates used by Cargo. + +## Extra crates + +Some functionality is split off into separate crates, usually in the +[`crates`](https://github.com/rust-lang/cargo/tree/master/crates) directory. + +* [`cargo-platform`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-platform) + --- This library handles parsing `cfg` expressions. +* [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro) + --- This is a proc-macro used by the test suite to define tests. More + information can be found at [`cargo_test` + attribute](../tests/writing.md#cargo_test-attribute). +* [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support) + --- This contains a variety of code to support [writing + tests](../tests/writing.md). +* [`cargo-util`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-util) + --- This contains general utility code that is shared between cargo and the + testsuite. +* [`crates-io`](https://github.com/rust-lang/cargo/tree/master/crates/crates-io) + --- This contains code for accessing the crates.io API. +* [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential) + --- This subdirectory contains several packages for implementing the + experimental + [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process) + feature. +* [`home`](https://github.com/rust-lang/cargo/tree/master/crates/home) --- This library is shared between cargo and rustup and is used for finding their home directories. + This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io. + It is intended to be versioned and published independently of Rust's release system. + Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version. +* [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman) + --- This is a utility for generating cargo's man pages. See [Building the man + pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages) + for more information. +* [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests) + --- This is a dedicated package that defines tests for the [dependency + resolver](../architecture/packages.md#resolver). diff --git a/src/doc/contrib/src/architecture/compilation.md b/src/doc/contrib/src/architecture/compilation.md new file mode 100644 index 0000000..ecccee0 --- /dev/null +++ b/src/doc/contrib/src/architecture/compilation.md @@ -0,0 +1,39 @@ +# Compilation + +The [`Unit`] is the primary data structure representing a single execution of +the compiler. It (mostly) contains all the information needed to determine +which flags to pass to the compiler. + +The entry to the compilation process is located in the [`cargo_compile`] +module. The compilation can be conceptually broken into these steps: + +1. Perform dependency resolution (see [the resolution chapter]). +2. Generate the root `Unit`s, the things the user requested to compile on the + command-line. This is done in the [`unit_generator`] module. +3. Starting from the root `Unit`s, generate the [`UnitGraph`] by walking the + dependency graph from the resolver. The `UnitGraph` contains all of the + `Unit` structs, and information about the dependency relationships between + units. This is done in the [`unit_dependencies`] module. +4. Construct the [`BuildContext`] with all of the information collected so + far. This is the end of the "front end" of compilation. +5. Create a [`Context`], a large, mutable data structure that coordinates the + compilation process. +6. The [`Context`] will create a [`JobQueue`], a data structure that tracks + which units need to be built. +7. [`drain_the_queue`] does the compilation process. This is the only point in + Cargo that currently uses threads. +8. The result of the compilation is stored in the [`Compilation`] struct. This + can be used for various things, such as running tests after the compilation + has finished. + +[`cargo_compile`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs +[`unit_generator`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/unit_generator.rs +[`UnitGraph`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_graph.rs +[the resolution chapter]: packages.md +[`Unit`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit.rs +[`unit_dependencies`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_dependencies.rs +[`BuildContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs +[`Context`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs +[`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs +[`drain_the_queue`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/compiler/job_queue.rs#L623-L634 +[`Compilation`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/compilation.rs diff --git a/src/doc/contrib/src/architecture/console.md b/src/doc/contrib/src/architecture/console.md new file mode 100644 index 0000000..2c5412b --- /dev/null +++ b/src/doc/contrib/src/architecture/console.md @@ -0,0 +1,82 @@ +# Console Output + +All of Cargo's output should go through the [`Shell`] struct. You can normally +obtain the `Shell` instance from the [`Config`] struct. Do **not** use the std +`println!` macros. + +Most of Cargo's output goes to stderr. When running in JSON mode, the output +goes to stdout. + +It is important to properly handle errors when writing to the console. +Informational commands, like `cargo list`, should ignore any errors writing +the output. There are some [`drop_print`] macros that are intended to make +this easier. + +Messages written during compilation should handle errors, and abort the build +if they are unable to be displayed. This is generally automatically handled in +the [`JobQueue`] as it processes each message. + +[`Shell`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/shell.rs +[`Config`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs +[`drop_print`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1820-L1848 +[`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs + +## Errors + +Cargo uses [`anyhow`] for managing errors. This makes it convenient to "chain" +errors together, so that Cargo can report how an error originated, and what it +was trying to do at the time. + +Error helpers are implemented in the [`errors`] module. Use the +`InternalError` error type for errors that are not expected to happen. This +will print a message to the user to file a bug report. + +The binary side of Cargo uses the `CliError` struct to wrap the process exit +code. Usually Cargo exits with 101 for an error, but some commands like `cargo +test` will exit with different codes. + +[`errors`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/errors.rs + +## Style + +Some guidelines for Cargo's output: + +* Keep the normal output brief. Cargo is already fairly noisy, so try to keep + the output as brief and clean as possible. +* Good error messages are very important! Try to keep them brief and to the + point, but good enough that a beginner can understand what is wrong and can + figure out how to fix. It is a difficult balance to hit! Err on the side of + providing extra information. +* When using any low-level routines, such as `std::fs`, *always* add error + context about what it is doing. For example, reading from a file should + include context about which file is being read if there is an error. +* Cargo's error style is usually a phrase, starting with a lowercase letter. + If there is a longer error message that needs multiple sentences, go ahead + and use multiple sentences. This should probably be improved sometime in the + future to be more structured. + +## Debug logging + +Cargo uses the [`env_logger`] crate to display debug log messages. The +`CARGO_LOG` environment variable can be set to enable debug logging, with a +value such as `trace`, `debug`, or `warn`. It also supports filtering for +specific modules. Feel free to use the standard [`log`] macros to help with +diagnosing problems. + +```sh +# Outputs all logs with levels debug and higher +CARGO_LOG=debug cargo generate-lockfile + +# Don't forget that you can filter by module as well +CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile + +# This will print lots of info about the download process. `trace` prints even more. +CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch + +# This is an important command for diagnosing fingerprint issues. +CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build +``` + +[`env_logger`]: https://docs.rs/env_logger +[`log`]: https://docs.rs/log +[`anyhow`]: https://docs.rs/anyhow diff --git a/src/doc/contrib/src/architecture/files.md b/src/doc/contrib/src/architecture/files.md new file mode 100644 index 0000000..2e6e02b --- /dev/null +++ b/src/doc/contrib/src/architecture/files.md @@ -0,0 +1,67 @@ +# Files + +This chapter gives some pointers on where to start looking at Cargo's on-disk +data file structures. + +* [`Layout`] is the abstraction for the `target` directory. It handles locking + the target directory, and providing paths to the parts inside. There is a + separate `Layout` for each "target". +* [`Resolve`] contains the contents of the `Cargo.lock` file. See the [`encode`] + module for the different `Cargo.lock` formats. +* [`TomlManifest`] contains the contents of the `Cargo.toml` file. It is translated + to a [`Manifest`] object for some simplification, and the `Manifest` is stored + in a [`Package`]. +* The [`fingerprint`] module deals with the fingerprint information stored in + `target/debug/.fingerprint`. This tracks whether or not a crate needs to be + rebuilt. +* `cargo install` tracks its installed files with some metadata in + `$CARGO_HOME`. The metadata is managed in the + [`common_for_install_and_uninstall`] module. +* Git sources are cached in `$CARGO_HOME/git`. The code for this cache is in + the [`git`] source module. +* Registries are cached in `$CARGO_HOME/registry`. There are three parts, the + index, the compressed `.crate` files, and the extracted sources of those + crate files. + * Management of the registry cache can be found in the [`registry`] source + module. Note that this includes an on-disk cache as an optimization for + accessing the git repository. + * Saving of `.crate` files is handled by the [`RemoteRegistry`]. + * Extraction of `.crate` files is handled by the [`RegistrySource`]. + * There is a lock for the package cache. Code must be careful, because + this lock must be obtained manually. See + [`Config::acquire_package_cache_lock`]. + +[`Layout`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/layout.rs +[`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs +[`encode`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/encode.rs +[`TomlManifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/toml/mod.rs +[`Manifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs +[`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs +[`common_for_install_and_uninstall`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/common_for_install_and_uninstall.rs +[`git`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/git +[`registry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs +[`RemoteRegistry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/remote.rs +[`RegistrySource`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs +[`Config::acquire_package_cache_lock`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1261-L1266 + +## Filesystems + +Cargo tends to get run on a very wide array of file systems. Different file +systems can have a wide range of capabilities, and Cargo should strive to do +its best to handle them. Some examples of issues to deal with: + +* Not all file systems support locking. Cargo tries to detect if locking is + supported, and if not, will ignore lock errors. This isn't ideal, but it is + difficult to deal with. +* The [`fs::canonicalize`] function doesn't work on all file systems + (particularly some Windows file systems). If that function is used, there + should be a fallback if it fails. This function will also return `\\?\` + style paths on Windows, which can have some issues (such as some tools not + supporting them, or having issues with relative paths). +* Timestamps can be unreliable. The [`fingerprint`] module has a deeper + discussion of this. One example is that Docker cache layers will erase the + fractional part of the time stamp. +* Symlinks are not always supported, particularly on Windows. + +[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs +[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html diff --git a/src/doc/contrib/src/architecture/index.md b/src/doc/contrib/src/architecture/index.md new file mode 100644 index 0000000..fded5fc --- /dev/null +++ b/src/doc/contrib/src/architecture/index.md @@ -0,0 +1,8 @@ +# Architecture Overview + +This chapter gives a very high-level overview of Cargo's architecture. This is +intended to give you links into the code which is hopefully commented with +more in-depth information. + +If you feel something is missing that would help you, feel free to ask on +Zulip. diff --git a/src/doc/contrib/src/architecture/packages.md b/src/doc/contrib/src/architecture/packages.md new file mode 100644 index 0000000..626714b --- /dev/null +++ b/src/doc/contrib/src/architecture/packages.md @@ -0,0 +1,92 @@ +# Packages and Resolution + +## Workspaces + +The [`Workspace`] object is usually created very early by calling the +[`workspace`][ws-method] helper method. This discovers the root of the +workspace, and loads all the workspace members as a [`Package`] object. Each +package corresponds to a single `Cargo.toml` (which is deserialized into a +[`Manifest`]), and may define several [`Target`]s, such as the library, +binaries, integration test or examples. Targets are crates (each target +defines a crate root, like `src/lib.rs` or `examples/foo.rs`) and are what is +actually compiled by `rustc`. + +## Packages and Sources + +There are several data structures that are important to understand how +packages are found and loaded: + +* [`Package`] --- A package, which is a `Cargo.toml` manifest and its associated + source files. + * [`PackageId`] --- A unique identifier for a package. +* [`Source`] --- An abstraction for something that can fetch packages (a remote + registry, a git repo, the local filesystem, etc.). Check out the [source + implementations] for all the details about registries, indexes, git + dependencies, etc. + * [`SourceId`] --- A unique identifier for a source. +* [`SourceMap`] --- Map of all available sources. +* [`PackageRegistry`] --- This is the main interface for how the dependency + resolver finds packages. It contains the `SourceMap`, and handles things + like the `[patch]` table. The `Registry` trait provides a generic interface + to the `PackageRegistry`, but this is only used for providing an alternate + implementation of the `PackageRegistry` for testing. The dependency resolver + sends a query to the `PackageRegistry` to "get me all packages that match + this dependency declaration". +* [`Summary`] --- A summary is a subset of a [`Manifest`], and is essentially + the information that can be found in a registry index. Queries against the + `PackageRegistry` yields a `Summary`. The resolver uses the summary + information to build the dependency graph. +* [`PackageSet`] --- Contains all of the `Package` objects. This works with the + [`Downloads`] struct to coordinate downloading packages. It has a reference + to the `SourceMap` to get the `Source` objects which tell the `Downloads` + struct which URLs to fetch. + +All of these come together in the [`ops::resolve`] module. This module +contains the primary functions for performing resolution (described below). It +also handles downloading of packages. It is essentially where all of the data +structures above come together. + +## Resolver + +[`Resolve`] is the representation of a directed graph of package dependencies, +which uses [`PackageId`]s for nodes. This is the data structure that is saved +to the `Cargo.lock` file. If there is no lock file, Cargo constructs a resolve +by finding a graph of packages which matches declared dependency specification +according to SemVer. + +[`ops::resolve`] is the front-end for creating a `Resolve`. It handles loading +the `Cargo.lock` file, checking if it needs updating, etc. + +Resolution is currently performed twice. It is performed once with all +features enabled. This is the resolve that gets saved to `Cargo.lock`. It then +runs again with only the specific features the user selected on the +command-line. Ideally this second run will get removed in the future when +transitioning to the new feature resolver. + +### Feature resolver + +A new feature-specific resolver was added in 2020 which adds more +sophisticated feature resolution. It is located in the [`resolver::features`] +module. The original dependency resolver still performs feature unification, +as it can help reduce the dependencies it has to consider during resolution +(rather than assuming every optional dependency of every package is enabled). +Checking if a feature is enabled must go through the new feature resolver. + + +[`Workspace`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/workspace.rs +[ws-method]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/command_prelude.rs#L298-L318 +[`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs +[`Target`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/manifest.rs#L181-L206 +[`Manifest`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/manifest.rs#L27-L51 +[`Source`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/source/mod.rs +[`SourceId`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/source/source_id.rs +[`SourceMap`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/source/mod.rs#L245-L249 +[`PackageRegistry`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/registry.rs#L36-L81 +[`ops::resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/resolve.rs +[`resolver::features`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/features.rs#L259 +[source implementations]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources +[`PackageId`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package_id.rs +[`Summary`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/summary.rs +[`PackageSet`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/package.rs#L283-L296 +[`Downloads`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/package.rs#L298-L352 +[`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs diff --git a/src/doc/contrib/src/architecture/subcommands.md b/src/doc/contrib/src/architecture/subcommands.md new file mode 100644 index 0000000..bdb586c --- /dev/null +++ b/src/doc/contrib/src/architecture/subcommands.md @@ -0,0 +1,25 @@ +# SubCommands + +Cargo is a single binary composed of a set of [`clap`] subcommands. All +subcommands live in [`src/bin/cargo/commands`] directory. +[`src/bin/cargo/main.rs`] is the entry point. + +Each subcommand, such as [`src/bin/cargo/commands/build.rs`], usually performs +the following: + +1. Parse the CLI flags. See the [`command_prelude`] module for some helpers to make this easier. +2. Load the config files. +3. Discover and load the workspace. +4. Calls the actual implementation of the subcommand which resides in [`src/cargo/ops`]. + +If the subcommand is not found in the built-in list, then Cargo will +automatically search for a subcommand named `cargo-{NAME}` in the users `PATH` +to execute the subcommand. + + +[`clap`]: https://clap.rs/ +[`src/bin/cargo/commands/build.rs`]: https://github.com/rust-lang/cargo/tree/master/src/bin/cargo/commands/build.rs +[`src/cargo/ops`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/ops +[`src/bin/cargo/commands`]: https://github.com/rust-lang/cargo/tree/master/src/bin/cargo/commands +[`src/bin/cargo/main.rs`]: https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/main.rs +[`command_prelude`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/command_prelude.rs diff --git a/src/doc/contrib/src/design.md b/src/doc/contrib/src/design.md new file mode 100644 index 0000000..d51d3eb --- /dev/null +++ b/src/doc/contrib/src/design.md @@ -0,0 +1,101 @@ +# Design Principles + +The purpose of Cargo is to formalize a canonical Rust workflow, by automating +the standard tasks associated with distributing software. Cargo simplifies +structuring a new project, adding dependencies, writing and running unit +tests, and more. + +Cargo is not intended to be a general-purpose build tool. Ideally, it should +be easy to integrate it within another build tool, though admittedly that is +not as seamless as desired. + +## Stability and compatibility + +### Backwards compatibility + +Cargo strives to remain backwards compatible with projects created in previous +versions. The CLI interface also strives to remain backwards compatible, such +that the commands and options behave the same. That being said, changes in +behavior, and even outright breakage are sometimes done in limited situations. +The following outlines some situations where backwards-incompatible changes are +made: + +* Anything that addresses a security concern. +* Dropping support for older platforms and tooling. Cargo follows the Rust + [tiered platform support]. +* Changes to resolve possibly unsafe or unreliable behavior. + +None of these changes should be taken lightly, and should be avoided if +possible, or possibly with some transition period to alert the user of the +potential change. + +Behavior is sometimes changed in ways that have a high confidence that it +won't break existing workflows. Almost every change carries this risk, so it +is often a judgment call balancing the benefit of the change with the +perceived possibility of its negative consequences. + +At times, some changes fall in the gray area, where the current behavior is +undocumented, or not working as intended. These are more difficult judgment +calls. The general preference is to balance towards avoiding breaking existing +workflows. + +Support for older registry APIs and index formats may be dropped, if there is +high confidence that there aren't any active registries that may be affected. +This has never (to my knowledge) happened so far, and is unlikely to happen in +the future, but remains a possibility. + +In all of the above, a transition period may be employed if a change is known +to cause breakage. A warning can be issued to alert the user that something +will change, and provide them with an alternative to resolve the issue +(preferably in a way that is compatible across versions if possible). + +Cargo is only expected to work with the version of the related Rust tools +(`rustc`, `rustdoc`, etc.) that it is released with. As a matter of choice, +the latest nightly works with the most recent stable release, but that is +mostly to accommodate development of Cargo itself, and should not be expected +by users. + +### Forwards compatibility + +Additionally, Cargo strives a limited degree of *forwards compatibility*. +Changes should not egregiously prevent older versions from working. This is +mostly relevant for persistent data, such as on-disk files and the registry +interface and index. It also applies to a lesser degree to the registry API. + +Changes to `Cargo.lock` require a transition time, where the new format is not +automatically written when the lock file is updated. The transition time +should not be less than 6 months, though preferably longer. New projects may +use the new format in a shorter time frame. + +Changes to `Cargo.toml` can be made in any release. This is because the user +must manually modify the file, and opt-in to any new changes. Additionally, +Cargo will usually only issue a warning about new fields it doesn't +understand, but otherwise continue to function. + +Changes to cache files (such as artifacts in the `target` directory, or cached +data in Cargo's home directory) should not *prevent* older versions from +running, but they may cause older versions to recreate the cache, which may +result in a performance impact. + +Changes to the registry index should not prevent older versions from working. +Generally, older versions ignore new fields, so the format should be easily +extensible. Changes to the format or interpretation of existing fields should +be done very carefully to avoid preventing older versions of Cargo from +working. In some cases, this may mean that older versions of Cargo will not be +able to *select* a newly published crate, but it shouldn't prevent them from +working at all. This level of compatibility may not last forever, but the +exact time frame for such a change has not yet been decided. + +The registry API may be changed in such a way to prevent older versions of +Cargo from working. Generally, compatibility should be retained for as long as +possible, but the exact length of time is not specified. + +## Simplicity and layers + +Standard workflows should be easy and consistent. Each knob that is added has +a high cost, regardless if it is intended for a small audience. Layering and +defaults can help avoid the surface area that the user needs to be concerned +with. Try to avoid small functionalities that may have complex interactions +with one another. + +[tiered platform support]: https://doc.rust-lang.org/nightly/rustc/platform-support.html diff --git a/src/doc/contrib/src/index.md b/src/doc/contrib/src/index.md new file mode 100644 index 0000000..5ab169e --- /dev/null +++ b/src/doc/contrib/src/index.md @@ -0,0 +1,29 @@ +# Introduction + +Thank you for your interest in contributing to [Cargo]! This guide provides an +overview of how to contribute to Cargo, how to dive into the code, and how the +testing infrastructure works. + +There are many ways to contribute, such as [helping other users], [filing +issues], [improving the documentation], [fixing bugs], and working on [small] +and [large features]. + +If you have a general question about Cargo or its internals, feel free to ask +on [Zulip]. + +This guide assumes you have some familiarity with Rust, and how to use Cargo, +[rustup], and general development tools like [git]. + +Please also read the [Rust Code of Conduct]. + +[Cargo]: https://doc.rust-lang.org/cargo/ +[Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo +[Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct +[helping other users]: https://users.rust-lang.org/ +[filing issues]: issues.md +[rustup]: https://rust-lang.github.io/rustup/ +[git]: https://git-scm.com/ +[improving the documentation]: https://github.com/rust-lang/cargo/tree/master/src/doc +[fixing bugs]: process/index.md#working-on-small-bugs +[small]: process/index.md#working-on-small-features +[large features]: process/index.md#working-on-large-features diff --git a/src/doc/contrib/src/issues.md b/src/doc/contrib/src/issues.md new file mode 100644 index 0000000..8fc6954 --- /dev/null +++ b/src/doc/contrib/src/issues.md @@ -0,0 +1,109 @@ +# Issue Tracker + +Cargo's issue tracker is located at +<https://github.com/rust-lang/cargo/issues/>. This is the primary spot where +we track bugs and small feature requests. See [Process] for more about our +process for proposing changes. + +## Filing issues + +We can't fix what we don't know about, so please report problems liberally. +This includes problems with understanding the documentation, unhelpful error +messages, and unexpected behavior. + +**If you think that you have identified an issue with Cargo that might +compromise its users' security, please do not open a public issue on GitHub. +Instead, we ask you to refer to Rust's [security policy].** + +Opening an issue is as easy as following [this link][new-issues]. There are +several templates for different issue kinds, but if none of them fit your +issue, don't hesitate to modify one of the templates, or click the [Open a +blank issue] link. + +The Rust tools are spread across multiple repositories in the Rust +organization. It may not always be clear where to file an issue. No worries! +If you file in the wrong tracker, someone will either transfer it to the +correct one or ask you to move it. Some other repositories that may be +relevant are: + +* [`rust-lang/rust`] --- Home for the [`rustc`] compiler and [`rustdoc`]. +* [`rust-lang/rustup`] --- Home for the [`rustup`] toolchain installer. +* [`rust-lang/rustfmt`] --- Home for the `rustfmt` tool, which also includes `cargo fmt`. +* [`rust-lang/rust-clippy`] --- Home for the `clippy` tool, which also includes `cargo clippy`. +* [`rust-lang/crates.io`] --- Home for the [crates.io] website. + +Issues with [`cargo fix`] can be tricky to know where they should be filed, +since the fixes are driven by `rustc`, processed by [`rustfix`], and the +front-interface is implemented in Cargo. Feel free to file in the Cargo issue +tracker, and it will get moved to one of the other issue trackers if +necessary. + +[Process]: process/index.md +[security policy]: https://www.rust-lang.org/security.html +[new-issues]: https://github.com/rust-lang/cargo/issues/new/choose +[Open a blank issue]: https://github.com/rust-lang/cargo/issues/new +[`rust-lang/rust`]: https://github.com/rust-lang/rust +[`rust-lang/rustup`]: https://github.com/rust-lang/rustup +[`rust-lang/rustfmt`]: https://github.com/rust-lang/rustfmt +[`rust-lang/rust-clippy`]: https://github.com/rust-lang/rust-clippy +[`rustc`]: https://doc.rust-lang.org/rustc/ +[`rustdoc`]: https://doc.rust-lang.org/rustdoc/ +[`rustup`]: https://rust-lang.github.io/rustup/ +[`rust-lang/crates.io`]: https://github.com/rust-lang/crates.io +[crates.io]: https://crates.io/ +[`rustfix`]: https://github.com/rust-lang/rustfix/ +[`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html + +## Issue labels + +[Issue labels] are very helpful to identify the types of issues and which +category they are related to. The Cargo team typically manages assigning +labels. The labels use a naming convention with short prefixes and colors to +indicate the kind of label: + +* Yellow, **A**-prefixed labels state which **area** of the project an issue + relates to. + +* Light purple, **C**-prefixed labels represent the **category** of an issue. + In particular, **[C-feature-request]** marks *proposals* for new features. If + an issue is **C-feature-request**, but is not **[Feature accepted]** or + **[I-nominated]**, then it was not thoroughly discussed, and might need some + additional design or perhaps should be implemented as an external subcommand + first. Ping @rust-lang/cargo if you want to send a PR for such issue. + +* Dark purple, **Command**-prefixed labels mean the issue has to do with a + specific cargo command. + +* Green, **E**-prefixed labels indicate the level of **experience** or + **effort** necessary to fix the issue. **[E-mentor]** issues also + have some instructions on how to get started. Generally, all of the + **E**-prefixed labels are issues that are ready for someone to contribute + to! + +* Red, **I**-prefixed labels indicate the **importance** of the issue. The + **[I-nominated]** label indicates that an issue has been nominated for + prioritizing at the next triage meeting. + +* Purple gray, **O**-prefixed labels are the **operating system** or platform + that this issue is specific to. + +* Orange, **P**-prefixed labels indicate a bug's **priority**. + +* **S**-prefixed labels are "status" labels, typically used for PRs, but can + also indicate an issue is **[S-blocked]**. + +* The light orange **[relnotes]** label marks issues that should be highlighted + in the [Rust release notes] of the next release. + +* Dark blue, **Z**-prefixed labels are for unstable, [nightly features]. + +[Issue labels]: https://github.com/rust-lang/cargo/labels +[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy +[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor +[I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated +[C-feature-request]: https://github.com/rust-lang/cargo/labels/C-feature-request +[Feature accepted]: https://github.com/rust-lang/cargo/labels/Feature%20accepted +[S-blocked]: https://github.com/rust-lang/cargo/labels/S-blocked +[Rust release notes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md +[nightly features]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html +[relnotes]: https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes diff --git a/src/doc/contrib/src/process/index.md b/src/doc/contrib/src/process/index.md new file mode 100644 index 0000000..af0f030 --- /dev/null +++ b/src/doc/contrib/src/process/index.md @@ -0,0 +1,129 @@ +# Process + +This chapter gives an overview of how Cargo comes together, and how you can be +a part of that process. + +See the [Working on Cargo] chapter for an overview of the contribution +process. + +Please read the guidelines below before working on an issue or new feature. + +**Due to limited review capacity, the Cargo team is not accepting new features +or major changes at this time. Please consult with the team before opening a +new PR. Only issues that have been explicitly marked as accepted will be +reviewed.** + +[Working on Cargo]: working-on-cargo.md + +## Cargo team + +Cargo is managed by a [team] of volunteers. The Cargo Team reviews all +changes, and sets the direction for the project. + +The team meets on a weekly basis on a video chat. If you are interested in +participating, feel free to contact us on [Zulip]. + +## Roadmap + +The [Roadmap Project Board] is used for tracking major initiatives. This gives +an overview of the things the team is interested in and thinking about. + +The [RFC Project Board] is used for tracking [RFCs]. + +[the 2020 roadmap]: https://blog.rust-lang.org/inside-rust/2020/01/10/cargo-in-2020.html +[Roadmap Project Board]: https://github.com/rust-lang/cargo/projects/1 +[RFC Project Board]: https://github.com/rust-lang/cargo/projects/2 +[RFCs]: https://github.com/rust-lang/rfcs/ + +## Working on small bugs + +Issues labeled with the [E-help-wanted], [E-easy], or [E-mentor] [labels] are +typically issues that the Cargo team wants to see addressed, and are +relatively easy to get started with. If you are interested in one of those, +and it has not already been assigned to someone, leave a comment. See [Issue +assignment](#issue-assignment) below for assigning yourself. + +If there is a specific issue that you are interested in, but it doesn't have +one of the `E-` labels, leave a comment on the issue. If a Cargo team member +has the time to help out, they will respond to help with the next steps. + +[E-help-wanted]: https://github.com/rust-lang/cargo/labels/E-help-wanted +[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy +[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor +[labels]: ../issues.md#issue-labels + +## Working on large bugs + +Some issues may be difficult to fix. They may require significant code +changes, or major design decisions. The [E-medium] and [E-hard] [labels] can +be used to tag such issues. These will typically involve some discussion with +the Cargo team on how to tackle it. + +[E-medium]: https://github.com/rust-lang/cargo/labels/E-medium +[E-hard]: https://github.com/rust-lang/cargo/labels/E-hard + +## Working on small features + +Small feature requests are typically managed on the [issue +tracker][issue-feature-request]. Features that the Cargo team have approved +will have the [Feature accepted] label or the [E-mentor] label. If there is a +feature request that you are interested in, feel free to leave a comment +expressing your interest. If a Cargo team member has the time to help out, +they will respond to help with the next steps. Keep in mind that the Cargo +team has limited time, and may not be able to help with every feature request. +Most of them require some design work, which can be difficult. Check out the +[design principles chapter] for some guidance. + +## Working on large features + +Cargo follows the Rust model of evolution. Major features usually go through +an [RFC process]. Therefore, before opening a feature request issue create a +Pre-RFC thread on the [internals][irlo] forum to get preliminary feedback. + +Implementing a feature as a [custom subcommand][subcommands] is encouraged as +it helps demonstrate the demand for the functionality and is a great way to +deliver a working solution faster as it can iterate outside of Cargo's release +cadence. + +See the [unstable chapter] for how new major features are typically +implemented. + +[unstable chapter]: unstable.md + +## Bots and infrastructure + +The Cargo project uses several bots: + +* [GitHub Actions] are used to automatically run all tests for each PR. +* [triagebot] automatically assigns reviewers for PRs, see [Assignment] for + how to configure. +* [bors] is used to merge PRs. See [The merging process]. +* [triagebot] is used for assigning issues to non-members, see [Issue + assignment](#issue-assignment). +* [rfcbot] is used for making asynchronous decisions by team members. + +[bors]: https://buildbot2.rust-lang.org/homu/ +[The merging process]: working-on-cargo.md#the-merging-process +[GitHub Actions]: https://github.com/features/actions +[triagebot]: https://github.com/rust-lang/triagebot/wiki +[rfcbot]: https://github.com/rust-lang/rfcbot-rs +[Assignment]: https://github.com/rust-lang/triagebot/wiki/Assignment + +## Issue assignment + +Normally, if you plan to work on an issue that has been marked with one of the +`E-` tags or [Feature accepted], it is sufficient just to leave a comment that +you are working on it. We also have a bot that allows you to formally "claim" +an issue by entering the text `@rustbot claim` in a comment. See the +[Assignment] docs on how this works. + + +[Assignment]: https://github.com/rust-lang/triagebot/wiki/Assignment +[team]: https://www.rust-lang.org/governance/teams/dev-tools#cargo +[Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo +[issue-feature-request]: https://github.com/rust-lang/cargo/labels/C-feature-request +[Feature accepted]: https://github.com/rust-lang/cargo/labels/Feature%20accepted +[design principles chapter]: ../design.md +[RFC process]: https://github.com/rust-lang/rfcs/ +[irlo]: https://internals.rust-lang.org/ +[subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands diff --git a/src/doc/contrib/src/process/release.md b/src/doc/contrib/src/process/release.md new file mode 100644 index 0000000..0307410 --- /dev/null +++ b/src/doc/contrib/src/process/release.md @@ -0,0 +1,164 @@ +# Release process + +Cargo is released with `rustc` using a ["train model"][choochoo]. After a +change lands in Cargo's master branch, it will be synced with the +[rust-lang/rust] repository by a Cargo team member, which happens about once a +week. If there are complications, it can take longer. After it is synced and +merged, the changes will appear in the next nightly release, which is usually +published around 00:30 UTC. + +After changes are in the nightly release, they will make their way to the +stable release anywhere from 6 to 12 weeks later, depending on when during the +cycle it landed. + +The current release schedule is posted on the [Rust Forge]. See the [release +process] for more details on how Rust's releases are created. Rust releases +are managed by the [Release team]. + +[Rust Forge]: https://forge.rust-lang.org/ + +## Build process + +The build process for Cargo is handled as part of building Rust. Every PR on +the [rust-lang/rust] repository creates a full collection of release artifacts +for every platform. The code for this is in the [`dist` bootstrap module]. +Every night at 00:00 UTC, the artifacts from the most recently merged PR are +promoted to the nightly release channel. A similar process happens for beta +and stable releases. + +[`dist` bootstrap module]: https://github.com/rust-lang/rust/blob/master/src/bootstrap/dist.rs + +## Submodule updates + +Cargo is tracked in the [rust-lang/rust] repository using a [git submodule]. +It is updated manually about once a week by a Cargo team member. +However, anyone is welcome to update it as needed. + +[@ehuss] has a tool called [subup](https://github.com/ehuss/subup) to automate the process of updating the submodule, updating the lockfile, running tests, and creating a PR. +Running the tests ahead-of-time helps avoid long cycle times waiting for bors if there are any errors. +Subup will also provide a message to include in the PR with a list of all PRs it covers. +Posting this in the PR message also helps create reference links on each Cargo PR to the submodule update PR to help track when it gets merged. + +The following is an example of the command to run in a local clone of rust-lang/rust to run a certain set of tests of things that are likely to get broken by a Cargo update: + +```bash +subup --up-branch update-cargo \ + --commit-message "Update cargo" \ + --test="src/tools/linkchecker tidy \ + src/tools/cargo \ + src/tools/rustfmt \ + src/tools/cargo +``` + +If doing a [beta backport](#beta-backports), the command is similar, but needs to point to the correct branches: + +```bash +subup --up-branch update-beta-cargo \ + --rust-branch beta \ + --set-config rust.channel=beta \ + --commit-message "[beta] Update cargo" \ + --test="src/tools/linkchecker tidy \ + src/tools/cargo \ + src/tools/rustfmt \ + rust-1.66.0:src/tools/cargo +``` + +[@ehuss]: https://github.com/ehuss/ +[git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules + +## Version updates + +Shortly after each major release, a Cargo team member will post a PR to update +Cargo's version in `Cargo.toml`. Cargo's library is permanently unstable, so +its version number starts with a `0`. The minor version is always 1 greater +than the Rust release it is a part of, so cargo 0.49.0 is part of the 1.48 +Rust release. The [CHANGELOG] is also usually updated at this time. + +Also, any version-specific checks that are no longer needed can be removed. +For example, some tests are disabled on stable if they require some nightly +behavior. Once that behavior is available on the new stable release, the +checks are no longer necessary. (I usually search for the word "nightly" in +the testsuite directory, and read the comments to see if any of those nightly +checks can be removed.) + +Sometimes Cargo will have a runtime check to probe `rustc` if it supports a +specific feature. This is usually stored in the [`TargetInfo`] struct. If this +behavior is now stable, those checks should be removed. + +Cargo has several other packages in the [`crates/` directory]. If any of these +packages have changed, the version should be bumped **before the beta +release**. It is rare that these get updated. Bumping these as-needed helps +avoid churning incompatible version numbers. This process should be improved +in the future! + +[@ehuss] has a tool called [cargo-new-release] to automate the process of doing a version bump. +It runs through several steps: +1. Creates a branch +2. Updates the version numbers +3. Creates a changelog for anything on the master branch that is not part of beta +4. Creates a changelog for anything on the beta branch + +It opens a browser tab for every PR in order to review each change. +It places each PR in the changelog with its title, but usually every PR should be rewritten to explain the change from the user's perspective. +Each PR should also be categorized as an Addition, Change, Fix, or Nightly-only change. +Most PRs are deleted, since they are not relevant to users of Cargo. +For example, remove all PRs related to Cargo internals, infrastructure, documentation, error changes, refactorings, etc. +Usually about half of the PRs get removed. +This process usually takes @ehuss about an hour to finish. + +[@ehuss]: https://github.com/ehuss/ +[cargo-new-release]: https://github.com/ehuss/cargo-new-release +[`crates/` directory]: https://github.com/rust-lang/cargo/tree/master/crates + +## Docs publishing + +Docs are automatically published during the Rust release process. The nightly +channel's docs appear at <https://doc.rust-lang.org/nightly/cargo/>. Once +nightly is promoted to beta, those docs will appear at +<https://doc.rust-lang.org/beta/cargo/>. Once the stable release is made, it +will appear on <https://doc.rust-lang.org/cargo/> (which is the "current" +stable) and the release-specific URL such as +<https://doc.rust-lang.org/1.46.0/cargo/>. + +The code that builds the documentation is located in the [`doc` bootstrap +module]. + +[`doc` bootstrap module]: https://github.com/rust-lang/rust/blob/master/src/bootstrap/doc.rs + +## crates.io publishing + +Cargo's library is published to [crates.io] as part of the stable release +process. This is handled by the [Release team] as part of their process. There +is a [`publish.py` script] that in theory should help with this process. The +test and build tool crates aren't published. + +[`publish.py` script]: https://github.com/rust-lang/cargo/blob/master/publish.py + +## Beta backports + +If there is a regression or major problem detected during the beta phase, it +may be necessary to backport a fix to beta. The process is documented in the +[Beta Backporting] page. + +[Beta Backporting]: https://forge.rust-lang.org/release/beta-backporting.html + +## Stable backports + +In (hopefully!) very rare cases, a major regression or problem may be reported +after the stable release. Decisions about this are usually coordinated between +the [Release team] and the Cargo team. There is usually a high bar for making +a stable patch release, and the decision may be influenced by whether or not +there are other changes that need a new stable release. + +The process here is similar to the beta-backporting process. The +[rust-lang/cargo] branch is the same as beta (`rust-1.XX.0`). The +[rust-lang/rust] branch is called `stable`. + +[choochoo]: https://doc.rust-lang.org/book/appendix-07-nightly-rust.html +[rust-lang/rust]: https://github.com/rust-lang/rust/ +[rust-lang/cargo]: https://github.com/rust-lang/cargo/ +[CHANGELOG]: https://github.com/rust-lang/cargo/blob/master/CHANGELOG.md +[release process]: https://forge.rust-lang.org/release/process.html +[`TargetInfo`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/target_info.rs +[crates.io]: https://crates.io/ +[release team]: https://www.rust-lang.org/governance/teams/operations#release diff --git a/src/doc/contrib/src/process/unstable.md b/src/doc/contrib/src/process/unstable.md new file mode 100644 index 0000000..d59b9aa --- /dev/null +++ b/src/doc/contrib/src/process/unstable.md @@ -0,0 +1,105 @@ +# Unstable features + +Most new features should go through the unstable process. This means that the +feature will only be usable on the nightly channel, and requires a specific +opt-in by the user. Small changes can skip this process, but please consult +with the Cargo team first. + +## Unstable feature opt-in + +For features that require behavior changes or new syntax in `Cargo.toml`, then +it will need a `cargo-features` value placed at the top of `Cargo.toml` to +enable it. The process for doing adding a new feature is described in the +[`features` module]. Code that implements the feature will need to manually +check that the feature is enabled for the current manifest. + +For features that add new command-line flags, config options, or environment +variables, then the `-Z` flags will be needed to enable them. The [`features` +module] also describes how to add these. New flags should use the +`fail_if_stable_opt` method to check if the `-Z unstable-options` flag has +been passed. + +## Unstable documentation + +Every unstable feature should have a section added to the [unstable chapter] +describing how to use the feature. + +[unstable chapter]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md + +## Tracking issues + +Each unstable feature should get a [tracking issue]. These issues are +typically created when a PR is close to being merged, or soon after it is +merged. Use the [tracking issue template] when creating a tracking issue. + +Larger features should also get a new label in the issue tracker so that when +issues are filed, they can be easily tied together. + +[tracking issue]: https://github.com/rust-lang/cargo/labels/C-tracking-issue +[tracking issue template]: https://github.com/rust-lang/cargo/issues/new?labels=C-tracking-issue&template=tracking_issue.md + +## Pre-Stabilization + +Once an unstable feature is "complete", the search for users to test +and give feedback begins. Testing notes should be written up to give users an +idea of how to test the new feature. An example being the +[workspace inheritance testing notes] for workspace inheritance. Once testing +notes have been written up you should make posts in various rust communities +([rust subreddit], [users], [internals], etc). Example posts made for workspace +inheritance: [reddit post], [users post], [internals post]. The unstable feature +should also be added to [This Week in Rust]. This should be done by adding the +label `call-for-testing` to the RFC for the feature and making a comment with a +link to the testing notes and the tracking issue (as needed). If there is not an +RFC, a pull request should be made to the [TWiR repo] adding the feature to the +`Call for Testing` section ([example]). + +[workspace inheritance testing notes]: https://github.com/rust-lang/cargo/blob/6d6dd9d9be9c91390da620adf43581619c2fa90e/src/doc/src/reference/unstable.md#testing-notes +[rust subreddit]: https://www.reddit.com/r/rust/ +[users]: https://users.rust-lang.org/ +[internals]: https://internals.rust-lang.org/ +[reddit post]: https://www.reddit.com/r/rust/comments/uo8zeh/help_test_workspace_inheritance_in_preparation/ +[users post]: https://users.rust-lang.org/t/help-test-workspace-inheritance-in-preparation-for-stablization/75582 +[internals post]: https://internals.rust-lang.org/t/help-test-workspace-inheritance-in-preparation-for-stablization/16618 +[This Week in Rust]: https://this-week-in-rust.org/ +[TWiR repo]: https://github.com/rust-lang/this-week-in-rust +[example]: https://github.com/rust-lang/this-week-in-rust/pull/3256 + +## Stabilization + +After some period of time, typically measured in months, the feature can be +considered to be stabilized. The feature should not have any significant known +bugs or issues, and any design concerns should be resolved. + +The stabilization process depends on the kind of feature. For smaller +features, you can leave a comment on the tracking issue expressing interest in +stabilizing it. It can usually help to indicate that the feature has received +some real-world testing, and has exhibited some demand for broad use. + +For larger features that have not gone through the [RFC process], then an RFC +to call for stabilization might be warranted. This gives the community a final +chance to provide feedback about the proposed design. + +For a small feature, or one that has already gone through the RFC process, a +Cargo Team member may decide to call for a "final comment period" using +[rfcbot]. This is a public signal that a major change is being made, and gives +the Cargo Team members an opportunity to confirm or block the change. This +process can take a few days or weeks, or longer if a concern is raised. + +Once the stabilization has been approved, the person who called for +stabilization should prepare a PR to stabilize the feature. This PR should: + +* Flip the feature to stable in the [`features` module]. +* Remove any unstable checks that aren't automatically handled by the feature + system. +* Move the documentation from the [unstable chapter] into the appropriate + places in the Cargo book and man pages. +* Remove the `-Z` flags and help message if applicable. +* Update all tests to remove nightly checks. +* Tag the PR with [relnotes] label if it seems important enough to highlight + in the [Rust release notes]. + +[`features` module]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/features.rs +[RFC process]: https://github.com/rust-lang/rfcs/ +[rfcbot]: https://github.com/rust-lang/rfcbot-rs +[Rust release notes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md +[relnotes]: https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes diff --git a/src/doc/contrib/src/process/working-on-cargo.md b/src/doc/contrib/src/process/working-on-cargo.md new file mode 100644 index 0000000..e90bb85 --- /dev/null +++ b/src/doc/contrib/src/process/working-on-cargo.md @@ -0,0 +1,172 @@ +# Working on Cargo + +This chapter gives an overview of how to build Cargo, make a change, and +submit a Pull Request. + +0. [Before hacking on Cargo.](#before-hacking-on-cargo) +1. [Check out the Cargo source.](#checkout-out-the-source) +2. [Building Cargo.](#building-cargo) +3. [Making a change.](#making-a-change) +4. [Writing and running tests.](../tests/index.md) +5. [Submitting a Pull Request.](#submitting-a-pull-request) +6. [The merging process.](#the-merging-process) + +## Before hacking on Cargo + +We encourage people to discuss their design before hacking on code. This gives +the Cargo team a chance to know your idea more. Sometimes after a discussion, +we even find a way to solve the problem without coding! Typically, you +[file an issue] or start a thread on the [internals forum] before submitting a +pull request. Please read [the process] of how features and bugs are managed in +Cargo. + +## Checkout out the source + +We use the "fork and pull" model [described here][development-models], where +contributors push changes to their personal fork and [create pull requests] to +bring those changes into the source repository. Cargo uses [git] and [GitHub] +for all development. + +1. Fork the [`rust-lang/cargo`] repository on GitHub to your personal account + (see [GitHub docs][how-to-fork]). +2. Clone your fork to your local machine using `git clone` (see [GitHub + docs][how-to-clone]) +3. It is recommended to start a new branch for the change you want to make. + All Pull Requests are made against the master branch. + +## Building Cargo + +Cargo is built by...running `cargo`! There are a few prerequisites that you +need to have installed: + +* `rustc` and `cargo` need to be installed. Cargo is expected to build and + test with the current stable, beta, and nightly releases. It is your choice + which to use. Nightly is recommended, since some nightly-specific tests are + disabled when using the stable release. But using stable is fine if you + aren't working on those. +* A C compiler (typically gcc, clang, or MSVC). +* [git] +* Unix: + * pkg-config + * OpenSSL (`libssl-dev` on Ubuntu, `openssl-devel` on Fedora) +* macOS: + * OpenSSL ([homebrew] is recommended to install the `openssl` package) + +If you can successfully run `cargo build`, you should be good to go! + +[homebrew]: https://brew.sh/ + +## Running Cargo + +You can use `cargo run` to run cargo itself, or you can use the path directly +to the cargo binary, such as `target/debug/cargo`. + +If you are using [`rustup`], beware that running the binary directly can cause +issues with rustup overrides. Usually, when `cargo` is executed as part of +rustup, the toolchain becomes sticky (via an environment variable), and all +calls to `rustc` will use the same toolchain. But when `cargo` is not run via +rustup, the toolchain may change based on the directory. Since Cargo changes +the directory for each compilation, this can cause different calls to `rustc` +to use different versions. There are a few workarounds: + +* Don't use rustup overrides. +* Use `rustup run target/debug/cargo` to execute `cargo`. +* Set the `RUSTC` environment variable to a specific `rustc` executable (not + the rustup wrapper). +* Create a [custom toolchain]. This is a bit of a hack, but you can create a + directory in the rustup `toolchains` directory, and create symlinks for all + the files and directories in there to your toolchain of choice (such as + nightly), except for the `cargo` binary, which you can symlink to your + `target/debug/cargo` binary in your project directory. + +*Normally*, all development is done by running Cargo's test suite, so running +it directly usually isn't required. But it can be useful for testing Cargo on +more complex projects. + +[`rustup`]: https://rust-lang.github.io/rustup/ +[custom toolchain]: https://rust-lang.github.io/rustup/concepts/toolchains.html#custom-toolchains + +## Making a change + +Some guidelines on working on a change: + +* All code changes are expected to comply with the formatting suggested by + `rustfmt`. You can use `rustup component add rustfmt` to install `rustfmt` + and use `cargo fmt` to automatically format your code. +* Include tests that cover all non-trivial code. See the [Testing chapter] for + more about writing and running tests. +* All code should be warning-free. This is checked during tests. + +## Submitting a Pull Request + +After you have committed your work, and pushed it to GitHub, you can +open a Pull Request + +* Push your commits to GitHub and create a pull request against Cargo's + `master` branch. +* Include a clear description of what the change is and why it is being made. +* Use [GitHub's keywords] in the description to automatically link to an issue + if the PR resolves the issue. For example `Closes #1234` will link issue + #1234 to the PR. When the PR is merged, GitHub will automatically close the + issue. + +[`@rustbot`] will automatically assign a reviewer for the PR. It +may take at least a few days for someone to respond. If you don't get a +response in over a week, feel free to ping the assigned reviewer. + +When your PR is submitted, GitHub automatically runs all tests. The GitHub +interface will show a green checkmark if it passes, or a red X if it fails. +There are links to the logs on the PR page to diagnose any issues. The tests +typically finish in under 30 minutes. + +The reviewer might point out changes deemed necessary. Large or tricky changes +may require several passes of review and changes. + +### Status labeling + +PRs will get marked with [labels] like [`S-waiting-on-review`] or [`S-waiting-on-author`] to indicate their status. +The [`@rustbot`] bot can be used by anyone to adjust the labels. +If a PR gets marked as `S-waiting-on-author`, and you have pushed new changes that you would like to be reviewed, you can write a comment on the PR with the text `@rustbot ready`. +The bot will switch the labels on the PR. + +More information about these commands can be found at the [shortcuts documentation]. + +[labels]: https://github.com/rust-lang/cargo/labels +[`S-waiting-on-review`]: https://github.com/rust-lang/cargo/labels/S-waiting-on-review +[`S-waiting-on-author`]: https://github.com/rust-lang/cargo/labels/S-waiting-on-author +[`@rustbot`]: https://github.com/rustbot +[shortcuts documentation]: https://github.com/rust-lang/triagebot/wiki/Shortcuts + +## The merging process + +After a reviewer has approved your PR, they will issue a command to the [bors] +bot (also known as "Homu", the software that powers [`@bors`]). Bors will +create a temporary branch with your PR, and run all tests. Only if all tests +pass will it merge the PR to master. If it fails, the bot will leave a comment +on the PR. This system ensures that the master branch is always in a good +state, and that merges are processed one at a time. The [Homu queue +dashboard][homu-cargo] shows the current merge queue. Cargo's queue is rarely +busy, but a busy project like the [rust repo][homu-rust] is constantly full. + +Assuming everything works, congratulations! It may take at least a week for +the changes to arrive on the nightly channel. See the [release chapter] for +more information on how Cargo releases are made. + + +[development-models]: https://help.github.com/articles/about-collaborative-development-models/ +[create pull requests]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request +[how-to-fork]: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo +[`rust-lang/cargo`]: https://github.com/rust-lang/cargo/ +[git]: https://git-scm.com/ +[GitHub]: https://github.com/ +[how-to-clone]: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository +[Testing chapter]: ../tests/index.md +[GitHub's keywords]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue +[bors]: https://buildbot2.rust-lang.org/homu/ +[`@bors`]: https://github.com/bors +[homu-cargo]: https://buildbot2.rust-lang.org/homu/queue/cargo +[homu-rust]: https://buildbot2.rust-lang.org/homu/queue/rust +[release chapter]: release.md +[internals forum]: https://internals.rust-lang.org/c/tools-and-infrastructure/cargo +[file an issue]: https://github.com/rust-lang/cargo/issues +[the process]: index.md diff --git a/src/doc/contrib/src/tests/crater.md b/src/doc/contrib/src/tests/crater.md new file mode 100644 index 0000000..2220cb0 --- /dev/null +++ b/src/doc/contrib/src/tests/crater.md @@ -0,0 +1,122 @@ +# Crater + +[Crater](https://github.com/rust-lang/crater) is a tool for compiling and running tests for _every_ crate on [crates.io](https://crates.io) (and a few on GitHub). +It is mainly used for checking the extent of breakage when implementing potentially breaking changes and ensuring lack of breakage by running beta vs stable compiler versions. + +Essentially it runs some `cargo` command on every crate twice; once against the "start" toolchain and again against the "end" toolchain. +For example, "start" could be the stable release, and "end" could be beta. +If it passes in "start" but fails with "end", then that is reported as a regression. + +There is a bot called [craterbot] which is used to run crater on hardware managed by the rust-lang organization. + +Crater is run by the release team during the beta cycle. +If there are any regressions that look like they are caused by Cargo, they should contact the Cargo team to decide how to handle it. + +## Running crater + +If you have a change that you want to test before the beta release, or you want to test behavior that is not normally exercised by crater, you can do a manual run of crater. +Roughly the steps are: + +1. Create a branch with your changes. + + In your clone of cargo, make the changes to incorporate whatever new thing you want to test and push it to a branch on your fork on GitHub. + +2. Get a clone of <https://github.com/rust-lang/rust> + +3. Create a branch in your rust-lang/rust clone to add your changes. + +4. Change the `src/tools/cargo` submodule to point to your new branch. + + Modify `.gitmodules` to point to your clone and branch of cargo with the changes you want to test. + For example: + + ```bash + git submodule set-url src/tools/cargo https://github.com/ehuss/cargo.git + git submodule set-branch --branch my-awesome-feature src/tools/cargo + git submodule update --remote src/tools/cargo + git add .gitmodules src/tools/cargo + git commit + ``` + +5. Create an PR on rust-lang/rust. + + Push your submodule changes to GitHub and make a PR. + Start the PR title with `[EXPERIMENT]` to make it clear what the PR is for and assign yourself or @ghost. + +6. Make a "try" build. + + A "try" build creates a full release of x86_64-unknown-linux-gnu and stores it on rust-lang servers. + This can be done with a comment `@bors try` on the PR (all Cargo team members should have permission to do this). + +7. Run crater. + + Look at the [craterbot] docs to determine the command that you want to run. + There are different modes like `check-only`, `build-and-test`, `rustdoc`, etc. + + You can also choose how many crates to run against. + If you are uncertain if your cargo changes will work correctly, it might be a good idea to run against `top-100` first to check its behavior. + This will run much faster. + You can do a full run afterwards. + + After the try build finishes (which should take a couple hours), ask someone to make a crater run. + The Cargo team does not have that permission, so just ask someone on Zulip. + They will need to write a comment to `@craterbot` with the command that you have specified. + +8. Wait. + + Crater can take anywhere from a few hours to a few weeks to run depending on how long the [craterbot queue](https://crater.rust-lang.org/) is and which mode you picked and the priority of your job. + When the crater run finishes, craterbot will post a comment to the PR with a link to a report of the results. + +9. Investigate the report. + + Look through the report which contains links to build logs for any regressions or errors. + +10. Close the PR. + + Whenever you are done doing crater runs, close your PR. + +[craterbot]: https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md + + +## Advanced crater modes + +Crater only has a few built-in modes, such as running `cargo check` or `cargo test`. +You can pass extra flags with `+cargoflags`. + +More complex tests can be accomplished by customizing Cargo to perform whatever actions you want. +Since crater essentially runs `cargo check`, you can modify the `check` command to perform whichever actions you want. +For example, to test `cargo fix --edition`, [this commit](https://github.com/ehuss/cargo/commit/6901690a6f8d519efb4fabf48c1c2b94af0c3bd8) intercepted `cargo check` and modified it to instead: + +1. Only run on crates with the 2018 edition. +2. Run `cargo fix --edition`. +3. Modify the manifest to switch to the 2021 edition. +4. Run `cargo check` to verify. + +If you need to compare the before and after of a command that is not part of crater's built-in modes, that can be more difficult. +Two possible options: + +* Work with the infra team to add a new mode. +* Build two custom try builds. + Each one should modify the `cargo check` command as described above. + The "start" build should perform whichever action you want with an otherwise unmodified cargo. + The "end" build should perform whichever action you want with your modified cargo. + Then, in the `@craterbot` command, specify the start and end hashes of the two try builds. + +## Limitations + +There are some limitations of crater to consider when running Cargo: + +* A crater run without regressions is not a green light to move forward. + * A large portion of Rust code is not tested, such as closed-source projects or things otherwise not collected by crater. + * Many crates can't build in crater's environment or are otherwise broken. + * Some crates have flaky tests. +* Crater runs in an isolated environment. + * It only runs on Linux x86-64. + * It does not have network access. + * The crate source is in a read-only mount. +* Crater does several steps before running the test (using its own copy of the stable toolchain): + * It generates a lockfile using `generate-lockfile` and includes `-Zno-index-update` to prevent index updates (which makes it run much faster). + * All dependencies are downloaded ahead-of-time with `cargo fetch`. +* The built-in modes pass several flags to cargo such as `--frozen` or `--message-format=json`. + It will sometimes use `--all-targets` and sometimes not. + Check the [crater source](https://github.com/rust-lang/crater/blob/master/src/runner/test.rs) for more details on how it works. diff --git a/src/doc/contrib/src/tests/index.md b/src/doc/contrib/src/tests/index.md new file mode 100644 index 0000000..dac0476 --- /dev/null +++ b/src/doc/contrib/src/tests/index.md @@ -0,0 +1,20 @@ +# Tests + +Cargo has an extensive test suite. Most of it is implemented as integration +tests in the [`testsuite`] directory. There are several other tests: + +* Unit tests are scattered throughout. +* The dependency resolver has its own set of tests in the [`resolver-tests`] + directory. +* All of the packages in the [`crates`] directory have their own set of tests. +* The [`build-std`] test is for the [build-std feature]. It is separate since + it has some special requirements. +* Documentation has a variety of tests, such as link validation, and the + [SemVer chapter validity checks]. + +[`testsuite`]: https://github.com/rust-lang/cargo/tree/master/tests/testsuite/ +[`resolver-tests`]: https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests +[`crates`]: https://github.com/rust-lang/cargo/tree/master/crates +[`build-std`]: https://github.com/rust-lang/cargo/blob/master/tests/build-std/main.rs +[build-std feature]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std +[SemVer chapter validity checks]: https://github.com/rust-lang/cargo/tree/master/src/doc/semver-check diff --git a/src/doc/contrib/src/tests/profiling.md b/src/doc/contrib/src/tests/profiling.md new file mode 100644 index 0000000..1cc980c --- /dev/null +++ b/src/doc/contrib/src/tests/profiling.md @@ -0,0 +1,40 @@ +# Benchmarking and Profiling + +## Internal profiler + +Cargo has a basic, hierarchical profiler built-in. The environment variable +`CARGO_PROFILE` can be set to an integer which specifies how deep in the +profile stack to print results for. + +```sh +# Output first three levels of profiling info +CARGO_PROFILE=3 cargo generate-lockfile +``` + +## Benchmarking + +### Benchsuite + +Head over to the [`benches` +directory](https://github.com/rust-lang/cargo/tree/master/benches) for more +information about the benchmarking suite. + +### Informal benchmarking + +The overhead for starting a build should be kept as low as possible +(preferably, well under 0.5 seconds on most projects and systems). Currently, +the primary parts that affect this are: + +* Running the resolver. +* Querying the index. +* Checking git dependencies. +* Scanning the local project. +* Building the unit dependency graph. + +One way to test this is to use [hyperfine]. This is a tool that can be used to +measure the difference between different commands and settings. Usually this +is done by measuring the time it takes for `cargo build` to finish in a large +project where the build is fresh (no actual compilation is performed). Just +run `cargo build` once before using hyperfine. + +[hyperfine]: https://github.com/sharkdp/hyperfine diff --git a/src/doc/contrib/src/tests/running.md b/src/doc/contrib/src/tests/running.md new file mode 100644 index 0000000..dc306fb --- /dev/null +++ b/src/doc/contrib/src/tests/running.md @@ -0,0 +1,68 @@ +# Running Tests + +Using `cargo test` is usually sufficient for running the full test suite. This +can take a few minutes, so you may want to use more targeted flags to pick the +specific test you want to run, such as `cargo test --test testsuite +-- check::check_success`. + +## Running nightly tests + +Some tests only run on the nightly toolchain, and will be ignored on other +channels. It is recommended that you run tests with both nightly and stable to +ensure everything is working as expected. + +Some of the nightly tests require the `rustc-dev` and `llvm-tools-preview` +rustup components installed. These components include the compiler as a +library. This may already be installed with your nightly toolchain, but if it +isn't, run `rustup component add rustc-dev llvm-tools-preview +--toolchain=nightly`. + +## Running cross tests + +Some tests exercise cross compiling to a different target. This will require +you to install the appropriate target. This typically is the 32-bit target of +your host platform. For example, if your host is a 64-bit +`x86_64-unknown-linux-gnu`, then you should install the 32-bit target with +`rustup target add i686-unknown-linux-gnu`. If you don't have the alternate +target installed, there should be an error message telling you what to do. You +may also need to install additional tools for the target. For example, on Ubuntu +you should install the `gcc-multilib` package. + +If you can't install an alternate target, you can set the +`CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests. The +Windows cross tests only support the MSVC toolchain. + +## Running build-std tests + +The `build-std` tests are disabled by default, but you can run them by setting +the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test +--test build-std`. This requires the nightly channel, and also requires the +`rust-src` component installed with `rustup component add rust-src +--toolchain=nightly`. + +## Running public network tests + +Some (very rare) tests involve connecting to the public internet. +These tests are disabled by default, +but you can run them by setting the `CARGO_PUBLIC_NETWORK_TESTS=1` environment variable. +Additionally our CI suite has a smoke test for fetching dependencies. +For most contributors, you will never need to bother with this. + +## Running container tests + +Tests marked with `container_test` involve running Docker to test more complex configurations. +These tests are disabled by default, +but you can run them by setting the `CARGO_CONTAINER_TESTS=1` environment variable. +You will need to have Docker installed and running to use these. + +> Note: Container tests mostly do not work on Windows. +> * The SSH tests require ssh-agent, but the two versions of ssh-agent +> on Windows are not suitable for testing. +> * The Microsoft version of ssh-agent runs as a global service, and can't be isolated per test. +> * The mingw/cygwin one can't be accessed from a Windows executable like cargo. +> * Pageant similarly does not seem to have a way to isolate it (and I'm not certain it can be driven completely from the command-line). +> +> The tests also can't run on Windows CI because the Docker that is preinstalled doesn't support Linux containers, and setting up Windows containers is a pain. +> +> macOS should work with Docker installed and running, +> but unfortunately the tests are not run on CI because Docker is not available. diff --git a/src/doc/contrib/src/tests/writing.md b/src/doc/contrib/src/tests/writing.md new file mode 100644 index 0000000..a84dd5d --- /dev/null +++ b/src/doc/contrib/src/tests/writing.md @@ -0,0 +1,299 @@ +# Writing Tests + +The following focuses on writing an integration test. However, writing unit +tests is also encouraged! + +## Testsuite + +Cargo has a wide variety of integration tests that execute the `cargo` binary +and verify its behavior, located in the [`testsuite`] directory. The +[`support`] crate and [`snapbox`] contain many helpers to make this process easy. + +There are two styles of tests that can roughly be categorized as +- functional tests + - The fixture is programmatically defined + - The assertions are regular string comparisons + - Easier to share in an issue as a code block is completely self-contained + - More resilient to insignificant changes though ui tests are easy to update when a change does occur +- ui tests + - The fixture is file-based + - The assertions use file-backed snapshots that can be updated with an env variable + - Easier to review the expected behavior of the command as more details are included + - Easier to get up and running from an existing project + - Easier to reason about as everything is just files in the repo + +These tests typically work by creating a temporary "project" with a +`Cargo.toml` file, executing the `cargo` binary process, and checking the +stdout and stderr output against the expected output. + +### Functional Tests + +Generally, a functional test will be placed in `tests/testsuite/<command>.rs` and will look roughly like: +```rust,ignore +#[cargo_test] +fn <description>() { + let p = project() + .file("src/main.rs", r#"fn main() { println!("hi!"); }"#) + .build(); + + p.cargo("run --bin foo") + .with_stderr( + "\ + [COMPILING] foo [..] + [FINISHED] [..] + [RUNNING] `target/debug/foo` + ", + ) + .with_stdout("hi!") + .run(); + } +} +``` + +The [`#[cargo_test]` attribute](#cargo_test-attribute) is used in place of `#[test]` to inject some setup code. + +[`ProjectBuilder`] via `project()`: +- Each project is in a separate directory in the sandbox +- If you do not specify a `Cargo.toml` manifest using `file()`, one is + automatically created with a project name of `foo` using `basic_manifest()`. + +[`Execs`] via `p.cargo(...)`: +- This executes the command and evaluates different assertions + - See [`support::compare`] for an explanation of the string pattern matching. + Patterns are used to make it easier to match against the expected output. + +#### `#[cargo_test]` attribute + +The `#[cargo_test]` attribute injects code which does some setup before starting the test. +It will create a filesystem "sandbox" under the "cargo integration test" directory for each test, such as `/path/to/cargo/target/tmp/cit/t123/`. +The sandbox will contain a `home` directory that will be used instead of your normal home directory. + +The `#[cargo_test]` attribute takes several options that will affect how the test is generated. +They are listed in parentheses separated with commas, such as: + +```rust,ignore +#[cargo_test(nightly, reason = "-Zfoo is unstable")] +``` + +The options it supports are: + +* `nightly` --- This will cause the test to be ignored if not running on the nightly toolchain. + This is useful for tests that use unstable options in `rustc` or `rustdoc`. + These tests are run in Cargo's CI, but are disabled in rust-lang/rust's CI due to the difficulty of updating both repos simultaneously. + A `reason` field is required to explain why it is nightly-only. +* `build_std_real` --- This is a "real" `-Zbuild-std` test (in the `build_std` integration test). + This only runs on nightly, and only if the environment variable `CARGO_RUN_BUILD_STD_TESTS` is set (these tests on run on Linux). +* `build_std_mock` --- This is a "mock" `-Zbuild-std` test (which uses a mock standard library). + This only runs on nightly, and is disabled for windows-gnu. +* `requires_` --- This indicates a command that is required to be installed to be run. + For example, `requires_rustfmt` means the test will only run if the executable `rustfmt` is installed. + These tests are *always* run on CI. + This is mainly used to avoid requiring contributors from having every dependency installed. +* `>=1.64` --- This indicates that the test will only run with the given version of `rustc` or newer. + This can be used when a new `rustc` feature has been stabilized that the test depends on. + If this is specified, a `reason` is required to explain why it is being checked. +* `public_network_test` --- This tests contacts the public internet. + These tests are disabled unless the `CARGO_PUBLIC_NETWORK_TESTS` environment variable is set. + Use of this should be *extremely rare*, please avoid using it if possible. + The hosts it contacts should have a relatively high confidence that they are reliable and stable (such as github.com), especially in CI. + The tests should be carefully considered for developer security and privacy as well. +* `container_test` --- This indicates that it is a test that uses Docker. + These tests are disabled unless the `CARGO_CONTAINER_TESTS` environment variable is set. + This requires that you have Docker installed. + The SSH tests also assume that you have OpenSSH installed. + These should work on Linux, macOS, and Windows where possible. + Unfortunately these tests are not run in CI for macOS or Windows (no Docker on macOS, and Windows does not support Linux images). + See [`crates/cargo-test-support/src/containers.rs`](https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/containers.rs) for more on writing these tests. +* `ignore_windows="reason"` --- Indicates that the test should be ignored on windows for the given reason. + +#### Testing Nightly Features + +If you are testing a Cargo feature that only works on "nightly" Cargo, then +you need to call `masquerade_as_nightly_cargo` on the process builder and pass +the name of the feature as the reason, like this: + +```rust,ignore +p.cargo("build").masquerade_as_nightly_cargo(&["print-im-a-teapot"]) +``` + +If you are testing a feature that only works on *nightly rustc* (such as +benchmarks), then you should use the `nightly` option of the `cargo_test` +attribute, like this: + +```rust,ignore +#[cargo_test(nightly, reason = "-Zfoo is unstable")] +``` + +This will cause the test to be ignored if not running on the nightly toolchain. + +#### Specifying Dependencies + +You should not write any tests that use the network such as contacting +crates.io. Typically, simple path dependencies are the easiest way to add a +dependency. Example: + +```rust,ignore +let p = project() + .file("Cargo.toml", r#" + [package] + name = "foo" + version = "1.0.0" + + [dependencies] + bar = {path = "bar"} + "#) + .file("src/lib.rs", "extern crate bar;") + .file("bar/Cargo.toml", &basic_manifest("bar", "1.0.0")) + .file("bar/src/lib.rs", "") + .build(); +``` + +If you need to test with registry dependencies, see +[`support::registry::Package`] for creating packages you can depend on. + +If you need to test git dependencies, see [`support::git`] to create a git +dependency. + +### UI Tests + +UI Tests are a bit more spread out and generally look like: + +`tests/testsuite/<command>/mod.rs`: +```rust,ignore +mod <case>; +``` + +`tests/testsuite/<command>/<case>/mod.rs`: +```rust,ignore +use cargo_test_support::prelude::*; +use cargo_test_support::compare::assert_ui; +use cargo_test_support::Project; +use cargo_test_support::curr_dir; + +#[cargo_test] +fn case() { + let project = Project::from_template(curr_dir!().join("in")); + let project_root = project.root(); + let cwd = &project_root; + + snapbox::cmd::Command::cargo_ui() + .arg("run") + .arg_line("--bin foo") + .current_dir(cwd) + .assert() + .success() + .stdout_matches_path(curr_dir!().join("stdout.log")) + .stderr_matches_path(curr_dir!().join("stderr.log")); + + assert_ui().subset_matches(curr_dir!().join("out"), &project_root); +} +``` + +Then populate +- `tests/testsuite/<command>/<case>/in` with the project's directory structure +- `tests/testsuite/<command>/<case>/out` with the files you want verified +- `tests/testsuite/<command>/<case>/stdout.log` with nothing +- `tests/testsuite/<command>/<case>/stderr.log` with nothing + +`#[cargo_test]`: +- This is used in place of `#[test]` +- This attribute injects code which does some setup before starting the + test, creating a filesystem "sandbox" under the "cargo integration test" + directory for each test such as + `/path/to/cargo/target/cit/t123/` +- The sandbox will contain a `home` directory that will be used instead of your normal home directory + +`Project`: +- The project is copied from a directory in the repo +- Each project is in a separate directory in the sandbox + +[`Command`] via `Command::cargo_ui()`: +- Set up and run a command. + +[`OutputAssert`] via `Command::assert()`: +- Perform assertions on the result of the [`Command`] + +[`Assert`] via `assert_ui()`: +- Verify the command modified the file system as expected + +#### Updating Snapshots + +The project, stdout, and stderr snapshots can be updated by running with the +`SNAPSHOTS=overwrite` environment variable, like: +```console +$ SNAPSHOTS=overwrite cargo test +``` + +Be sure to check the snapshots to make sure they make sense. + +#### Testing Nightly Features + +If you are testing a Cargo feature that only works on "nightly" Cargo, then +you need to call `masquerade_as_nightly_cargo` on the process builder and pass +the name of the feature as the reason, like this: + +```rust,ignore + snapbox::cmd::Command::cargo() + .masquerade_as_nightly_cargo(&["print-im-a-teapot"]) +``` + +If you are testing a feature that only works on *nightly rustc* (such as +benchmarks), then you should use the `nightly` option of the `cargo_test` +attribute, like this: + +```rust,ignore +#[cargo_test(nightly, reason = "-Zfoo is unstable")] +``` + +This will cause the test to be ignored if not running on the nightly toolchain. + +### Platform-specific Notes + +When checking output, use `/` for paths even on Windows: the actual output +of `\` on Windows will be replaced with `/`. + +Be careful when executing binaries on Windows. You should not rename, delete, +or overwrite a binary immediately after running it. Under some conditions +Windows will fail with errors like "directory not empty" or "failed to remove" +or "access is denied". + +## Debugging tests + +In some cases, you may need to dig into a test that is not working as you +expect, or you just generally want to experiment within the sandbox +environment. The general process is: + +1. Build the sandbox for the test you want to investigate. For example: + + `cargo test --test testsuite -- features2::inactivate_targets`. +2. In another terminal, head into the sandbox directory to inspect the files and run `cargo` directly. + 1. The sandbox directories start with `t0` for the first test. + + `cd target/tmp/cit/t0` + 2. Set up the environment so that the sandbox configuration takes effect: + + `export CARGO_HOME=$(pwd)/home/.cargo` + 3. Most tests create a `foo` project, so head into that: + + `cd foo` +3. Run whatever cargo command you want. See [Running Cargo] for more details + on running the correct `cargo` process. Some examples: + + * `/path/to/my/cargo/target/debug/cargo check` + * Using a debugger like `lldb` or `gdb`: + 1. `lldb /path/to/my/cargo/target/debug/cargo` + 2. Set a breakpoint, for example: `b generate_root_units` + 3. Run with arguments: `r check` + +[`testsuite`]: https://github.com/rust-lang/cargo/tree/master/tests/testsuite/ +[`ProjectBuilder`]: https://github.com/rust-lang/cargo/blob/d847468768446168b596f721844193afaaf9d3f2/crates/cargo-test-support/src/lib.rs#L196-L202 +[`Execs`]: https://github.com/rust-lang/cargo/blob/d847468768446168b596f721844193afaaf9d3f2/crates/cargo-test-support/src/lib.rs#L531-L550 +[`support`]: https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/lib.rs +[`support::compare`]: https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/compare.rs +[`support::registry::Package`]: https://github.com/rust-lang/cargo/blob/d847468768446168b596f721844193afaaf9d3f2/crates/cargo-test-support/src/registry.rs#L311-L389 +[`support::git`]: https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/git.rs +[Running Cargo]: ../process/working-on-cargo.md#running-cargo +[`snapbox`]: https://docs.rs/snapbox/latest/snapbox/ +[`Command`]: https://docs.rs/snapbox/latest/snapbox/cmd/struct.Command.html +[`OutputAssert`]: https://docs.rs/snapbox/latest/snapbox/cmd/struct.OutputAssert.html +[`Assert`]: https://docs.rs/snapbox/latest/snapbox/struct.Assert.html diff --git a/src/doc/man/cargo-add.md b/src/doc/man/cargo-add.md new file mode 100644 index 0000000..c9bb237 --- /dev/null +++ b/src/doc/man/cargo-add.md @@ -0,0 +1,173 @@ +# cargo-add(1) + +{{*set actionverb="Add"}} +{{*set nouns="adds"}} + +## NAME + +cargo-add --- Add dependencies to a Cargo.toml manifest file + +## SYNOPSIS + +`cargo add` [_options_] _crate_...\ +`cargo add` [_options_] `--path` _path_\ +`cargo add` [_options_] `--git` _url_ [_crate_...]\ + + +## DESCRIPTION + +This command can add or modify dependencies. + +The source for the dependency can be specified with: + +* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_" +* `--path` _path_: Fetch from the specified _path_ +* `--git` _url_: Pull from a git repo at _url_ + +If no source is specified, then a best effort will be made to select one, including: + +* Existing dependencies in other tables (like `dev-dependencies`) +* Workspace members +* Latest release in the registry + +When you add a package that is already present, the existing entry will be updated with the flags specified. + +Upon successful invocation, the enabled (`+`) and disabled (`-`) [features] of the specified +dependency will be listed in the command's output. + +[features]: ../reference/features.md + +## OPTIONS + +### Source options + +{{#options}} + +{{#option "`--git` _url_" }} +[Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories). +{{/option}} + +{{#option "`--branch` _branch_" }} +Branch to use when adding from git. +{{/option}} + +{{#option "`--tag` _tag_" }} +Tag to use when adding from git. +{{/option}} + +{{#option "`--rev` _sha_" }} +Specific commit to use when adding from git. +{{/option}} + +{{#option "`--path` _path_" }} +[Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add. +{{/option}} + +{{> options-registry }} + +{{/options}} + +### Section options + +{{#options}} + +{{#option "`--dev`" }} +Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies). +{{/option}} + +{{#option "`--build`" }} +Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies). +{{/option}} + +{{#option "`--target` _target_" }} +Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies). +{{/option}} + +{{/options}} + + +</dl> + +### Dependency options + +{{#options}} + +{{#option "`--dry-run`" }} +Don't actually write the manifest +{{/option}} + +{{#option "`--rename` _name_" }} +[Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency. +{{/option}} + +{{#option "`--optional`" }} +Mark the dependency as [optional](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-optional`" }} +Mark the dependency as [required](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-default-features`" }} +Disable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`--default-features`" }} +Re-enable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`-F` _features_" "`--features` _features_" }} +Space or comma separated list of [features to +activate](../reference/features.html#dependency-features). When adding multiple +crates, the features for a specific crate may be enabled with +`package-name/feature-name` syntax. This flag may be specified multiple times, +which enables all specified features. +{{/option}} + +{{/options}} + + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +Add dependencies to only the specified package. +{{/option}} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Add `regex` as a dependency + + cargo add regex + +2. Add `trybuild` as a dev-dependency + + cargo add --dev trybuild + +3. Add an older version of `nom` as a dependency + + cargo add nom@5 + +4. Add support for serializing data structures to json with `derive`s + + cargo add serde serde_json -F serde/derive + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-remove" 1}} diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md new file mode 100644 index 0000000..32c98da --- /dev/null +++ b/src/doc/man/cargo-bench.md @@ -0,0 +1,164 @@ +# cargo-bench(1) +{{*set actionverb="Benchmark"}} +{{*set nouns="benchmarks"}} +{{*set multitarget=true}} + +## NAME + +cargo-bench --- Execute benchmarks of a package + +## SYNOPSIS + +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] + +## DESCRIPTION + +Compile and execute benchmarks. + +The benchmark filtering argument _benchname_ and all the arguments following +the two dashes (`--`) are passed to the benchmark binaries and thus to +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help` and check out the rustc +book's chapter on how tests work at +<https://doc.rust-lang.org/rustc/tests/index.html>. + +As an example, this will run only the benchmark named `foo` (and skip other +similarly named benchmarks like `foobar`): + + cargo bench -- foo --exact + +Benchmarks are built with the `--test` option to `rustc` which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the `#[bench]` attribute. +Cargo passes the `--bench` flag to the test harness to tell it to run +only benchmarks. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running benchmarks. + +> **Note**: The +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +> is currently unstable and only available on the +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). +> There are some packages available on +> [crates.io](https://crates.io/keywords/benchmark) that may help with +> running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +By default, `cargo bench` uses the [`bench` profile], which enables +optimizations and disables debugging information. If you need to debug a +benchmark, you can use the `--profile=dev` command-line option to switch to +the dev profile. You can then run the debug-enabled benchmark within a +debugger. + +[`bench` profile]: ../reference/profiles.html#bench + +## OPTIONS + +### Benchmark Options + +{{> options-test }} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo bench` will build the +following targets of the selected packages: + +- lib --- used to link with binaries and benchmarks +- bins (only if benchmark targets are built and required features are + available) +- lib as a benchmark +- bins as benchmarks +- benchmark targets + +The default behavior can be changed by setting the `bench` flag for the target +in the manifest settings. Setting examples to `bench = true` will build and +run the example as a benchmark. Setting targets to `bench = false` will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the `bench` flag and will always benchmark the given +target. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g., for debugging) by +passing `--nocapture` to the benchmark binaries: + + cargo bench -- --nocapture + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +The `--jobs` argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build and execute all the benchmarks of the current package: + + cargo bench + +2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-test" 1}} diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md new file mode 100644 index 0000000..9861444 --- /dev/null +++ b/src/doc/man/cargo-build.md @@ -0,0 +1,116 @@ +# cargo-build(1) +{{*set actionverb="Build"}} +{{*set multitarget=true}} + +## NAME + +cargo-build --- Compile the current package + +## SYNOPSIS + +`cargo build` [_options_] + +## DESCRIPTION + +Compile local packages and all of their dependencies. + +## OPTIONS + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo build` will build all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} + +{{#option "`--out-dir` _directory_" }} +Copy final artifacts to this directory. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z unstable-options` flag to enable. +See <https://github.com/rust-lang/cargo/issues/6790> for more information. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} + +{{#option "`--build-plan`" }} +Outputs a series of JSON messages to stdout that indicate the commands to run +the build. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z unstable-options` flag to enable. +See <https://github.com/rust-lang/cargo/issues/5579> for more information. +{{/option}} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build the local package and all of its dependencies: + + cargo build + +2. Build with optimizations: + + cargo build --release + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-rustc" 1}} diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md new file mode 100644 index 0000000..055adff --- /dev/null +++ b/src/doc/man/cargo-check.md @@ -0,0 +1,99 @@ +# cargo-check(1) +{{*set actionverb="Check"}} +{{*set multitarget=true}} + +## NAME + +cargo-check --- Check the current package + +## SYNOPSIS + +`cargo check` [_options_] + +## DESCRIPTION + +Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running `cargo build`. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. Some diagnostics and errors are only emitted during code +generation, so they inherently won't be reported with `cargo check`. + +## OPTIONS + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo check` will check all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Check the local package for errors: + + cargo check + +2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-clean.md b/src/doc/man/cargo-clean.md new file mode 100644 index 0000000..3222f7b --- /dev/null +++ b/src/doc/man/cargo-clean.md @@ -0,0 +1,88 @@ +# cargo-clean(1) +{{*set actionverb="Clean"}} +{{*set multitarget=true}} + +## NAME + +cargo-clean --- Remove generated artifacts + +## SYNOPSIS + +`cargo clean` [_options_] + +## DESCRIPTION + +Remove artifacts from the target directory that Cargo has generated in the +past. + +With no options, `cargo clean` will delete the entire target directory. + +## OPTIONS + +### Package Selection + +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. + +{{#options}} +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Clean only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. +{{/option}} +{{/options}} + +### Clean Options + +{{#options}} + +{{#option "`--doc`" }} +This option will cause `cargo clean` to remove only the `doc` directory in +the target directory. +{{/option}} + +{{#option "`--release`" }} +Remove all artifacts in the `release` directory. +{{/option}} + +{{#option "`--profile` _name_" }} +Remove all artifacts in the directory with the given profile name. +{{/option}} + +{{> options-target-dir }} + +{{> options-target-triple }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Remove the entire target directory: + + cargo clean + +2. Remove only the release artifacts: + + cargo clean --release + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md new file mode 100644 index 0000000..9d5b776 --- /dev/null +++ b/src/doc/man/cargo-doc.md @@ -0,0 +1,129 @@ +# cargo-doc(1) +{{*set actionverb="Document"}} +{{*set multitarget=true}} + +## NAME + +cargo-doc --- Build a package's documentation + +## SYNOPSIS + +`cargo doc` [_options_] + +## DESCRIPTION + +Build the documentation for the local package and all dependencies. The output +is placed in `target/doc` in rustdoc's usual format. + +## OPTIONS + +### Documentation Options + +{{#options}} + +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. +{{/option}} + +{{#option "`--no-deps`" }} +Do not build documentation for dependencies. +{{/option}} + +{{#option "`--document-private-items`" }} +Include non-public items in the documentation. This will be enabled by default if documenting a binary target. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo doc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +The default behavior can be changed by setting `doc = false` for the target in +the manifest settings. Using target selection options will ignore the `doc` +flag and will always document the given target. + +{{#options}} +{{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build the local package documentation and its dependencies and output to + `target/doc`. + + cargo doc + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-rustdoc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/cargo-fetch.md b/src/doc/man/cargo-fetch.md new file mode 100644 index 0000000..c31166a --- /dev/null +++ b/src/doc/man/cargo-fetch.md @@ -0,0 +1,65 @@ +# cargo-fetch(1) +{{*set actionverb="Fetch"}} +{{*set target-default-to-all-arch=true}} +{{*set multitarget=true}} + +## NAME + +cargo-fetch --- Fetch dependencies of a package from the network + +## SYNOPSIS + +`cargo fetch` [_options_] + +## DESCRIPTION + +If a `Cargo.lock` file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands will be able to run offline after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch) +plugin which adds a command to download popular crates. This may be useful if +you plan to use Cargo without a network with the `--offline` flag. + +## OPTIONS + +### Fetch options + +{{#options}} +{{> options-target-triple }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Fetch all dependencies: + + cargo fetch + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-update" 1}}, {{man "cargo-generate-lockfile" 1}} diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md new file mode 100644 index 0000000..64fe299 --- /dev/null +++ b/src/doc/man/cargo-fix.md @@ -0,0 +1,182 @@ +# cargo-fix(1) +{{*set actionverb="Fix"}} +{{*set multitarget=true}} + +## NAME + +cargo-fix --- Automatically fix lint warnings reported by rustc + +## SYNOPSIS + +`cargo fix` [_options_] + +## DESCRIPTION + +This Cargo subcommand will automatically take rustc's suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! + +Executing `cargo fix` will under the hood execute {{man "cargo-check" 1}}. Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you'd like to apply all fixes to the current package, you can run: + + cargo fix + +which behaves the same as `cargo check --all-targets`. + +`cargo fix` is only capable of fixing code that is normally compiled with +`cargo check`. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: + + cargo fix --features foo + +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. + + cargo fix --target x86_64-pc-windows-gnu + +If you encounter any problems with `cargo fix` or otherwise have any questions +or feature requests please don't hesitate to file an issue at +<https://github.com/rust-lang/cargo>. + +### Edition migration + +The `cargo fix` subcommand can also be used to migrate a package from one +[edition] to the next. The general procedure is: + +1. Run `cargo fix --edition`. Consider also using the `--all-features` flag if + your project has multiple features. You may also want to run `cargo fix + --edition` multiple times with different `--target` flags if your project + has platform-specific code gated by `cfg` attributes. +2. Modify `Cargo.toml` to set the [edition field] to the new edition. +3. Run your project tests to verify that everything still works. If new + warnings are issued, you may want to consider running `cargo fix` again + (without the `--edition` flag) to apply any suggestions given by the + compiler. + +And hopefully that's it! Just keep in mind of the caveats mentioned above that +`cargo fix` cannot update code for inactive features or `cfg` expressions. +Also, in some rare cases the compiler is unable to automatically migrate all +code to the new edition, and this may require manual changes after building +with the new edition. + +[edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html +[edition field]: ../reference/manifest.html#the-edition-field + +## OPTIONS + +### Fix options + +{{#options}} + +{{#option "`--broken-code`" }} +Fix code even if it already has compiler errors. This is useful if `cargo fix` +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix. +{{/option}} + +{{#option "`--edition`" }} +Apply changes that will update the code to the next edition. This will not +update the edition in the `Cargo.toml` manifest, which must be updated +manually after `cargo fix --edition` has finished. +{{/option}} + +{{#option "`--edition-idioms`" }} +Apply suggestions that will update code to the preferred style for the current +edition. +{{/option}} + +{{#option "`--allow-no-vcs`" }} +Fix code even if a VCS was not detected. +{{/option}} + +{{#option "`--allow-dirty`" }} +Fix code even if the working directory has changes. +{{/option}} + +{{#option "`--allow-staged`" }} +Fix code even if the working directory has staged changes. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo fix` will fix all targets +(`--all-targets` implied). Binaries are skipped if they have +`required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Apply compiler suggestions to the local package: + + cargo fix + +2. Update a package to prepare it for the next edition: + + cargo fix --edition + +3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-check" 1}} diff --git a/src/doc/man/cargo-generate-lockfile.md b/src/doc/man/cargo-generate-lockfile.md new file mode 100644 index 0000000..3a2f52b --- /dev/null +++ b/src/doc/man/cargo-generate-lockfile.md @@ -0,0 +1,49 @@ +# cargo-generate-lockfile(1) + +## NAME + +cargo-generate-lockfile --- Generate the lockfile for a package + +## SYNOPSIS + +`cargo generate-lockfile` [_options_] + +## DESCRIPTION + +This command will create the `Cargo.lock` lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt with the latest +available version of every package. + +See also {{man "cargo-update" 1}} which is also capable of creating a `Cargo.lock` +lockfile and has more options for controlling update behavior. + +## OPTIONS + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-update" 1}} diff --git a/src/doc/man/cargo-help.md b/src/doc/man/cargo-help.md new file mode 100644 index 0000000..4a5a8f5 --- /dev/null +++ b/src/doc/man/cargo-help.md @@ -0,0 +1,26 @@ +# cargo-help(1) + +## NAME + +cargo-help --- Get help for a Cargo command + +## SYNOPSIS + +`cargo help` [_subcommand_] + +## DESCRIPTION + +Prints a help message for the given command. + +## EXAMPLES + +1. Get help for a command: + + cargo help build + +2. Help is also available with the `--help` flag: + + cargo build --help + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-init.md b/src/doc/man/cargo-init.md new file mode 100644 index 0000000..cd8e623 --- /dev/null +++ b/src/doc/man/cargo-init.md @@ -0,0 +1,51 @@ +# cargo-init(1) + +## NAME + +cargo-init --- Create a new Cargo package in an existing directory + +## SYNOPSIS + +`cargo init` [_options_] [_path_] + +## DESCRIPTION + +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +See {{man "cargo-new" 1}} for a similar command which will create a new package in +a new directory. + +## OPTIONS + +### Init Options + +{{> options-new }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create a binary Cargo package in the current directory: + + cargo init + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-new" 1}} diff --git a/src/doc/man/cargo-install.md b/src/doc/man/cargo-install.md new file mode 100644 index 0000000..14c2296 --- /dev/null +++ b/src/doc/man/cargo-install.md @@ -0,0 +1,229 @@ +# cargo-install(1) +{{*set actionverb="Install"}} +{{*set temp-target-dir=true}} + +## NAME + +cargo-install --- Build and install a Rust binary + +## SYNOPSIS + +`cargo install` [_options_] _crate_[@_version_]...\ +`cargo install` [_options_] `--path` _path_\ +`cargo install` [_options_] `--git` _url_ [_crate_...]\ +`cargo install` [_options_] `--list` + +## DESCRIPTION + +This command manages Cargo's local set of installed binary crates. Only +packages which have executable `[[bin]]` or `[[example]]` targets can be +installed, and all executables are installed into the installation root's +`bin` folder. + +{{> description-install-root }} + +There are multiple sources from which a crate can be installed. The default +location is crates.io but the `--git`, `--path`, and `--registry` flags can +change this source. If the source contains more than one package (such as +crates.io or a git repository with multiple crates) the _crate_ argument is +required to indicate which crate should be installed. + +Crates from crates.io can optionally specify the version they wish to install +via the `--version` flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the `--bin` argument can selectively install only +one of them, and if you'd rather install examples the `--example` argument can +be used as well. + +If the package is already installed, Cargo will reinstall it if the installed +version does not appear to be up-to-date. If any of the following values +change, then Cargo will reinstall the package: + +- The package version and source. +- The set of binary names installed. +- The chosen features. +- The profile (`--profile`). +- The target (`--target`). + +Installing with `--path` will always build and install, unless there are +conflicting binaries from another package. The `--force` flag may be used to +force Cargo to always reinstall the package. + +If the source is crates.io or `--git` then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the `CARGO_TARGET_DIR` environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. + +### Dealing with the Lockfile + +By default, the `Cargo.lock` file that is included with the package will be +ignored. This means that Cargo will recompute which versions of dependencies +to use, possibly using newer versions that have been released since the +package was published. The `--locked` flag can be used to force Cargo to use +the packaged `Cargo.lock` file if it is available. This may be useful for +ensuring reproducible builds, to use the exact same set of dependencies that +were available when the package was published. It may also be useful if a +newer version of a dependency is published that no longer builds on your +system, or has other problems. The downside to using `--locked` is that you +will not receive any fixes or updates to any dependency. Note that Cargo did +not start publishing `Cargo.lock` files until version 1.37, which means +packages published with prior versions will not have a `Cargo.lock` file +available. + +### Configuration Discovery + +This command operates on system or user level, not project level. +This means that the local [configuration discovery] is ignored. +Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`. +If the package is installed with `--path $PATH`, the local configuration +will be used, beginning discovery at `$PATH/.cargo/config.toml`. + +[configuration discovery]: ../reference/config.html#hierarchical-structure + +## OPTIONS + +### Install Options + +{{#options}} + +{{#option "`--vers` _version_" "`--version` _version_" }} +Specify a version to install. This may be a [version +requirement](../reference/specifying-dependencies.md), like `~1.2`, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as `^` or `~`), then it must be in the form +_MAJOR.MINOR.PATCH_, and will install exactly that version; it is *not* +treated as a caret requirement like Cargo dependencies are. +{{/option}} + +{{#option "`--git` _url_" }} +Git URL to install the specified crate from. +{{/option}} + +{{#option "`--branch` _branch_" }} +Branch to use when installing from git. +{{/option}} + +{{#option "`--tag` _tag_" }} +Tag to use when installing from git. +{{/option}} + +{{#option "`--rev` _sha_" }} +Specific commit to use when installing from git. +{{/option}} + +{{#option "`--path` _path_" }} +Filesystem path to local crate to install. +{{/option}} + +{{#option "`--list`" }} +List all installed packages and their versions. +{{/option}} + +{{#option "`-f`" "`--force`" }} +Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of `rustc`. +{{/option}} + +{{#option "`--no-track`" }} +By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the `--force` flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. +{{/option}} + +{{#option "`--bin` _name_..." }} +Install only the specified binary. +{{/option}} + +{{#option "`--bins`" }} +Install all binaries. +{{/option}} + +{{#option "`--example` _name_..." }} +Install only the specified example. +{{/option}} + +{{#option "`--examples`" }} +Install all examples. +{{/option}} + +{{#option "`--root` _dir_" }} +Directory to install packages into. +{{/option}} + +{{> options-registry }} + +{{> options-index }} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{#option "`--debug`" }} +Build with the `dev` profile instead the `release` profile. +See also the `--profile` option for choosing a specific profile by name. +{{/option}} + +{{> options-profile }} + +{{> options-timings }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Install or upgrade a package from crates.io: + + cargo install ripgrep + +2. Install or reinstall the package in the current directory: + + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-uninstall" 1}}, {{man "cargo-search" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-locate-project.md b/src/doc/man/cargo-locate-project.md new file mode 100644 index 0000000..4ebf36d --- /dev/null +++ b/src/doc/man/cargo-locate-project.md @@ -0,0 +1,66 @@ +# cargo-locate-project(1) + +## NAME + +cargo-locate-project --- Print a JSON representation of a Cargo.toml file's location + +## SYNOPSIS + +`cargo locate-project` [_options_] + +## DESCRIPTION + +This command will print a JSON object to stdout with the full path to the manifest. The +manifest is found by searching upward for a file named `Cargo.toml` starting from the current +working directory. + +If the project happens to be a part of a workspace, the manifest of the project, rather than +the workspace root, is output. This can be overridden by the `--workspace` flag. The root +workspace is found by traversing further upward or by using the field `package.workspace` after +locating the manifest of a workspace member. + +## OPTIONS + +{{#options}} + +{{#option "`--workspace`" }} +Locate the `Cargo.toml` at the root of the workspace, as opposed to the current +workspace member. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{#option "`--message-format` _fmt_" }} +The representation in which to print the project location. Valid values: + +- `json` (default): JSON object with the path under the key "root". +- `plain`: Just the path. +{{/option}} + +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Display the path to the manifest based on the current directory: + + cargo locate-project + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-login.md b/src/doc/man/cargo-login.md new file mode 100644 index 0000000..11c663c --- /dev/null +++ b/src/doc/man/cargo-login.md @@ -0,0 +1,51 @@ +# cargo-login(1) + +## NAME + +cargo-login --- Save an API token from the registry locally + +## SYNOPSIS + +`cargo login` [_options_] [_token_] + +## DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication, such as {{man "cargo-publish" 1}}, will be automatically +authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` +defaults to `.cargo` in your home directory. + +If the _token_ argument is not specified, it will be read from stdin. + +The API token for crates.io may be retrieved from <https://crates.io/me>. + +Take care to keep the token secret, it should not be shared with anyone else. + +## OPTIONS + +### Login Options + +{{#options}} +{{> options-registry }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Save the API token to disk: + + cargo login + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md new file mode 100644 index 0000000..4f9032d --- /dev/null +++ b/src/doc/man/cargo-metadata.md @@ -0,0 +1,353 @@ +# cargo-metadata(1) + +## NAME + +cargo-metadata --- Machine-readable metadata about the current package + +## SYNOPSIS + +`cargo metadata` [_options_] + +## DESCRIPTION + +Output JSON to stdout containing information about the workspace members and +resolved dependencies of the current package. + +It is recommended to include the `--format-version` flag to future-proof +your code to ensure the output is in the format you are expecting. + +See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) +for a Rust API for reading the metadata. + +## OUTPUT FORMAT + +The output has the following format: + +```javascript +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* The file system path for a local path dependency. + not present if not a path dependency. + */ + "path": "/path/to/dep", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether the target should be documented by `cargo doc`. */ + "doc": true, + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe <user@example.com>" + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The homepage value from the manifest or null if not specified. */ + "homepage": "https://rust-lang.org", + /* The documentation value from the manifest or null if not specified. */ + "documentation": "https://doc.rust-lang.org/stable/std", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } +} +```` + +## OPTIONS + +### Output Options + +{{#options}} + +{{#option "`--no-deps`" }} +Output information only about the workspace members and don't fetch +dependencies. +{{/option}} + +{{#option "`--format-version` _version_" }} +Specify the version of the output format to use. Currently `1` is the only +possible value. +{{/option}} + +{{#option "`--filter-platform` _triple_" }} +This filters the `resolve` output to only include dependencies for the +given [target triple](../appendix/glossary.html#target). +Without this flag, the resolve includes all targets. + +Note that the dependencies listed in the "packages" array still includes all +dependencies. Each package definition is intended to be an unaltered +reproduction of the information within `Cargo.toml`. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Output JSON about the current package: + + cargo metadata --format-version=1 + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-new.md b/src/doc/man/cargo-new.md new file mode 100644 index 0000000..ea6182a --- /dev/null +++ b/src/doc/man/cargo-new.md @@ -0,0 +1,46 @@ +# cargo-new(1) + +## NAME + +cargo-new --- Create a new Cargo package + +## SYNOPSIS + +`cargo new` [_options_] _path_ + +## DESCRIPTION + +This command will create a new Cargo package in the given directory. This +includes a simple template with a `Cargo.toml` manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see `--vcs` below). + +See {{man "cargo-init" 1}} for a similar command which will create a new manifest +in an existing directory. + +## OPTIONS + +### New Options + +{{> options-new }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create a binary Cargo package in the given directory: + + cargo new foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-init" 1}} diff --git a/src/doc/man/cargo-owner.md b/src/doc/man/cargo-owner.md new file mode 100644 index 0000000..3279169 --- /dev/null +++ b/src/doc/man/cargo-owner.md @@ -0,0 +1,81 @@ +# cargo-owner(1) + +## NAME + +cargo-owner --- Manage the owners of a crate on the registry + +## SYNOPSIS + +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] + +## DESCRIPTION + +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care! + +This command requires you to be authenticated with either the `--token` option +or using {{man "cargo-login" 1}}. + +If the crate name is not specified, it will use the package name from the +current directory. + +See [the reference](../reference/publishing.html#cargo-owner) for more +information about owners and publishing. + +## OPTIONS + +### Owner Options + +{{#options}} + +{{#option "`-a`" "`--add` _login_..." }} +Invite the given user or team as an owner. +{{/option}} + +{{#option "`-r`" "`--remove` _login_..." }} +Remove the given user or team as an owner. +{{/option}} + +{{#option "`-l`" "`--list`" }} +List owners of a crate. +{{/option}} + +{{> options-token }} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. List owners of a package: + + cargo owner --list foo + +2. Invite an owner to a package: + + cargo owner --add username foo + +3. Remove an owner from a package: + + cargo owner --remove username foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md new file mode 100644 index 0000000..2000353 --- /dev/null +++ b/src/doc/man/cargo-package.md @@ -0,0 +1,138 @@ +# cargo-package(1) +{{*set actionverb="Package"}} +{{*set noall=true}} +{{*set multitarget=true}} + +## NAME + +cargo-package --- Assemble the local package into a distributable tarball + +## SYNOPSIS + +`cargo package` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory. The resulting file will +be stored in the `target/package` directory. This performs the following +steps: + +1. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. + `dev-dependencies` do not have this restriction. +2. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the + manifest. + - `Cargo.lock` is automatically included if the package contains an + executable binary or example target. {{man "cargo-install" 1}} will use the + packaged lock file if the `--locked` flag is used. + - A `.cargo_vcs_info.json` file is included that contains information + about the current VCS checkout hash if available (not included with + `--allow-dirty`). +3. Extract the `.crate` file and build it to verify it can build. + - This will rebuild your package from scratch to ensure that it can be + built from a pristine state. The `--no-verify` flag can be used to skip + this step. +4. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +### .cargo_vcs_info.json format + +Will generate a `.cargo_vcs_info.json` in the following format + +```javascript +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +``` + +`path_in_vcs` will be set to a repo-relative path for packages +in subdirectories of the version control repository. + +## OPTIONS + +### Package Options + +{{#options}} + +{{#option "`-l`" "`--list`" }} +Print files included in a package without making one. +{{/option}} + +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} + +{{#option "`--no-metadata`" }} +Ignore warnings about a lack of human-usable metadata (such as the description +or the license). +{{/option}} + +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{/options}} + +{{> section-features }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create a compressed `.crate` file of the current package: + + cargo package + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md new file mode 100644 index 0000000..47ed133 --- /dev/null +++ b/src/doc/man/cargo-pkgid.md @@ -0,0 +1,89 @@ +# cargo-pkgid(1) + +## NAME + +cargo-pkgid --- Print a fully qualified package specification + +## SYNOPSIS + +`cargo pkgid` [_options_] [_spec_] + +## DESCRIPTION + +Given a _spec_ argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if _spec_ is ambiguous as to which package it refers to in +the dependency graph. If no _spec_ is given, then the specifier for the local +package is printed. + +This command requires that a lockfile is available and dependencies have been +fetched. + +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a _spec_ can be one of the +following: + +SPEC Structure | Example SPEC +---------------------------|-------------- +_name_ | `bitflags` +_name_`@`_version_ | `bitflags@1.0.4` +_url_ | `https://github.com/rust-lang/cargo` +_url_`#`_version_ | `https://github.com/rust-lang/cargo#0.33.0` +_url_`#`_name_ | `https://github.com/rust-lang/crates.io-index#bitflags` +_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io@0.21.0` + +## OPTIONS + +### Package Selection + +{{#options}} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +Get the package ID for the given package instead of the current package. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Retrieve package specification for `foo` package: + + cargo pkgid foo + +2. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo@1.0.0 + +3. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +4. Retrieve package specification for `foo` from a local package: + + cargo pkgid file:///path/to/local/package#foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md new file mode 100644 index 0000000..4ccb5b5 --- /dev/null +++ b/src/doc/man/cargo-publish.md @@ -0,0 +1,117 @@ +# cargo-publish(1) +{{*set actionverb="Publish"}} +{{*set multitarget=true}} + +## NAME + +cargo-publish --- Upload a package to the registry + +## SYNOPSIS + +`cargo publish` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory and upload it to a +registry. The default registry is <https://crates.io>. This performs the +following steps: + +1. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on + which registries you are allowed to publish to. +2. Create a `.crate` file by following the steps in {{man "cargo-package" 1}}. +3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using {{man "cargo-login" 1}}. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Publish Options + +{{#options}} + +{{#option "`--dry-run`" }} +Perform all checks without uploading. +{{/option}} + +{{> options-token }} + +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} + +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} + +{{> options-index }} + +{{#option "`--registry` _registry_"}} +Name of the registry to publish to. Registry names are defined in [Cargo +config files](../reference/config.html). If not specified, and there is a +[`package.publish`](../reference/manifest.html#the-publish-field) field in +`Cargo.toml` with a single registry, then it will publish to that registry. +Otherwise it will use the default registry, which is defined by the +[`registry.default`](../reference/config.html#registrydefault) config key +which defaults to `crates-io`. +{{/option}} + +{{/options}} + +{{> section-options-package }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{/options}} + +{{> section-features }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Publish the current package: + + cargo publish + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}}, {{man "cargo-login" 1}} diff --git a/src/doc/man/cargo-remove.md b/src/doc/man/cargo-remove.md new file mode 100644 index 0000000..0722e6e --- /dev/null +++ b/src/doc/man/cargo-remove.md @@ -0,0 +1,92 @@ +# cargo-remove(1) +{{*set actionverb="Remove"}} +{{*set nouns="removes"}} + +## NAME + +cargo-remove --- Remove dependencies from a Cargo.toml manifest file + +## SYNOPSIS + +`cargo remove` [_options_] _dependency_... + +## DESCRIPTION + +Remove one or more dependencies from a `Cargo.toml` manifest. + +## OPTIONS + +### Section options + +{{#options}} + +{{#option "`--dev`" }} +Remove as a [development dependency](../reference/specifying-dependencies.html#development-dependencies). +{{/option}} + +{{#option "`--build`" }} +Remove as a [build dependency](../reference/specifying-dependencies.html#build-dependencies). +{{/option}} + +{{#option "`--target` _target_" }} +Remove as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies). +{{/option}} + +{{/options}} + +### Miscellaneous Options + +{{#options}} + +{{#option "`--dry-run`" }} +Don't actually write to the manifest. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +### Package Selection + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Package to remove from. +{{/option}} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Remove `regex` as a dependency + + cargo remove regex + +2. Remove `trybuild` as a dev-dependency + + cargo remove --dev trybuild + +3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table + + cargo remove --target x86_64-pc-windows-gnu nom + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-add" 1}} diff --git a/src/doc/man/cargo-report.md b/src/doc/man/cargo-report.md new file mode 100644 index 0000000..ba33617 --- /dev/null +++ b/src/doc/man/cargo-report.md @@ -0,0 +1,42 @@ +# cargo-report(1) + +## NAME + +cargo-report --- Generate and display various kinds of reports + +## SYNOPSIS + +`cargo report` _type_ [_options_] + +### DESCRIPTION + +Displays a report of the given _type_ --- currently, only `future-incompat` is supported + +## OPTIONS + +{{#options}} + +{{#option "`--id` _id_" }} +Show the report with the specified Cargo-generated id +{{/option}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Only display a report for the specified package +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +## SEE ALSO +[Future incompat report](../reference/future-incompat-report.html) + +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md new file mode 100644 index 0000000..4b6b935 --- /dev/null +++ b/src/doc/man/cargo-run.md @@ -0,0 +1,111 @@ +# cargo-run(1) +{{*set actionverb="Run"}} + +## NAME + +cargo-run --- Run the current package + +## SYNOPSIS + +`cargo run` [_options_] [`--` _args_] + +## DESCRIPTION + +Run a binary or example of the local package. + +All the arguments following the two dashes (`--`) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +`--` go to the binary, the ones before go to Cargo. + +## OPTIONS + +{{> section-options-package }} + +### Target Selection + +When no target selection options are given, `cargo run` will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. Or, the `default-run` field may be specified in the `[package]` +section of `Cargo.toml` to choose the name of the binary to run by default. + +{{#options}} + +{{#option "`--bin` _name_" }} +Run the specified binary. +{{/option}} + +{{#option "`--example` _name_" }} +Run the specified example. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build the local package and run its main target (assuming only one binary): + + cargo run + +2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md new file mode 100644 index 0000000..f3b3723 --- /dev/null +++ b/src/doc/man/cargo-rustc.md @@ -0,0 +1,145 @@ +# cargo-rustc(1) +{{*set actionverb="Build"}} +{{*set multitarget=true}} + +## NAME + +cargo-rustc --- Compile the current package, and pass extra options to the compiler + +## SYNOPSIS + +`cargo rustc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be compiled along with all of its dependencies. The specified +_args_ will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as `-L`, `--extern`, and `--crate-type`, and the specified +_args_ will simply be added to the compiler invocation. + +See <https://doc.rust-lang.org/rustc/index.html> for documentation on rustc +flags. + +{{> description-one-target }} +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +[environment variable](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). + +## OPTIONS + +{{> section-options-package }} + +### Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{#option "`--profile` _name_" }} +Build with the given profile. + +The `rustc` subcommand will treat the following named profiles with special behaviors: + +* `check` --- Builds in the same way as the {{man "cargo-check" 1}} command with + the `dev` profile. +* `test` --- Builds in the same way as the {{man "cargo-test" 1}} command, + enabling building in test mode which will enable tests and enable the `test` + cfg option. See [rustc + tests](https://doc.rust-lang.org/rustc/tests/index.html) for more detail. +* `bench` --- Builds in the same was as the {{man "cargo-bench" 1}} command, + similar to the `test` profile. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{#option "`--crate-type` _crate-type_"}} +Build for the given crate type. This flag accepts a comma-separated list of +1 or more crate types, of which the allowed values are the same as `crate-type` +field in the manifest for configurating a Cargo target. See +[`crate-type` field](../reference/cargo-targets.html#the-crate-type-field) +for possible values. + +If the manifest contains a list, and `--crate-type` is provided, +the command-line argument value will override what is in the manifest. + +This flag only works when building a `lib` or `example` library target. +{{/option}} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + +2. Try an experimental flag on the nightly compiler, such as this which prints + the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +3. Override `crate-type` field in Cargo.toml with command-line option: + + cargo rustc --lib --crate-type lib,cdylib + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}}, {{man "rustc" 1}} diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md new file mode 100644 index 0000000..23be579 --- /dev/null +++ b/src/doc/man/cargo-rustdoc.md @@ -0,0 +1,116 @@ +# cargo-rustdoc(1) +{{*set actionverb="Document"}} +{{*set multitarget=true}} + +## NAME + +cargo-rustdoc --- Build a package's documentation, using specified custom flags + +## SYNOPSIS + +`cargo rustdoc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be documented with the specified _args_ being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as `-L`, `--extern`, and `--crate-type`, and the specified _args_ will simply +be added to the rustdoc invocation. + +See <https://doc.rust-lang.org/rustdoc/index.html> for documentation on rustdoc +flags. + +{{> description-one-target }} +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). + +## OPTIONS + +### Documentation Options + +{{#options}} + +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. +{{/option}} + +{{/options}} + +{{> section-options-package }} + +### Target Selection + +When no target selection options are given, `cargo rustdoc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-doc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/cargo-search.md b/src/doc/man/cargo-search.md new file mode 100644 index 0000000..f3d87cb --- /dev/null +++ b/src/doc/man/cargo-search.md @@ -0,0 +1,52 @@ +# cargo-search(1) + +## NAME + +cargo-search --- Search packages in crates.io + +## SYNOPSIS + +`cargo search` [_options_] [_query_...] + +## DESCRIPTION + +This performs a textual search for crates on <https://crates.io>. The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +## OPTIONS + +### Search Options + +{{#options}} + +{{#option "`--limit` _limit_" }} +Limit the number of results (default: 10, max: 100). +{{/option}} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Search for a package from crates.io: + + cargo search serde + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-install" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md new file mode 100644 index 0000000..0b6da16 --- /dev/null +++ b/src/doc/man/cargo-test.md @@ -0,0 +1,191 @@ +# cargo-test(1) +{{*set actionverb="Test"}} +{{*set nouns="tests"}} +{{*set multitarget=true}} + +## NAME + +cargo-test --- Execute unit and integration tests of a package + +## SYNOPSIS + +`cargo test` [_options_] [_testname_] [`--` _test-options_] + +## DESCRIPTION + +Compile and execute unit, integration, and documentation tests. + +The test filtering argument `TESTNAME` and all the arguments following the two +dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's +built in unit-test and micro-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after `--` go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of `cargo test -- --help` and check out the rustc book's chapter on +how tests work at <https://doc.rust-lang.org/rustc/tests/index.html>. + +As an example, this will filter for tests with `foo` in their name and run them +on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + +Tests are built with the `--test` option to `rustc` which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the `#[test]` attribute in multiple threads. +`#[bench]` annotated functions will also be run with one iteration to verify +that they are functional. + +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running tests. + +### Documentation tests + +Documentation tests are also run by default, which is handled by `rustdoc`. It +extracts code samples from documentation comments of the library target, and +then executes them. + +Different from normal test targets, each code block compiles to a doctest +executable on the fly with `rustc`. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as `--jobs` might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. + +See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information +on writing doc tests. + +## OPTIONS + +### Test Options + +{{> options-test }} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo test` will build the +following targets of the selected packages: + +- lib --- used to link with binaries, examples, integration tests, and doc tests +- bins (only if integration tests are built and required features are + available) +- examples --- to ensure they compile +- lib as a unit test +- bins as unit tests +- integration tests +- doc tests for the lib target + +The default behavior can be changed by setting the `test` flag for the target +in the manifest settings. Setting examples to `test = true` will build and run +the example as a test. Setting targets to `test = false` will stop them from +being tested by default. Target selection options that take a target by name +ignore the `test` flag and will always test the given target. + +Doc tests for libraries may be disabled by setting `doctest = false` for the +library in the manifest. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{#options}} + +{{#option "`--doc`" }} +Test only the library's documentation. This cannot be mixed with other +target options. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g., for debugging) by passing +`--nocapture` to the test binaries: + + cargo test -- --nocapture + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +The `--jobs` argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + +{{#options}} + +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} + +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Execute all the unit and integration tests of the current package: + + cargo test + +2. Run only tests whose names match against a filter string: + + cargo test name_filter + +3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-bench" 1}}, [types of tests](../reference/cargo-targets.html#tests), [how to write tests](https://doc.rust-lang.org/rustc/tests/index.html) diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md new file mode 100644 index 0000000..3e1da20 --- /dev/null +++ b/src/doc/man/cargo-tree.md @@ -0,0 +1,268 @@ +# cargo-tree(1) +{{*set actionverb="Display"}} +{{*set noall=true}} + +## NAME + +cargo-tree --- Display a tree visualization of a dependency graph + +## SYNOPSIS + +`cargo tree` [_options_] + +## DESCRIPTION + +This command will display a tree of dependencies to the terminal. An example +of a simple project that depends on the "rand" package: + +``` +myproject v0.1.0 (/myproject) +└── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) +[build-dependencies] +└── cc v1.0.50 +``` + +Packages marked with `(*)` have been "de-duplicated". The dependencies for the +package have already been shown elsewhere in the graph, and so are not +repeated. Use the `--no-dedupe` option to repeat the duplicates. + +The `-e` flag can be used to select the dependency kinds to display. The +"features" kind changes the output to display the features enabled by +each dependency. For example, `cargo tree -e features`: + +``` +myproject v0.1.0 (/myproject) +└── log feature "serde" + └── log v0.4.8 + ├── serde v1.0.106 + └── cfg-if feature "default" + └── cfg-if v0.1.10 +``` + +In this tree, `myproject` depends on `log` with the `serde` feature. `log` in +turn depends on `cfg-if` with "default" features. When using `-e features` it +can be helpful to use `-i` flag to show how the features flow into a package. +See the examples below for more detail. + +### Feature Unification + +This command shows a graph much closer to a feature-unified graph Cargo will +build, rather than what you list in `Cargo.toml`. For instance, if you specify +the same dependency in both `[dependencies]` and `[dev-dependencies]` but with +different features on. This command may merge all features and show a `(*)` on +one of the dependency to indicate the duplicate. + +As a result, for a mostly equivalent overview of what `cargo build` does, +`cargo tree -e normal,build` is pretty close; for a mostly equivalent overview +of what `cargo test` does, `cargo tree` is pretty close. However, it doesn't +guarantee the exact equivalence to what Cargo is going to build, since a +compilation is complex and depends on lots of different factors. + +To learn more about feature unification, check out this +[dedicated section](../reference/features.html#feature-unification). + +## OPTIONS + +### Tree Options + +{{#options}} + +{{#option "`-i` _spec_" "`--invert` _spec_" }} +Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package. + +Note that in a workspace, by default it will only display the package's +reverse dependencies inside the tree of the workspace member in the current +directory. The `--workspace` flag can be used to extend it so that it will +show the package's reverse dependencies across the entire workspace. The `-p` +flag can be used to display the package's reverse dependencies only with the +subtree of the package given to `-p`. +{{/option}} + +{{#option "`--prune` _spec_" }} +Prune the given package from the display of the dependency tree. +{{/option}} + +{{#option "`--depth` _depth_" }} +Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example. +{{/option}} + +{{#option "`--no-dedupe`" }} +Do not de-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re-display its +dependencies, and will include a `(*)` to indicate it has already been shown. +This flag will cause those duplicates to be repeated. +{{/option}} + +{{#option "`-d`" "`--duplicates`" }} +Show only dependencies which come in multiple versions (implies `--invert`). +When used with the `-p` flag, only shows duplicates within the subtree of the +given package. + +It can be beneficial for build times and executable sizes to avoid building +that same package multiple times. This flag can help identify the offending +packages. You can then investigate if the package that depends on the +duplicate with the older version can be updated to the newer version so that +only one instance is built. +{{/option}} + +{{#option "`-e` _kinds_" "`--edges` _kinds_" }} +The dependency kinds to display. Takes a comma separated list of values: + +- `all` --- Show all edge kinds. +- `normal` --- Show normal dependencies. +- `build` --- Show build dependencies. +- `dev` --- Show development dependencies. +- `features` --- Show features enabled by each dependency. If this is the only + kind given, then it will automatically include the other dependency kinds. +- `no-normal` --- Do not include normal dependencies. +- `no-build` --- Do not include build dependencies. +- `no-dev` --- Do not include development dependencies. +- `no-proc-macro` --- Do not include procedural macro dependencies. + +The `normal`, `build`, `dev`, and `all` dependency kinds cannot be mixed with +`no-normal`, `no-build`, or `no-dev` dependency kinds. + +The default is `normal,build,dev`. +{{/option}} + +{{#option "`--target` _triple_" }} +Filter dependencies matching the given [target triple](../appendix/glossary.html#target). +The default is the host platform. Use the value `all` to include *all* targets. +{{/option}} + +{{/options}} + +### Tree Formatting Options + +{{#options}} + +{{#option "`--charset` _charset_" }} +Chooses the character set to use for the tree. Valid values are "utf8" or +"ascii". Default is "utf8". +{{/option}} + +{{#option "`-f` _format_" "`--format` _format_" }} +Set the format string for each package. The default is "{p}". + +This is an arbitrary string which will be used to display each package. The following +strings will be replaced with the corresponding value: + +- `{p}` --- The package name. +- `{l}` --- The package license. +- `{r}` --- The package repository URL. +- `{f}` --- Comma-separated list of package features that are enabled. +- `{lib}` --- The name, as used in a `use` statement, of the package's library. +{{/option}} + +{{#option "`--prefix` _prefix_" }} +Sets how each line is displayed. The _prefix_ value can be one of: + +- `indent` (default) --- Shows each line indented as a tree. +- `depth` --- Show as a list, with the numeric depth printed before each entry. +- `none` --- Show as a flat list. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-features }} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Display the tree for the package in the current directory: + + cargo tree + +2. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +4. Show all packages that are built multiple times. This can happen if multiple + semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). + + cargo tree -d + +5. Explain why features are enabled for the `syn` package: + + cargo tree -e features -i syn + + The `-e features` flag is used to show features. The `-i` flag is used to + invert the graph so that it displays the packages that depend on `syn`. An + example of what this would display: + + ``` + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + ``` + + To read this graph, you can follow the chain for each feature from the root + to see why it is included. For example, the "full" feature is added by the + `rustversion` crate which is included from `myproject` (with the default + features), and `myproject` is the package selected on the command-line. All + of the other `syn` features are added by the "default" feature ("quote" is + added by "printing" and "proc-macro", both of which are default features). + + If you're having difficulty cross-referencing the de-duplicated `(*)` + entries, try with the `--no-dedupe` flag to get the full output. + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-uninstall.md b/src/doc/man/cargo-uninstall.md new file mode 100644 index 0000000..b2ebd09 --- /dev/null +++ b/src/doc/man/cargo-uninstall.md @@ -0,0 +1,63 @@ +# cargo-uninstall(1) + +## NAME + +cargo-uninstall --- Remove a Rust binary + +## SYNOPSIS + +`cargo uninstall` [_options_] [_spec_...] + +## DESCRIPTION + +This command removes a package installed with {{man "cargo-install" 1}}. The _spec_ +argument is a package ID specification of the package to remove (see +{{man "cargo-pkgid" 1}}). + +By default all binaries are removed for a crate but the `--bin` and +`--example` flags can be used to only remove particular binaries. + +{{> description-install-root }} + +## OPTIONS + +### Install Options + +{{#options}} + +{{#option "`-p`" "`--package` _spec_..." }} +Package to uninstall. +{{/option}} + +{{#option "`--bin` _name_..." }} +Only uninstall the binary _name_. +{{/option}} + +{{#option "`--root` _dir_" }} +Directory to uninstall packages from. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-install" 1}} diff --git a/src/doc/man/cargo-update.md b/src/doc/man/cargo-update.md new file mode 100644 index 0000000..e91606a --- /dev/null +++ b/src/doc/man/cargo-update.md @@ -0,0 +1,97 @@ +# cargo-update(1) + +## NAME + +cargo-update --- Update dependencies as recorded in the local lock file + +## SYNOPSIS + +`cargo update` [_options_] + +## DESCRIPTION + +This command will update dependencies in the `Cargo.lock` file to the latest +version. If the `Cargo.lock` file does not exist, it will be created with the +latest available versions. + +## OPTIONS + +### Update Options + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Update only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. + +If packages are specified with the `-p` flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. + +If `-p` is not specified, all dependencies are updated. +{{/option}} + +{{#option "`--aggressive`" }} +When used with `-p`, dependencies of _spec_ are forced to update as well. +Cannot be used with `--precise`. +{{/option}} + +{{#option "`--precise` _precise_" }} +When used with `-p`, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag). +{{/option}} + +{{#option "`-w`" "`--workspace`" }} +Attempt to update only packages defined in the workspace. Other packages +are updated only if they don't already exist in the lockfile. This +option is useful for updating `Cargo.lock` after you've changed version +numbers in `Cargo.toml`. +{{/option}} + +{{#option "`--dry-run`" }} +Displays what would be updated, but doesn't actually write the lockfile. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Update all dependencies in the lockfile: + + cargo update + +2. Update only specific dependencies: + + cargo update -p foo -p bar + +3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}} diff --git a/src/doc/man/cargo-vendor.md b/src/doc/man/cargo-vendor.md new file mode 100644 index 0000000..b30d0d8 --- /dev/null +++ b/src/doc/man/cargo-vendor.md @@ -0,0 +1,93 @@ +# cargo-vendor(1) + +## NAME + +cargo-vendor --- Vendor all dependencies locally + +## SYNOPSIS + +`cargo vendor` [_options_] [_path_] + +## DESCRIPTION + +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at `<path>`. After this command completes +the vendor directory specified by `<path>` will contain all remote sources from +dependencies specified. Additional manifests beyond the default one can be +specified with the `-s` option. + +The `cargo vendor` command will also print out the configuration necessary +to use the vendored sources, which you will need to add to `.cargo/config.toml`. + +## OPTIONS + +### Vendor Options + +{{#options}} + +{{#option "`-s` _manifest_" "`--sync` _manifest_" }} +Specify an extra `Cargo.toml` manifest to workspaces which should also be +vendored and synced to the output. May be specified multiple times. +{{/option}} + +{{#option "`--no-delete`" }} +Don't delete the "vendor" directory when vendoring, but rather keep all +existing contents of the vendor directory +{{/option}} + +{{#option "`--respect-source-config`" }} +Instead of ignoring `[source]` configuration by default in `.cargo/config.toml` +read it and use it when downloading crates from crates.io, for example +{{/option}} + +{{#option "`--versioned-dirs`" }} +Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the "vendor" directory +to be versioned, which makes it easier to track the history of vendored +packages over time, and can help with the performance of re-vendoring when +only a subset of the packages have changed. +{{/option}} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Vendor all dependencies into a local "vendor" folder + + cargo vendor + +2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +## SEE ALSO +{{man "cargo" 1}} + diff --git a/src/doc/man/cargo-verify-project.md b/src/doc/man/cargo-verify-project.md new file mode 100644 index 0000000..8b334fb --- /dev/null +++ b/src/doc/man/cargo-verify-project.md @@ -0,0 +1,58 @@ +# cargo-verify-project(1) + +## NAME + +cargo-verify-project --- Check correctness of crate manifest + +## SYNOPSIS + +`cargo verify-project` [_options_] + +## DESCRIPTION + +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +## OPTIONS + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +## EXIT STATUS + +* `0`: The workspace is OK. +* `1`: The workspace is invalid. + +## EXAMPLES + +1. Check the current workspace for errors: + + cargo verify-project + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}} diff --git a/src/doc/man/cargo-version.md b/src/doc/man/cargo-version.md new file mode 100644 index 0000000..9bbadc9 --- /dev/null +++ b/src/doc/man/cargo-version.md @@ -0,0 +1,41 @@ +# cargo-version(1) + +## NAME + +cargo-version --- Show version information + +## SYNOPSIS + +`cargo version` [_options_] + +## DESCRIPTION + +Displays the version of Cargo. + +## OPTIONS + +{{#options}} + +{{#option "`-v`" "`--verbose`" }} +Display additional version information. +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Display the version: + + cargo version + +2. The version is also available via flags: + + cargo --version + cargo -V + +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md new file mode 100644 index 0000000..8ad28ef --- /dev/null +++ b/src/doc/man/cargo-yank.md @@ -0,0 +1,71 @@ +# cargo-yank(1) + +## NAME + +cargo-yank --- Remove a pushed crate from the index + +## SYNOPSIS + +`cargo yank` [_options_] _crate_@_version_\ +`cargo yank` [_options_] `--version` _version_ [_crate_] + +## DESCRIPTION + +The yank command removes a previously published crate's version from the +server's index. This command does not delete any data, and the crate will +still be available for download via the registry's download link. + +Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version. + +This command requires you to be authenticated with either the `--token` option +or using {{man "cargo-login" 1}}. + +If the crate name is not specified, it will use the package name from the +current directory. + +## OPTIONS + +### Yank Options + +{{#options}} + +{{#option "`--vers` _version_" "`--version` _version_" }} +The version to yank or un-yank. +{{/option}} + +{{#option "`--undo`" }} +Undo a yank, putting a version back into the index. +{{/option}} + +{{> options-token }} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Yank a crate from the index: + + cargo yank foo@1.0.7 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md new file mode 100644 index 0000000..2d71fc4 --- /dev/null +++ b/src/doc/man/cargo.md @@ -0,0 +1,235 @@ +# cargo(1) + +## NAME + +cargo --- The Rust package manager + +## SYNOPSIS + +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ + +## DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at <https://rust-lang.org>. + +## COMMANDS + +### Build Commands + +{{man "cargo-bench" 1}}\ + Execute benchmarks of a package. + +{{man "cargo-build" 1}}\ + Compile a package. + +{{man "cargo-check" 1}}\ + Check a local package and all of its dependencies for errors. + +{{man "cargo-clean" 1}}\ + Remove artifacts that Cargo has generated in the past. + +{{man "cargo-doc" 1}}\ + Build a package's documentation. + +{{man "cargo-fetch" 1}}\ + Fetch dependencies of a package from the network. + +{{man "cargo-fix" 1}}\ + Automatically fix lint warnings reported by rustc. + +{{man "cargo-run" 1}}\ + Run a binary or example of the local package. + +{{man "cargo-rustc" 1}}\ + Compile a package, and pass extra options to the compiler. + +{{man "cargo-rustdoc" 1}}\ + Build a package's documentation, using specified custom flags. + +{{man "cargo-test" 1}}\ + Execute unit and integration tests of a package. + +### Manifest Commands + +{{man "cargo-generate-lockfile" 1}}\ + Generate `Cargo.lock` for a project. + +{{man "cargo-locate-project" 1}}\ + Print a JSON representation of a `Cargo.toml` file's location. + +{{man "cargo-metadata" 1}}\ + Output the resolved dependencies of a package in machine-readable format. + +{{man "cargo-pkgid" 1}}\ + Print a fully qualified package specification. + +{{man "cargo-tree" 1}}\ + Display a tree visualization of a dependency graph. + +{{man "cargo-update" 1}}\ + Update dependencies as recorded in the local lock file. + +{{man "cargo-vendor" 1}}\ + Vendor all dependencies locally. + +{{man "cargo-verify-project" 1}}\ + Check correctness of crate manifest. + +### Package Commands + +{{man "cargo-init" 1}}\ + Create a new Cargo package in an existing directory. + +{{man "cargo-install" 1}}\ + Build and install a Rust binary. + +{{man "cargo-new" 1}}\ + Create a new Cargo package. + +{{man "cargo-search" 1}}\ + Search packages in crates.io. + +{{man "cargo-uninstall" 1}}\ + Remove a Rust binary. + +### Publishing Commands + +{{man "cargo-login" 1}}\ + Save an API token from the registry locally. + +{{man "cargo-owner" 1}}\ + Manage the owners of a crate on the registry. + +{{man "cargo-package" 1}}\ + Assemble the local package into a distributable tarball. + +{{man "cargo-publish" 1}}\ + Upload a package to the registry. + +{{man "cargo-yank" 1}}\ + Remove a pushed crate from the index. + +### General Commands + +{{man "cargo-help" 1}}\ + Display help information about Cargo. + +{{man "cargo-version" 1}}\ + Show version information. + +## OPTIONS + +### Special Options + +{{#options}} + +{{#option "`-V`" "`--version`" }} +Print version info and exit. If used with `--verbose`, prints extra +information. +{{/option}} + +{{#option "`--list`" }} +List all installed Cargo subcommands. If used with `--verbose`, prints extra +information. +{{/option}} + +{{#option "`--explain` _code_" }} +Run `rustc --explain CODE` which will print out a detailed explanation of an +error message (for example, `E0004`). +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## FILES + +`~/.cargo/`\ + Default location for Cargo's "home" directory where it +stores various files. The location can be changed with the `CARGO_HOME` +environment variable. + +`$CARGO_HOME/bin/`\ + Binaries installed by {{man "cargo-install" 1}} will be located here. If using +[rustup], executables distributed with Rust are also located here. + +`$CARGO_HOME/config.toml`\ + The global configuration file. See [the reference](../reference/config.html) +for more information about configuration files. + +`.cargo/config.toml`\ + Cargo automatically searches for a file named `.cargo/config.toml` in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. + +`$CARGO_HOME/credentials.toml`\ + Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ + This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ + This directory contains cached downloads of git dependencies. + +Please note that the internal structure of the `$CARGO_HOME` directory is not +stable yet and may be subject to change. + +[rustup]: https://rust-lang.github.io/rustup/ + +## EXAMPLES + +1. Build a local package and all of its dependencies: + + cargo build + +2. Build a package with optimizations: + + cargo build --release + +3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +4. Create a new package that builds an executable: + + cargo new foobar + +5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +6. Learn about a command's options and usage: + + cargo help clean + +## BUGS + +See <https://github.com/rust-lang/cargo/issues> for issues. + +## SEE ALSO +{{man "rustc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/generated_txt/cargo-add.txt b/src/doc/man/generated_txt/cargo-add.txt new file mode 100644 index 0000000..fdde1fe --- /dev/null +++ b/src/doc/man/generated_txt/cargo-add.txt @@ -0,0 +1,236 @@ +CARGO-ADD(1) + +NAME + cargo-add — Add dependencies to a Cargo.toml manifest file + +SYNOPSIS + cargo add [options] crate… + cargo add [options] --path path + cargo add [options] --git url [crate…] + +DESCRIPTION + This command can add or modify dependencies. + + The source for the dependency can be specified with: + + o crate@version: Fetch from a registry with a version constraint of + “version” + + o --path path: Fetch from the specified path + + o --git url: Pull from a git repo at url + + If no source is specified, then a best effort will be made to select + one, including: + + o Existing dependencies in other tables (like dev-dependencies) + + o Workspace members + + o Latest release in the registry + + When you add a package that is already present, the existing entry will + be updated with the flags specified. + + Upon successful invocation, the enabled (+) and disabled (-) features + <https://doc.rust-lang.org/cargo/reference/features.md> of the specified + dependency will be listed in the command’s output. + +OPTIONS + Source options + --git url + Git URL to add the specified crate from + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories>. + + --branch branch + Branch to use when adding from git. + + --tag tag + Tag to use when adding from git. + + --rev sha + Specific commit to use when adding from git. + + --path path + Filesystem path + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies> + to local crate to add. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Section options + --dev + Add as a development dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>. + + --build + Add as a build dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>. + + --target target + Add as a dependency to the given target platform + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>. + +</dl> + + Dependency options + --dry-run + Don’t actually write the manifest + + --rename name + Rename + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml> + the dependency. + + --optional + Mark the dependency as optional + <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>. + + --no-optional + Mark the dependency as required + <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>. + + --no-default-features + Disable the default features + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + + --default-features + Re-enable the default features + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + + -F features, --features features + Space or comma separated list of features to activate + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + When adding multiple crates, the features for a specific crate may + be enabled with package-name/feature-name syntax. This flag may be + specified multiple times, which enables all specified features. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + -p spec, --package spec + Add dependencies to only the specified package. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Add regex as a dependency + + cargo add regex + + 2. Add trybuild as a dev-dependency + + cargo add --dev trybuild + + 3. Add an older version of nom as a dependency + + cargo add nom@5 + + 4. Add support for serializing data structures to json with derives + + cargo add serde serde_json -F serde/derive + +SEE ALSO + cargo(1), cargo-remove(1) + diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt new file mode 100644 index 0000000..78eed19 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -0,0 +1,425 @@ +CARGO-BENCH(1) + +NAME + cargo-bench — Execute benchmarks of a package + +SYNOPSIS + cargo bench [options] [benchname] [-- bench-options] + +DESCRIPTION + Compile and execute benchmarks. + + The benchmark filtering argument benchname and all the arguments + following the two dashes (--) are passed to the benchmark binaries and + thus to libtest (rustc’s built in unit-test and micro-benchmarking + framework). If you are passing arguments to both Cargo and the binary, + the ones after -- go to the binary, the ones before go to Cargo. For + details about libtest’s arguments see the output of cargo bench -- + --help and check out the rustc book’s chapter on how tests work at + <https://doc.rust-lang.org/rustc/tests/index.html>. + + As an example, this will run only the benchmark named foo (and skip + other similarly named benchmarks like foobar): + + cargo bench -- foo --exact + + Benchmarks are built with the --test option to rustc which creates a + special executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[bench] attribute. + Cargo passes the --bench flag to the test harness to tell it to run only + benchmarks. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running benchmarks. + + Note: The #[bench] attribute + <https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html> + is currently unstable and only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html>. There + are some packages available on crates.io + <https://crates.io/keywords/benchmark> that may help with running + benchmarks on the stable channel, such as Criterion + <https://crates.io/crates/criterion>. + + By default, cargo bench uses the bench profile + <https://doc.rust-lang.org/cargo/reference/profiles.html#bench>, which + enables optimizations and disables debugging information. If you need to + debug a benchmark, you can use the --profile=dev command-line option to + switch to the dev profile. You can then run the debug-enabled benchmark + within a debugger. + +OPTIONS + Benchmark Options + --no-run + Compile, but don’t run benchmarks. + + --no-fail-fast + Run all benchmarks regardless of failure. Without this flag, Cargo + will exit after the first executable fails. The Rust test harness + will run all benchmarks within the executable to completion, this + flag only applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Benchmark only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Benchmark all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo bench will build the + following targets of the selected packages: + + o lib — used to link with binaries and benchmarks + + o bins (only if benchmark targets are built and required features are + available) + + o lib as a benchmark + + o bins as benchmarks + + o benchmark targets + + The default behavior can be changed by setting the bench flag for the + target in the manifest settings. Setting examples to bench = true will + build and run the example as a benchmark. Setting targets to bench = + false will stop them from being benchmarked by default. Target selection + options that take a target by name ignore the bench flag and will always + benchmark the given target. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to benchmark. This allows an integration + test to execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will benchmark only the specified + targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Benchmark the package’s library. + + --bin name… + Benchmark the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Benchmark all binary targets. + + --example name… + Benchmark the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Benchmark all example targets. + + --test name… + Benchmark the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Benchmark all targets in test mode that have the test = true + manifest flag set. By default this includes the library and binaries + built as unittests, and integration tests. Be aware that this will + also build any required dependencies, so the lib target may be built + twice (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Benchmark the specified benchmark. This flag may be specified + multiple times and supports common Unix glob patterns. + + --benches + Benchmark all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Benchmark all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Benchmark for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --profile name + Benchmark with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Benchmark the target even if the selected Rust compiler is older + than the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + By default the Rust test harness hides output from benchmark execution + to keep results readable. Benchmark output can be recovered (e.g., for + debugging) by passing --nocapture to the benchmark binaries: + + cargo bench -- --nocapture + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + The --jobs argument affects the building of the benchmark executable but + does not affect how many threads are used when running the benchmarks. + The Rust test harness runs benchmarks serially in a single thread. + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build and execute all the benchmarks of the current package: + + cargo bench + + 2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +SEE ALSO + cargo(1), cargo-test(1) + diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt new file mode 100644 index 0000000..8b5b778 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -0,0 +1,376 @@ +CARGO-BUILD(1) + +NAME + cargo-build — Compile the current package + +SYNOPSIS + cargo build [options] + +DESCRIPTION + Compile local packages and all of their dependencies. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Build only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Build all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo build will build all + binary and library targets of the selected packages. Binaries are + skipped if they have required-features that are missing. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will build only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Build the package’s library. + + --bin name… + Build the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Build all binary targets. + + --example name… + Build the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Build all example targets. + + --test name… + Build the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Build all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Build the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + --out-dir directory + Copy final artifacts to this directory. + + This option is unstable and available only on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable. See + <https://github.com/rust-lang/cargo/issues/6790> for more + information. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + --build-plan + Outputs a series of JSON messages to stdout that indicate the + commands to run the build. + + This option is unstable and available only on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable. See + <https://github.com/rust-lang/cargo/issues/5579> for more + information. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and all of its dependencies: + + cargo build + + 2. Build with optimizations: + + cargo build --release + +SEE ALSO + cargo(1), cargo-rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt new file mode 100644 index 0000000..4946371 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -0,0 +1,361 @@ +CARGO-CHECK(1) + +NAME + cargo-check — Check the current package + +SYNOPSIS + cargo check [options] + +DESCRIPTION + Check a local package and all of its dependencies for errors. This will + essentially compile the packages without performing the final step of + code generation, which is faster than running cargo build. The compiler + will save metadata files to disk so that future runs will reuse them if + the source has not been modified. Some diagnostics and errors are only + emitted during code generation, so they inherently won’t be reported + with cargo check. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Check only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Check all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo check will check all + binary and library targets of the selected packages. Binaries are + skipped if they have required-features that are missing. + + Passing target selection flags will check only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Check the package’s library. + + --bin name… + Check the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Check all binary targets. + + --example name… + Check the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Check all example targets. + + --test name… + Check the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Check all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Check the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Check all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Check all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Check for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Check optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Check with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more detail. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Check the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check the local package for errors: + + cargo check + + 2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-clean.txt b/src/doc/man/generated_txt/cargo-clean.txt new file mode 100644 index 0000000..a145ed8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-clean.txt @@ -0,0 +1,170 @@ +CARGO-CLEAN(1) + +NAME + cargo-clean — Remove generated artifacts + +SYNOPSIS + cargo clean [options] + +DESCRIPTION + Remove artifacts from the target directory that Cargo has generated in + the past. + + With no options, cargo clean will delete the entire target directory. + +OPTIONS + Package Selection + When no packages are selected, all packages and all dependencies in the + workspace are cleaned. + + -p spec…, --package spec… + Clean only the specified packages. This flag may be specified + multiple times. See cargo-pkgid(1) for the SPEC format. + + Clean Options + --doc + This option will cause cargo clean to remove only the doc directory + in the target directory. + + --release + Remove all artifacts in the release directory. + + --profile name + Remove all artifacts in the directory with the given profile name. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + --target triple + Clean for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove the entire target directory: + + cargo clean + + 2. Remove only the release artifacts: + + cargo clean --release + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt new file mode 100644 index 0000000..5a8b39f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -0,0 +1,323 @@ +CARGO-DOC(1) + +NAME + cargo-doc — Build a package’s documentation + +SYNOPSIS + cargo doc [options] + +DESCRIPTION + Build the documentation for the local package and all dependencies. The + output is placed in target/doc in rustdoc’s usual format. + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable or use the doc.browser + <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser> + configuration option. + + --no-deps + Do not build documentation for dependencies. + + --document-private-items + Include non-public items in the documentation. This will be enabled + by default if documenting a binary target. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Document only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Document all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo doc will document all + binary and library targets of the selected package. The binary will be + skipped if its name is the same as the lib target. Binaries are skipped + if they have required-features that are missing. + + The default behavior can be changed by setting doc = false for the + target in the manifest settings. Using target selection options will + ignore the doc flag and will always document the given target. + + --lib + Document the package’s library. + + --bin name… + Document the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Document all binary targets. + + --example name… + Document the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Document all example targets. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package documentation and its dependencies and output + to target/doc. + + cargo doc + +SEE ALSO + cargo(1), cargo-rustdoc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-fetch.txt b/src/doc/man/generated_txt/cargo-fetch.txt new file mode 100644 index 0000000..820d5d5 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fetch.txt @@ -0,0 +1,151 @@ +CARGO-FETCH(1) + +NAME + cargo-fetch — Fetch dependencies of a package from the network + +SYNOPSIS + cargo fetch [options] + +DESCRIPTION + If a Cargo.lock file is available, this command will ensure that all of + the git dependencies and/or registry dependencies are downloaded and + locally available. Subsequent Cargo commands will be able to run offline + after a cargo fetch unless the lock file changes. + + If the lock file is not available, then this command will generate the + lock file before fetching the dependencies. + + If --target is not specified, then all target dependencies are fetched. + + See also the cargo-prefetch <https://crates.io/crates/cargo-prefetch> + plugin which adds a command to download popular crates. This may be + useful if you plan to use Cargo without a network with the --offline + flag. + +OPTIONS + Fetch options + --target triple + Fetch for the given architecture. The default is all architectures. + The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Fetch all dependencies: + + cargo fetch + +SEE ALSO + cargo(1), cargo-update(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt new file mode 100644 index 0000000..3c3627e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -0,0 +1,432 @@ +CARGO-FIX(1) + +NAME + cargo-fix — Automatically fix lint warnings reported by rustc + +SYNOPSIS + cargo fix [options] + +DESCRIPTION + This Cargo subcommand will automatically take rustc’s suggestions from + diagnostics like warnings and apply them to your source code. This is + intended to help automate tasks that rustc itself already knows how to + tell you to fix! + + Executing cargo fix will under the hood execute cargo-check(1). Any + warnings applicable to your crate will be automatically fixed (if + possible) and all remaining warnings will be displayed when the check + process is finished. For example if you’d like to apply all fixes to + the current package, you can run: + + cargo fix + + which behaves the same as cargo check --all-targets. + + cargo fix is only capable of fixing code that is normally compiled with + cargo check. If code is conditionally enabled with optional features, + you will need to enable those features for that code to be analyzed: + + cargo fix --features foo + + Similarly, other cfg expressions like platform-specific code will need + to pass --target to fix code for the given target. + + cargo fix --target x86_64-pc-windows-gnu + + If you encounter any problems with cargo fix or otherwise have any + questions or feature requests please don’t hesitate to file an issue + at <https://github.com/rust-lang/cargo>. + + Edition migration + The cargo fix subcommand can also be used to migrate a package from one + edition + <https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html> + to the next. The general procedure is: + + 1. Run cargo fix --edition. Consider also using the --all-features flag + if your project has multiple features. You may also want to run cargo + fix --edition multiple times with different --target flags if your + project has platform-specific code gated by cfg attributes. + + 2. Modify Cargo.toml to set the edition field + <https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field> + to the new edition. + + 3. Run your project tests to verify that everything still works. If new + warnings are issued, you may want to consider running cargo fix again + (without the --edition flag) to apply any suggestions given by the + compiler. + + And hopefully that’s it! Just keep in mind of the caveats mentioned + above that cargo fix cannot update code for inactive features or cfg + expressions. Also, in some rare cases the compiler is unable to + automatically migrate all code to the new edition, and this may require + manual changes after building with the new edition. + +OPTIONS + Fix options + --broken-code + Fix code even if it already has compiler errors. This is useful if + cargo fix fails to apply the changes. It will apply the changes and + leave the broken code in the working directory for you to inspect + and manually fix. + + --edition + Apply changes that will update the code to the next edition. This + will not update the edition in the Cargo.toml manifest, which must + be updated manually after cargo fix --edition has finished. + + --edition-idioms + Apply suggestions that will update code to the preferred style for + the current edition. + + --allow-no-vcs + Fix code even if a VCS was not detected. + + --allow-dirty + Fix code even if the working directory has changes. + + --allow-staged + Fix code even if the working directory has staged changes. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Fix only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Fix all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo fix will fix all + targets (--all-targets implied). Binaries are skipped if they have + required-features that are missing. + + Passing target selection flags will fix only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Fix the package’s library. + + --bin name… + Fix the specified binary. This flag may be specified multiple times + and supports common Unix glob patterns. + + --bins + Fix all binary targets. + + --example name… + Fix the specified example. This flag may be specified multiple times + and supports common Unix glob patterns. + + --examples + Fix all example targets. + + --test name… + Fix the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Fix all targets in test mode that have the test = true manifest flag + set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Fix the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Fix all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Fix all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Fix for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Fix optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Fix with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more detail. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Fix the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Apply compiler suggestions to the local package: + + cargo fix + + 2. Update a package to prepare it for the next edition: + + cargo fix --edition + + 3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +SEE ALSO + cargo(1), cargo-check(1) + diff --git a/src/doc/man/generated_txt/cargo-generate-lockfile.txt b/src/doc/man/generated_txt/cargo-generate-lockfile.txt new file mode 100644 index 0000000..94958d6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-generate-lockfile.txt @@ -0,0 +1,126 @@ +CARGO-GENERATE-LOCKFILE(1) + +NAME + cargo-generate-lockfile — Generate the lockfile for a package + +SYNOPSIS + cargo generate-lockfile [options] + +DESCRIPTION + This command will create the Cargo.lock lockfile for the current package + or workspace. If the lockfile already exists, it will be rebuilt with + the latest available version of every package. + + See also cargo-update(1) which is also capable of creating a Cargo.lock + lockfile and has more options for controlling update behavior. + +OPTIONS + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +SEE ALSO + cargo(1), cargo-update(1) + diff --git a/src/doc/man/generated_txt/cargo-help.txt b/src/doc/man/generated_txt/cargo-help.txt new file mode 100644 index 0000000..0107ebe --- /dev/null +++ b/src/doc/man/generated_txt/cargo-help.txt @@ -0,0 +1,23 @@ +CARGO-HELP(1) + +NAME + cargo-help — Get help for a Cargo command + +SYNOPSIS + cargo help [subcommand] + +DESCRIPTION + Prints a help message for the given command. + +EXAMPLES + 1. Get help for a command: + + cargo help build + + 2. Help is also available with the --help flag: + + cargo build --help + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-init.txt b/src/doc/man/generated_txt/cargo-init.txt new file mode 100644 index 0000000..48887d6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-init.txt @@ -0,0 +1,134 @@ +CARGO-INIT(1) + +NAME + cargo-init — Create a new Cargo package in an existing directory + +SYNOPSIS + cargo init [options] [path] + +DESCRIPTION + This command will create a new Cargo manifest in the current directory. + Give a path as an argument to create in the given directory. + + If there are typically-named Rust source files already in the directory, + those will be used. If not, then a sample src/main.rs file will be + created, or src/lib.rs if --lib is passed. + + If the directory is not already in a VCS repository, then a new + repository is created (see --vcs below). + + See cargo-new(1) for a similar command which will create a new package + in a new directory. + +OPTIONS + Init Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2021. Possible values: + 2015, 2018, 2021 + + --name name + Set the package name. Defaults to the directory name. + + --vcs vcs + Initialize a new VCS repository for the given version control system + (git, hg, pijul, or fossil) or do not initialize any version control + at all (none). If not specified, defaults to git or the + configuration value cargo-new.vcs, or none if already inside a VCS + repository. + + --registry registry + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the current directory: + + cargo init + +SEE ALSO + cargo(1), cargo-new(1) + diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt new file mode 100644 index 0000000..a66b231 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -0,0 +1,392 @@ +CARGO-INSTALL(1) + +NAME + cargo-install — Build and install a Rust binary + +SYNOPSIS + cargo install [options] crate[@version]… + cargo install [options] --path path + cargo install [options] --git url [crate…] + cargo install [options] --list + +DESCRIPTION + This command manages Cargo’s local set of installed binary crates. + Only packages which have executable [[bin]] or [[example]] targets can + be installed, and all executables are installed into the installation + root’s bin folder. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + <https://doc.rust-lang.org/cargo/reference/config.html> + + o CARGO_HOME environment variable + + o $HOME/.cargo + + There are multiple sources from which a crate can be installed. The + default location is crates.io but the --git, --path, and --registry + flags can change this source. If the source contains more than one + package (such as crates.io or a git repository with multiple crates) the + crate argument is required to indicate which crate should be installed. + + Crates from crates.io can optionally specify the version they wish to + install via the --version flags, and similarly packages from git + repositories can optionally specify the branch, tag, or revision that + should be installed. If a crate has multiple binaries, the --bin + argument can selectively install only one of them, and if you’d rather + install examples the --example argument can be used as well. + + If the package is already installed, Cargo will reinstall it if the + installed version does not appear to be up-to-date. If any of the + following values change, then Cargo will reinstall the package: + + o The package version and source. + + o The set of binary names installed. + + o The chosen features. + + o The profile (--profile). + + o The target (--target). + + Installing with --path will always build and install, unless there are + conflicting binaries from another package. The --force flag may be used + to force Cargo to always reinstall the package. + + If the source is crates.io or --git then by default the crate will be + built in a temporary target directory. To avoid this, the target + directory can be specified by setting the CARGO_TARGET_DIR environment + variable to a relative path. In particular, this can be useful for + caching build artifacts on continuous integration systems. + + Dealing with the Lockfile + By default, the Cargo.lock file that is included with the package will + be ignored. This means that Cargo will recompute which versions of + dependencies to use, possibly using newer versions that have been + released since the package was published. The --locked flag can be used + to force Cargo to use the packaged Cargo.lock file if it is available. + This may be useful for ensuring reproducible builds, to use the exact + same set of dependencies that were available when the package was + published. It may also be useful if a newer version of a dependency is + published that no longer builds on your system, or has other problems. + The downside to using --locked is that you will not receive any fixes or + updates to any dependency. Note that Cargo did not start publishing + Cargo.lock files until version 1.37, which means packages published with + prior versions will not have a Cargo.lock file available. + + Configuration Discovery + This command operates on system or user level, not project level. This + means that the local configuration discovery + <https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure> + is ignored. Instead, the configuration discovery begins at + $CARGO_HOME/config.toml. If the package is installed with --path $PATH, + the local configuration will be used, beginning discovery at + $PATH/.cargo/config.toml. + +OPTIONS + Install Options + --vers version, --version version + Specify a version to install. This may be a version requirement + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.md>, + like ~1.2, to have Cargo select the newest version from the given + requirement. If the version does not have a requirement operator + (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH, and + will install exactly that version; it is not treated as a caret + requirement like Cargo dependencies are. + + --git url + Git URL to install the specified crate from. + + --branch branch + Branch to use when installing from git. + + --tag tag + Tag to use when installing from git. + + --rev sha + Specific commit to use when installing from git. + + --path path + Filesystem path to local crate to install. + + --list + List all installed packages and their versions. + + -f, --force + Force overwriting existing crates or binaries. This can be used if a + package has installed a binary with the same name as another + package. This is also useful if something has changed on the system + that you want to rebuild with, such as a newer version of rustc. + + --no-track + By default, Cargo keeps track of the installed packages with a + metadata file stored in the installation root directory. This flag + tells Cargo not to use or create that file. With this flag, Cargo + will refuse to overwrite any existing files unless the --force flag + is used. This also disables Cargo’s ability to protect against + multiple concurrent invocations of Cargo installing at the same + time. + + --bin name… + Install only the specified binary. + + --bins + Install all binaries. + + --example name… + Install only the specified example. + + --examples + Install all examples. + + --root dir + Directory to install packages into. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + --index index + The URL of the registry index to use. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Install for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + a new temporary folder located in the temporary directory of the + platform. + + When using --path, by default it will use target directory in the + workspace of the local crate unless --target-dir is specified. + + --debug + Build with the dev profile instead the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Install with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Install or upgrade a package from crates.io: + + cargo install ripgrep + + 2. Install or reinstall the package in the current directory: + + cargo install --path . + + 3. View the list of installed packages: + + cargo install --list + +SEE ALSO + cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-locate-project.txt b/src/doc/man/generated_txt/cargo-locate-project.txt new file mode 100644 index 0000000..fcd76ff --- /dev/null +++ b/src/doc/man/generated_txt/cargo-locate-project.txt @@ -0,0 +1,117 @@ +CARGO-LOCATE-PROJECT(1) + +NAME + cargo-locate-project — Print a JSON representation of a Cargo.toml + file’s location + +SYNOPSIS + cargo locate-project [options] + +DESCRIPTION + This command will print a JSON object to stdout with the full path to + the manifest. The manifest is found by searching upward for a file named + Cargo.toml starting from the current working directory. + + If the project happens to be a part of a workspace, the manifest of the + project, rather than the workspace root, is output. This can be + overridden by the --workspace flag. The root workspace is found by + traversing further upward or by using the field package.workspace after + locating the manifest of a workspace member. + +OPTIONS + --workspace + Locate the Cargo.toml at the root of the workspace, as opposed to + the current workspace member. + + Display Options + --message-format fmt + The representation in which to print the project location. Valid + values: + + o json (default): JSON object with the path under the key + “root”. + + o plain: Just the path. + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the path to the manifest based on the current directory: + + cargo locate-project + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-login.txt b/src/doc/man/generated_txt/cargo-login.txt new file mode 100644 index 0000000..bd85053 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-login.txt @@ -0,0 +1,109 @@ +CARGO-LOGIN(1) + +NAME + cargo-login — Save an API token from the registry locally + +SYNOPSIS + cargo login [options] [token] + +DESCRIPTION + This command will save the API token to disk so that commands that + require authentication, such as cargo-publish(1), will be automatically + authenticated. The token is saved in $CARGO_HOME/credentials.toml. + CARGO_HOME defaults to .cargo in your home directory. + + If the token argument is not specified, it will be read from stdin. + + The API token for crates.io may be retrieved from + <https://crates.io/me>. + + Take care to keep the token secret, it should not be shared with anyone + else. + +OPTIONS + Login Options + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Save the API token to disk: + + cargo login + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt new file mode 100644 index 0000000..9bb09da --- /dev/null +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -0,0 +1,439 @@ +CARGO-METADATA(1) + +NAME + cargo-metadata — Machine-readable metadata about the current package + +SYNOPSIS + cargo metadata [options] + +DESCRIPTION + Output JSON to stdout containing information about the workspace members + and resolved dependencies of the current package. + + It is recommended to include the --format-version flag to future-proof + your code to ensure the output is in the format you are expecting. + + See the cargo_metadata crate <https://crates.io/crates/cargo_metadata> + for a Rust API for reading the metadata. + +OUTPUT FORMAT + The output has the following format: + + { + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* The file system path for a local path dependency. + not present if not a path dependency. + */ + "path": "/path/to/dep", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether the target should be documented by `cargo doc`. */ + "doc": true, + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe <user@example.com>" + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The homepage value from the manifest or null if not specified. */ + "homepage": "https://rust-lang.org", + /* The documentation value from the manifest or null if not specified. */ + "documentation": "https://doc.rust-lang.org/stable/std", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } + } + +OPTIONS + Output Options + --no-deps + Output information only about the workspace members and don’t + fetch dependencies. + + --format-version version + Specify the version of the output format to use. Currently 1 is the + only possible value. + + --filter-platform triple + This filters the resolve output to only include dependencies for the + given target triple + <https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. + Without this flag, the resolve includes all targets. + + Note that the dependencies listed in the “packages” array still + includes all dependencies. Each package definition is intended to be + an unaltered reproduction of the information within Cargo.toml. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Output JSON about the current package: + + cargo metadata --format-version=1 + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-new.txt b/src/doc/man/generated_txt/cargo-new.txt new file mode 100644 index 0000000..71cdfe6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-new.txt @@ -0,0 +1,129 @@ +CARGO-NEW(1) + +NAME + cargo-new — Create a new Cargo package + +SYNOPSIS + cargo new [options] path + +DESCRIPTION + This command will create a new Cargo package in the given directory. + This includes a simple template with a Cargo.toml manifest, sample + source file, and a VCS ignore file. If the directory is not already in a + VCS repository, then a new repository is created (see --vcs below). + + See cargo-init(1) for a similar command which will create a new manifest + in an existing directory. + +OPTIONS + New Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2021. Possible values: + 2015, 2018, 2021 + + --name name + Set the package name. Defaults to the directory name. + + --vcs vcs + Initialize a new VCS repository for the given version control system + (git, hg, pijul, or fossil) or do not initialize any version control + at all (none). If not specified, defaults to git or the + configuration value cargo-new.vcs, or none if already inside a VCS + repository. + + --registry registry + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the given directory: + + cargo new foo + +SEE ALSO + cargo(1), cargo-init(1) + diff --git a/src/doc/man/generated_txt/cargo-owner.txt b/src/doc/man/generated_txt/cargo-owner.txt new file mode 100644 index 0000000..65f95f7 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-owner.txt @@ -0,0 +1,144 @@ +CARGO-OWNER(1) + +NAME + cargo-owner — Manage the owners of a crate on the registry + +SYNOPSIS + cargo owner [options] --add login [crate] + cargo owner [options] --remove login [crate] + cargo owner [options] --list [crate] + +DESCRIPTION + This command will modify the owners for a crate on the registry. Owners + of a crate can upload new versions and yank old versions. Non-team + owners can also modify the set of owners, so take care! + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner> + for more information about owners and publishing. + +OPTIONS + Owner Options + -a, --add login… + Invite the given user or team as an owner. + + -r, --remove login… + Remove the given user or team as an owner. + + -l, --list + List owners of a crate. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. List owners of a package: + + cargo owner --list foo + + 2. Invite an owner to a package: + + cargo owner --add username foo + + 3. Remove an owner from a package: + + cargo owner --remove username foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt new file mode 100644 index 0000000..c0b4312 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -0,0 +1,278 @@ +CARGO-PACKAGE(1) + +NAME + cargo-package — Assemble the local package into a distributable + tarball + +SYNOPSIS + cargo package [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory. The resulting + file will be stored in the target/package directory. This performs the + following steps: + + 1. Load and check the current workspace, performing some basic checks. + o Path dependencies are not allowed unless they have a version key. + Cargo will ignore the path key for dependencies in published + packages. dev-dependencies do not have this restriction. + + 2. Create the compressed .crate file. + o The original Cargo.toml file is rewritten and normalized. + + o [patch], [replace], and [workspace] sections are removed from the + manifest. + + o Cargo.lock is automatically included if the package contains an + executable binary or example target. cargo-install(1) will use the + packaged lock file if the --locked flag is used. + + o A .cargo_vcs_info.json file is included that contains information + about the current VCS checkout hash if available (not included + with --allow-dirty). + + 3. Extract the .crate file and build it to verify it can build. + o This will rebuild your package from scratch to ensure that it can + be built from a pristine state. The --no-verify flag can be used + to skip this step. + + 4. Check that build scripts did not modify any source files. + + The list of files included can be controlled with the include and + exclude fields in the manifest. + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html> for more + details about packaging and publishing. + + .cargo_vcs_info.json format + Will generate a .cargo_vcs_info.json in the following format + + { + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" + } + + path_in_vcs will be set to a repo-relative path for packages in + subdirectories of the version control repository. + +OPTIONS + Package Options + -l, --list + Print files included in a package without making one. + + --no-verify + Don’t verify the contents by building them. + + --no-metadata + Ignore warnings about a lack of human-usable metadata (such as the + description or the license). + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Package only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Package all members in the workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Compilation Options + --target triple + Package for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a compressed .crate file of the current package: + + cargo package + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt new file mode 100644 index 0000000..336bc76 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-pkgid.txt @@ -0,0 +1,168 @@ +CARGO-PKGID(1) + +NAME + cargo-pkgid — Print a fully qualified package specification + +SYNOPSIS + cargo pkgid [options] [spec] + +DESCRIPTION + Given a spec argument, print out the fully qualified package ID + specifier for a package or dependency in the current workspace. This + command will generate an error if spec is ambiguous as to which package + it refers to in the dependency graph. If no spec is given, then the + specifier for the local package is printed. + + This command requires that a lockfile is available and dependencies have + been fetched. + + A package specifier consists of a name, version, and source URL. You are + allowed to use partial specifiers to succinctly match a specific package + as long as it matches only one package. The format of a spec can be one + of the following: + + +-----------------+--------------------------------------------------+ + | SPEC Structure | Example SPEC | + +-----------------+--------------------------------------------------+ + | name | bitflags | + +-----------------+--------------------------------------------------+ + | name@version | bitflags@1.0.4 | + +-----------------+--------------------------------------------------+ + | url | https://github.com/rust-lang/cargo | + +-----------------+--------------------------------------------------+ + | url#version | https://github.com/rust-lang/cargo#0.33.0 | + +-----------------+--------------------------------------------------+ + | url#name | | + | | https://github.com/rust-lang/crates.io-index#bitflags | + +-----------------+--------------------------------------------------+ + | | | + | url#name:version | https://github.com/rust-lang/cargo#crates-io@0.21.0 | + +-----------------+--------------------------------------------------+ + +OPTIONS + Package Selection + -p spec, --package spec + Get the package ID for the given package instead of the current + package. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Retrieve package specification for foo package: + + cargo pkgid foo + + 2. Retrieve package specification for version 1.0.0 of foo: + + cargo pkgid foo@1.0.0 + + 3. Retrieve package specification for foo from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + + 4. Retrieve package specification for foo from a local package: + + cargo pkgid file:///path/to/local/package#foo + +SEE ALSO + cargo(1), cargo-generate-lockfile(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt new file mode 100644 index 0000000..037083b --- /dev/null +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -0,0 +1,244 @@ +CARGO-PUBLISH(1) + +NAME + cargo-publish — Upload a package to the registry + +SYNOPSIS + cargo publish [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory and upload it to + a registry. The default registry is <https://crates.io>. This performs + the following steps: + + 1. Performs a few checks, including: + o Checks the package.publish key in the manifest for restrictions on + which registries you are allowed to publish to. + + 2. Create a .crate file by following the steps in cargo-package(1). + + 3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html> for more + details about packaging and publishing. + +OPTIONS + Publish Options + --dry-run + Perform all checks without uploading. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --no-verify + Don’t verify the contents by building them. + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to publish to. Registry names are defined in + Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, and there is a package.publish + <https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field> + field in Cargo.toml with a single registry, then it will publish to + that registry. Otherwise it will use the default registry, which is + defined by the registry.default + <https://doc.rust-lang.org/cargo/reference/config.html#registrydefault> + config key which defaults to crates-io. + + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to publish. See cargo-pkgid(1) for the SPEC format. + + Compilation Options + --target triple + Publish for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Publish the current package: + + cargo publish + +SEE ALSO + cargo(1), cargo-package(1), cargo-login(1) + diff --git a/src/doc/man/generated_txt/cargo-remove.txt b/src/doc/man/generated_txt/cargo-remove.txt new file mode 100644 index 0000000..5fb867a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-remove.txt @@ -0,0 +1,150 @@ +CARGO-REMOVE(1) + +NAME + cargo-remove — Remove dependencies from a Cargo.toml manifest file + +SYNOPSIS + cargo remove [options] dependency… + +DESCRIPTION + Remove one or more dependencies from a Cargo.toml manifest. + +OPTIONS + Section options + --dev + Remove as a development dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>. + + --build + Remove as a build dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>. + + --target target + Remove as a dependency to the given target platform + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>. + + Miscellaneous Options + --dry-run + Don’t actually write to the manifest. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Package Selection + -p spec…, --package spec… + Package to remove from. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove regex as a dependency + + cargo remove regex + + 2. Remove trybuild as a dev-dependency + + cargo remove --dev trybuild + + 3. Remove nom from the x86_64-pc-windows-gnu dependencies table + + cargo remove --target x86_64-pc-windows-gnu nom + +SEE ALSO + cargo(1), cargo-add(1) + diff --git a/src/doc/man/generated_txt/cargo-report.txt b/src/doc/man/generated_txt/cargo-report.txt new file mode 100644 index 0000000..f75a60c --- /dev/null +++ b/src/doc/man/generated_txt/cargo-report.txt @@ -0,0 +1,34 @@ +CARGO-REPORT(1) + +NAME + cargo-report — Generate and display various kinds of reports + +SYNOPSIS + cargo report type [options] + + DESCRIPTION + Displays a report of the given type — currently, only future-incompat + is supported + +OPTIONS + --id id + Show the report with the specified Cargo-generated id + + -p spec…, --package spec… + Only display a report for the specified package + +EXAMPLES + 1. Display the latest future-incompat report: + + cargo report future-incompat + + 2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +SEE ALSO + Future incompat report + <https://doc.rust-lang.org/cargo/reference/future-incompat-report.html> + + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt new file mode 100644 index 0000000..fc9112a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -0,0 +1,271 @@ +CARGO-RUN(1) + +NAME + cargo-run — Run the current package + +SYNOPSIS + cargo run [options] [-- args] + +DESCRIPTION + Run a binary or example of the local package. + + All the arguments following the two dashes (--) are passed to the binary + to run. If you’re passing arguments to both Cargo and the binary, the + ones after -- go to the binary, the ones before go to Cargo. + +OPTIONS + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to run. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo run will run the + binary target. If there are multiple binary targets, you must pass a + target flag to choose one. Or, the default-run field may be specified in + the [package] section of Cargo.toml to choose the name of the binary to + run by default. + + --bin name + Run the specified binary. + + --example name + Run the specified example. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Run for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Run optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Run with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Run the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and run its main target (assuming only one + binary): + + cargo run + + 2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt new file mode 100644 index 0000000..6082fe8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -0,0 +1,383 @@ +CARGO-RUSTC(1) + +NAME + cargo-rustc — Compile the current package, and pass extra options to + the compiler + +SYNOPSIS + cargo rustc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be compiled along with all of its dependencies. The + specified args will all be passed to the final compiler invocation, not + any of the dependencies. Note that the compiler will still + unconditionally receive arguments such as -L, --extern, and + --crate-type, and the specified args will simply be added to the + compiler invocation. + + See <https://doc.rust-lang.org/rustc/index.html> for documentation on + rustc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all compiler processes spawned by Cargo, use the + RUSTFLAGS environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + or the build.rustflags config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + +OPTIONS + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to build. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo rustc will build all + binary and library targets of the selected package. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will build only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Build the package’s library. + + --bin name… + Build the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Build all binary targets. + + --example name… + Build the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Build all example targets. + + --test name… + Build the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Build all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Build the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. + + The rustc subcommand will treat the following named profiles with + special behaviors: + + o check — Builds in the same way as the cargo-check(1) command + with the dev profile. + + o test — Builds in the same way as the cargo-test(1) command, + enabling building in test mode which will enable tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more + detail. + + o bench — Builds in the same was as the cargo-bench(1) command, + similar to the test profile. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + --crate-type crate-type + Build for the given crate type. This flag accepts a comma-separated + list of 1 or more crate types, of which the allowed values are the + same as crate-type field in the manifest for configurating a Cargo + target. See crate-type field + <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-crate-type-field> + for possible values. + + If the manifest contains a list, and --crate-type is provided, the + command-line argument value will override what is in the manifest. + + This flag only works when building a lib or example library target. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + + 2. Try an experimental flag on the nightly compiler, such as this which + prints the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + + 3. Override crate-type field in Cargo.toml with command-line option: + + cargo rustc --lib --crate-type lib,cdylib + +SEE ALSO + cargo(1), cargo-build(1), rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt new file mode 100644 index 0000000..97b49c4 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -0,0 +1,338 @@ +CARGO-RUSTDOC(1) + +NAME + cargo-rustdoc — Build a package’s documentation, using specified + custom flags + +SYNOPSIS + cargo rustdoc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be documented with the specified args being passed to + the final rustdoc invocation. Dependencies will not be documented as + part of this command. Note that rustdoc will still unconditionally + receive arguments such as -L, --extern, and --crate-type, and the + specified args will simply be added to the rustdoc invocation. + + See <https://doc.rust-lang.org/rustdoc/index.html> for documentation on + rustdoc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all rustdoc processes spawned by Cargo, use the + RUSTDOCFLAGS environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + or the build.rustdocflags config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable or use the doc.browser + <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser> + configuration option. + + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to document. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo rustdoc will document + all binary and library targets of the selected package. The binary will + be skipped if its name is the same as the lib target. Binaries are + skipped if they have required-features that are missing. + + Passing target selection flags will document only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Document the package’s library. + + --bin name… + Document the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Document all binary targets. + + --example name… + Document the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Document all example targets. + + --test name… + Document the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Document all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Document the specified benchmark. This flag may be specified + multiple times and supports common Unix glob patterns. + + --benches + Document all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Document all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +SEE ALSO + cargo(1), cargo-doc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-search.txt b/src/doc/man/generated_txt/cargo-search.txt new file mode 100644 index 0000000..779ed57 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-search.txt @@ -0,0 +1,106 @@ +CARGO-SEARCH(1) + +NAME + cargo-search — Search packages in crates.io + +SYNOPSIS + cargo search [options] [query…] + +DESCRIPTION + This performs a textual search for crates on <https://crates.io>. The + matching crates will be displayed along with their description in TOML + format suitable for copying into a Cargo.toml manifest. + +OPTIONS + Search Options + --limit limit + Limit the number of results (default: 10, max: 100). + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Search for a package from crates.io: + + cargo search serde + +SEE ALSO + cargo(1), cargo-install(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt new file mode 100644 index 0000000..082447d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -0,0 +1,457 @@ +CARGO-TEST(1) + +NAME + cargo-test — Execute unit and integration tests of a package + +SYNOPSIS + cargo test [options] [testname] [-- test-options] + +DESCRIPTION + Compile and execute unit, integration, and documentation tests. + + The test filtering argument TESTNAME and all the arguments following the + two dashes (--) are passed to the test binaries and thus to libtest + (rustc’s built in unit-test and micro-benchmarking framework). If + you’re passing arguments to both Cargo and the binary, the ones after + -- go to the binary, the ones before go to Cargo. For details about + libtest’s arguments see the output of cargo test -- --help and check + out the rustc book’s chapter on how tests work at + <https://doc.rust-lang.org/rustc/tests/index.html>. + + As an example, this will filter for tests with foo in their name and run + them on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + + Tests are built with the --test option to rustc which creates a special + executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[test] attribute in + multiple threads. #[bench] annotated functions will also be run with one + iteration to verify that they are functional. + + If the package contains multiple test targets, each target compiles to a + special executable as aforementioned, and then is run serially. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running tests. + + Documentation tests + Documentation tests are also run by default, which is handled by + rustdoc. It extracts code samples from documentation comments of the + library target, and then executes them. + + Different from normal test targets, each code block compiles to a + doctest executable on the fly with rustc. These executables run in + parallel in separate processes. The compilation of a code block is in + fact a part of test function controlled by libtest, so some options such + as --jobs might not take effect. Note that this execution model of + doctests is not guaranteed and may change in the future; beware of + depending on it. + + See the rustdoc book <https://doc.rust-lang.org/rustdoc/> for more + information on writing doc tests. + +OPTIONS + Test Options + --no-run + Compile, but don’t run tests. + + --no-fail-fast + Run all tests regardless of failure. Without this flag, Cargo will + exit after the first executable fails. The Rust test harness will + run all tests within the executable to completion, this flag only + applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Test only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Test all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo test will build the + following targets of the selected packages: + + o lib — used to link with binaries, examples, integration tests, and + doc tests + + o bins (only if integration tests are built and required features are + available) + + o examples — to ensure they compile + + o lib as a unit test + + o bins as unit tests + + o integration tests + + o doc tests for the lib target + + The default behavior can be changed by setting the test flag for the + target in the manifest settings. Setting examples to test = true will + build and run the example as a test. Setting targets to test = false + will stop them from being tested by default. Target selection options + that take a target by name ignore the test flag and will always test the + given target. + + Doc tests for libraries may be disabled by setting doctest = false for + the library in the manifest. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to test. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will test only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Test the package’s library. + + --bin name… + Test the specified binary. This flag may be specified multiple times + and supports common Unix glob patterns. + + --bins + Test all binary targets. + + --example name… + Test the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Test all example targets. + + --test name… + Test the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Test all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Test the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Test all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Test all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + --doc + Test only the library’s documentation. This cannot be mixed with + other target options. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Test for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Test optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Test with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Test the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + By default the Rust test harness hides output from test execution to + keep results readable. Test output can be recovered (e.g., for + debugging) by passing --nocapture to the test binaries: + + cargo test -- --nocapture + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + The --jobs argument affects the building of the test executable but does + not affect how many threads are used when running the tests. The Rust + test harness includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Execute all the unit and integration tests of the current package: + + cargo test + + 2. Run only tests whose names match against a filter string: + + cargo test name_filter + + 3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +SEE ALSO + cargo(1), cargo-bench(1), types of tests + <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests>, + how to write tests <https://doc.rust-lang.org/rustc/tests/index.html> + diff --git a/src/doc/man/generated_txt/cargo-tree.txt b/src/doc/man/generated_txt/cargo-tree.txt new file mode 100644 index 0000000..bc2993d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-tree.txt @@ -0,0 +1,392 @@ +CARGO-TREE(1) + +NAME + cargo-tree — Display a tree visualization of a dependency graph + +SYNOPSIS + cargo tree [options] + +DESCRIPTION + This command will display a tree of dependencies to the terminal. An + example of a simple project that depends on the “rand” package: + + myproject v0.1.0 (/myproject) + └── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) + [build-dependencies] + └── cc v1.0.50 + + Packages marked with (*) have been “de-duplicated”. The dependencies + for the package have already been shown elsewhere in the graph, and so + are not repeated. Use the --no-dedupe option to repeat the duplicates. + + The -e flag can be used to select the dependency kinds to display. The + “features” kind changes the output to display the features enabled + by each dependency. For example, cargo tree -e features: + + myproject v0.1.0 (/myproject) + └── log feature "serde" + └── log v0.4.8 + ├── serde v1.0.106 + └── cfg-if feature "default" + └── cfg-if v0.1.10 + + In this tree, myproject depends on log with the serde feature. log in + turn depends on cfg-if with “default” features. When using -e + features it can be helpful to use -i flag to show how the features flow + into a package. See the examples below for more detail. + + Feature Unification + This command shows a graph much closer to a feature-unified graph Cargo + will build, rather than what you list in Cargo.toml. For instance, if + you specify the same dependency in both [dependencies] and + [dev-dependencies] but with different features on. This command may + merge all features and show a (*) on one of the dependency to indicate + the duplicate. + + As a result, for a mostly equivalent overview of what cargo build does, + cargo tree -e normal,build is pretty close; for a mostly equivalent + overview of what cargo test does, cargo tree is pretty close. However, + it doesn’t guarantee the exact equivalence to what Cargo is going to + build, since a compilation is complex and depends on lots of different + factors. + + To learn more about feature unification, check out this dedicated + section + <https://doc.rust-lang.org/cargo/reference/features.html#feature-unification>. + +OPTIONS + Tree Options + -i spec, --invert spec + Show the reverse dependencies for the given package. This flag will + invert the tree and display the packages that depend on the given + package. + + Note that in a workspace, by default it will only display the + package’s reverse dependencies inside the tree of the workspace + member in the current directory. The --workspace flag can be used to + extend it so that it will show the package’s reverse dependencies + across the entire workspace. The -p flag can be used to display the + package’s reverse dependencies only with the subtree of the + package given to -p. + + --prune spec + Prune the given package from the display of the dependency tree. + + --depth depth + Maximum display depth of the dependency tree. A depth of 1 displays + the direct dependencies, for example. + + --no-dedupe + Do not de-duplicate repeated dependencies. Usually, when a package + has already displayed its dependencies, further occurrences will not + re-display its dependencies, and will include a (*) to indicate it + has already been shown. This flag will cause those duplicates to be + repeated. + + -d, --duplicates + Show only dependencies which come in multiple versions (implies + --invert). When used with the -p flag, only shows duplicates within + the subtree of the given package. + + It can be beneficial for build times and executable sizes to avoid + building that same package multiple times. This flag can help + identify the offending packages. You can then investigate if the + package that depends on the duplicate with the older version can be + updated to the newer version so that only one instance is built. + + -e kinds, --edges kinds + The dependency kinds to display. Takes a comma separated list of + values: + + o all — Show all edge kinds. + + o normal — Show normal dependencies. + + o build — Show build dependencies. + + o dev — Show development dependencies. + + o features — Show features enabled by each dependency. If this is + the only kind given, then it will automatically include the other + dependency kinds. + + o no-normal — Do not include normal dependencies. + + o no-build — Do not include build dependencies. + + o no-dev — Do not include development dependencies. + + o no-proc-macro — Do not include procedural macro dependencies. + + The normal, build, dev, and all dependency kinds cannot be mixed + with no-normal, no-build, or no-dev dependency kinds. + + The default is normal,build,dev. + + --target triple + Filter dependencies matching the given target triple + <https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. The + default is the host platform. Use the value all to include all + targets. + + Tree Formatting Options + --charset charset + Chooses the character set to use for the tree. Valid values are + “utf8” or “ascii”. Default is “utf8”. + + -f format, --format format + Set the format string for each package. The default is “{p}”. + + This is an arbitrary string which will be used to display each + package. The following strings will be replaced with the + corresponding value: + + o {p} — The package name. + + o {l} — The package license. + + o {r} — The package repository URL. + + o {f} — Comma-separated list of package features that are + enabled. + + o {lib} — The name, as used in a use statement, of the + package’s library. + + --prefix prefix + Sets how each line is displayed. The prefix value can be one of: + + o indent (default) — Shows each line indented as a tree. + + o depth — Show as a list, with the numeric depth printed before + each entry. + + o none — Show as a flat list. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Display only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Display all members in the workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the tree for the package in the current directory: + + cargo tree + + 2. Display all the packages that depend on the syn package: + + cargo tree -i syn + + 3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + + 4. Show all packages that are built multiple times. This can happen if + multiple semver-incompatible versions appear in the tree (like 1.0.0 + and 2.0.0). + + cargo tree -d + + 5. Explain why features are enabled for the syn package: + + cargo tree -e features -i syn + + The -e features flag is used to show features. The -i flag is used to + invert the graph so that it displays the packages that depend on syn. + An example of what this would display: + + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + + To read this graph, you can follow the chain for each feature from + the root to see why it is included. For example, the “full” + feature is added by the rustversion crate which is included from + myproject (with the default features), and myproject is the package + selected on the command-line. All of the other syn features are added + by the “default” feature (“quote” is added by “printing” + and “proc-macro”, both of which are default features). + + If you’re having difficulty cross-referencing the de-duplicated (*) + entries, try with the --no-dedupe flag to get the full output. + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-uninstall.txt b/src/doc/man/generated_txt/cargo-uninstall.txt new file mode 100644 index 0000000..a5ceb89 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-uninstall.txt @@ -0,0 +1,118 @@ +CARGO-UNINSTALL(1) + +NAME + cargo-uninstall — Remove a Rust binary + +SYNOPSIS + cargo uninstall [options] [spec…] + +DESCRIPTION + This command removes a package installed with cargo-install(1). The spec + argument is a package ID specification of the package to remove (see + cargo-pkgid(1)). + + By default all binaries are removed for a crate but the --bin and + --example flags can be used to only remove particular binaries. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + <https://doc.rust-lang.org/cargo/reference/config.html> + + o CARGO_HOME environment variable + + o $HOME/.cargo + +OPTIONS + Install Options + -p, --package spec… + Package to uninstall. + + --bin name… + Only uninstall the binary name. + + --root dir + Directory to uninstall packages from. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +SEE ALSO + cargo(1), cargo-install(1) + diff --git a/src/doc/man/generated_txt/cargo-update.txt b/src/doc/man/generated_txt/cargo-update.txt new file mode 100644 index 0000000..7b2d1aa --- /dev/null +++ b/src/doc/man/generated_txt/cargo-update.txt @@ -0,0 +1,164 @@ +CARGO-UPDATE(1) + +NAME + cargo-update — Update dependencies as recorded in the local lock file + +SYNOPSIS + cargo update [options] + +DESCRIPTION + This command will update dependencies in the Cargo.lock file to the + latest version. If the Cargo.lock file does not exist, it will be + created with the latest available versions. + +OPTIONS + Update Options + -p spec…, --package spec… + Update only the specified packages. This flag may be specified + multiple times. See cargo-pkgid(1) for the SPEC format. + + If packages are specified with the -p flag, then a conservative + update of the lockfile will be performed. This means that only the + dependency specified by SPEC will be updated. Its transitive + dependencies will be updated only if SPEC cannot be updated without + updating dependencies. All other dependencies will remain locked at + their currently recorded versions. + + If -p is not specified, all dependencies are updated. + + --aggressive + When used with -p, dependencies of spec are forced to update as + well. Cannot be used with --precise. + + --precise precise + When used with -p, allows you to specify a specific version number + to set the package to. If the package comes from a git repository, + this can be a git revision (such as a SHA hash or tag). + + -w, --workspace + Attempt to update only packages defined in the workspace. Other + packages are updated only if they don’t already exist in the + lockfile. This option is useful for updating Cargo.lock after + you’ve changed version numbers in Cargo.toml. + + --dry-run + Displays what would be updated, but doesn’t actually write the + lockfile. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Update all dependencies in the lockfile: + + cargo update + + 2. Update only specific dependencies: + + cargo update -p foo -p bar + + 3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +SEE ALSO + cargo(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-vendor.txt b/src/doc/man/generated_txt/cargo-vendor.txt new file mode 100644 index 0000000..03ceff3 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-vendor.txt @@ -0,0 +1,160 @@ +CARGO-VENDOR(1) + +NAME + cargo-vendor — Vendor all dependencies locally + +SYNOPSIS + cargo vendor [options] [path] + +DESCRIPTION + This cargo subcommand will vendor all crates.io and git dependencies for + a project into the specified directory at <path>. After this command + completes the vendor directory specified by <path> will contain all + remote sources from dependencies specified. Additional manifests beyond + the default one can be specified with the -s option. + + The cargo vendor command will also print out the configuration necessary + to use the vendored sources, which you will need to add to + .cargo/config.toml. + +OPTIONS + Vendor Options + -s manifest, --sync manifest + Specify an extra Cargo.toml manifest to workspaces which should also + be vendored and synced to the output. May be specified multiple + times. + + --no-delete + Don’t delete the “vendor” directory when vendoring, but rather + keep all existing contents of the vendor directory + + --respect-source-config + Instead of ignoring [source] configuration by default in + .cargo/config.toml read it and use it when downloading crates from + crates.io, for example + + --versioned-dirs + Normally versions are only added to disambiguate multiple versions + of the same package. This option causes all directories in the + “vendor” directory to be versioned, which makes it easier to + track the history of vendored packages over time, and can help with + the performance of re-vendoring when only a subset of the packages + have changed. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Vendor all dependencies into a local “vendor” folder + + cargo vendor + + 2. Vendor all dependencies into a local “third-party/vendor” folder + + cargo vendor third-party/vendor + + 3. Vendor the current workspace as well as another to “vendor” + + cargo vendor -s ../path/to/Cargo.toml + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-verify-project.txt b/src/doc/man/generated_txt/cargo-verify-project.txt new file mode 100644 index 0000000..1540d1d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-verify-project.txt @@ -0,0 +1,129 @@ +CARGO-VERIFY-PROJECT(1) + +NAME + cargo-verify-project — Check correctness of crate manifest + +SYNOPSIS + cargo verify-project [options] + +DESCRIPTION + This command will parse the local manifest and check its validity. It + emits a JSON object with the result. A successful validation will + display: + + {"success":"true"} + + An invalid workspace will display: + + {"invalid":"human-readable error message"} + +OPTIONS + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: The workspace is OK. + + o 1: The workspace is invalid. + +EXAMPLES + 1. Check the current workspace for errors: + + cargo verify-project + +SEE ALSO + cargo(1), cargo-package(1) + diff --git a/src/doc/man/generated_txt/cargo-version.txt b/src/doc/man/generated_txt/cargo-version.txt new file mode 100644 index 0000000..138390a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-version.txt @@ -0,0 +1,32 @@ +CARGO-VERSION(1) + +NAME + cargo-version — Show version information + +SYNOPSIS + cargo version [options] + +DESCRIPTION + Displays the version of Cargo. + +OPTIONS + -v, --verbose + Display additional version information. + +EXAMPLES + 1. Display the version: + + cargo version + + 2. The version is also available via flags: + + cargo --version + cargo -V + + 3. Display extra version information: + + cargo -Vv + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt new file mode 100644 index 0000000..62eb97a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-yank.txt @@ -0,0 +1,133 @@ +CARGO-YANK(1) + +NAME + cargo-yank — Remove a pushed crate from the index + +SYNOPSIS + cargo yank [options] crate@version + cargo yank [options] --version version [crate] + +DESCRIPTION + The yank command removes a previously published crate’s version from + the server’s index. This command does not delete any data, and the + crate will still be available for download via the registry’s download + link. + + Note that existing crates locked to a yanked version will still be able + to download the yanked version to use it. Cargo will, however, not allow + any new crates to be locked to any yanked version. + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + +OPTIONS + Yank Options + --vers version, --version version + The version to yank or un-yank. + + --undo + Undo a yank, putting a version back into the index. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Yank a crate from the index: + + cargo yank foo@1.0.7 + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt new file mode 100644 index 0000000..b175a78 --- /dev/null +++ b/src/doc/man/generated_txt/cargo.txt @@ -0,0 +1,293 @@ +CARGO(1) + +NAME + cargo — The Rust package manager + +SYNOPSIS + cargo [options] command [args] + cargo [options] --version + cargo [options] --list + cargo [options] --help + cargo [options] --explain code + +DESCRIPTION + This program is a package manager and build tool for the Rust language, + available at <https://rust-lang.org>. + +COMMANDS + Build Commands + cargo-bench(1) + Execute benchmarks of a package. + + cargo-build(1) + Compile a package. + + cargo-check(1) + Check a local package and all of its dependencies for errors. + + cargo-clean(1) + Remove artifacts that Cargo has generated in the past. + + cargo-doc(1) + Build a package’s documentation. + + cargo-fetch(1) + Fetch dependencies of a package from the network. + + cargo-fix(1) + Automatically fix lint warnings reported by rustc. + + cargo-run(1) + Run a binary or example of the local package. + + cargo-rustc(1) + Compile a package, and pass extra options to the compiler. + + cargo-rustdoc(1) + Build a package’s documentation, using specified custom flags. + + cargo-test(1) + Execute unit and integration tests of a package. + + Manifest Commands + cargo-generate-lockfile(1) + Generate Cargo.lock for a project. + + cargo-locate-project(1) + Print a JSON representation of a Cargo.toml file’s location. + + cargo-metadata(1) + Output the resolved dependencies of a package in + machine-readable format. + + cargo-pkgid(1) + Print a fully qualified package specification. + + cargo-tree(1) + Display a tree visualization of a dependency graph. + + cargo-update(1) + Update dependencies as recorded in the local lock file. + + cargo-vendor(1) + Vendor all dependencies locally. + + cargo-verify-project(1) + Check correctness of crate manifest. + + Package Commands + cargo-init(1) + Create a new Cargo package in an existing directory. + + cargo-install(1) + Build and install a Rust binary. + + cargo-new(1) + Create a new Cargo package. + + cargo-search(1) + Search packages in crates.io. + + cargo-uninstall(1) + Remove a Rust binary. + + Publishing Commands + cargo-login(1) + Save an API token from the registry locally. + + cargo-owner(1) + Manage the owners of a crate on the registry. + + cargo-package(1) + Assemble the local package into a distributable tarball. + + cargo-publish(1) + Upload a package to the registry. + + cargo-yank(1) + Remove a pushed crate from the index. + + General Commands + cargo-help(1) + Display help information about Cargo. + + cargo-version(1) + Show version information. + +OPTIONS + Special Options + -V, --version + Print version info and exit. If used with --verbose, prints extra + information. + + --list + List all installed Cargo subcommands. If used with --verbose, prints + extra information. + + --explain code + Run rustc --explain CODE which will print out a detailed explanation + of an error message (for example, E0004). + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +FILES + ~/.cargo/ + Default location for Cargo’s “home” directory where it + stores various files. The location can be changed with the CARGO_HOME + environment variable. + + $CARGO_HOME/bin/ + Binaries installed by cargo-install(1) will be located here. If + using rustup <https://rust-lang.github.io/rustup/>, executables + distributed with Rust are also located here. + + $CARGO_HOME/config.toml + The global configuration file. See the reference + <https://doc.rust-lang.org/cargo/reference/config.html> for more + information about configuration files. + + .cargo/config.toml + Cargo automatically searches for a file named .cargo/config.toml + in the current directory, and all parent directories. These + configuration files will be merged with the global configuration file. + + $CARGO_HOME/credentials.toml + Private authentication information for logging in to a registry. + + $CARGO_HOME/registry/ + This directory contains cached downloads of the registry index + and any downloaded dependencies. + + $CARGO_HOME/git/ + This directory contains cached downloads of git dependencies. + + Please note that the internal structure of the $CARGO_HOME directory is + not stable yet and may be subject to change. + +EXAMPLES + 1. Build a local package and all of its dependencies: + + cargo build + + 2. Build a package with optimizations: + + cargo build --release + + 3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + + 4. Create a new package that builds an executable: + + cargo new foobar + + 5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + + 6. Learn about a command’s options and usage: + + cargo help clean + +BUGS + See <https://github.com/rust-lang/cargo/issues> for issues. + +SEE ALSO + rustc(1), rustdoc(1) + diff --git a/src/doc/man/includes/description-install-root.md b/src/doc/man/includes/description-install-root.md new file mode 100644 index 0000000..50cf51b --- /dev/null +++ b/src/doc/man/includes/description-install-root.md @@ -0,0 +1,7 @@ +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` diff --git a/src/doc/man/includes/description-one-target.md b/src/doc/man/includes/description-one-target.md new file mode 100644 index 0000000..7af1813 --- /dev/null +++ b/src/doc/man/includes/description-one-target.md @@ -0,0 +1,4 @@ +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. diff --git a/src/doc/man/includes/options-display.md b/src/doc/man/includes/options-display.md new file mode 100644 index 0000000..917dac4 --- /dev/null +++ b/src/doc/man/includes/options-display.md @@ -0,0 +1,24 @@ +{{#option "`-v`" "`--verbose`"}} +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the `term.verbose` +[config value](../reference/config.html). +{{/option}} + +{{#option "`-q`" "`--quiet`"}} +Do not print cargo log messages. +May also be specified with the `term.quiet` +[config value](../reference/config.html). +{{/option}} + +{{#option "`--color` _when_"}} +Control when colored output is used. Valid values: + +- `auto` (default): Automatically detect if color support is available on the + terminal. +- `always`: Always display colors. +- `never`: Never display colors. + +May also be specified with the `term.color` +[config value](../reference/config.html). +{{/option}} diff --git a/src/doc/man/includes/options-future-incompat.md b/src/doc/man/includes/options-future-incompat.md new file mode 100644 index 0000000..3a8a1e7 --- /dev/null +++ b/src/doc/man/includes/options-future-incompat.md @@ -0,0 +1,6 @@ +{{#option "`--future-incompat-report`"}} +Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command + +See {{man "cargo-report" 1}} +{{/option}} diff --git a/src/doc/man/includes/options-ignore-rust-version.md b/src/doc/man/includes/options-ignore-rust-version.md new file mode 100644 index 0000000..a151534 --- /dev/null +++ b/src/doc/man/includes/options-ignore-rust-version.md @@ -0,0 +1,4 @@ +{{#option "`--ignore-rust-version`"}} +{{actionverb}} the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's `rust-version` field. +{{/option}} diff --git a/src/doc/man/includes/options-index.md b/src/doc/man/includes/options-index.md new file mode 100644 index 0000000..b19b983 --- /dev/null +++ b/src/doc/man/includes/options-index.md @@ -0,0 +1,3 @@ +{{#option "`--index` _index_"}} +The URL of the registry index to use. +{{/option}} diff --git a/src/doc/man/includes/options-jobs.md b/src/doc/man/includes/options-jobs.md new file mode 100644 index 0000000..2742638 --- /dev/null +++ b/src/doc/man/includes/options-jobs.md @@ -0,0 +1,7 @@ +{{#option "`-j` _N_" "`--jobs` _N_"}} +Number of parallel jobs to run. May also be specified with the +`build.jobs` [config value](../reference/config.html). Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0. +{{/option}} diff --git a/src/doc/man/includes/options-keep-going.md b/src/doc/man/includes/options-keep-going.md new file mode 100644 index 0000000..034181c --- /dev/null +++ b/src/doc/man/includes/options-keep-going.md @@ -0,0 +1,5 @@ +{{#option "`--keep-going`"}} +Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +`-Zunstable-options`. +{{/option}} diff --git a/src/doc/man/includes/options-locked.md b/src/doc/man/includes/options-locked.md new file mode 100644 index 0000000..c9ac952 --- /dev/null +++ b/src/doc/man/includes/options-locked.md @@ -0,0 +1,25 @@ +{{#option "`--frozen`" "`--locked`"}} +Either of these flags requires that the `Cargo.lock` file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The `--frozen` flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date. + +These may be used in environments where you want to assert that the +`Cargo.lock` file is up-to-date (such as a CI build) or want to avoid network +access. +{{/option}} + +{{#option "`--offline`"}} +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. + +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the {{man "cargo-fetch" 1}} command to download dependencies before going +offline. + +May also be specified with the `net.offline` [config value](../reference/config.html). +{{/option}} diff --git a/src/doc/man/includes/options-manifest-path.md b/src/doc/man/includes/options-manifest-path.md new file mode 100644 index 0000000..b1d6eab --- /dev/null +++ b/src/doc/man/includes/options-manifest-path.md @@ -0,0 +1,4 @@ +{{#option "`--manifest-path` _path_" }} +Path to the `Cargo.toml` file. By default, Cargo searches for the +`Cargo.toml` file in the current directory or any parent directory. +{{/option}} diff --git a/src/doc/man/includes/options-message-format.md b/src/doc/man/includes/options-message-format.md new file mode 100644 index 0000000..61e970a --- /dev/null +++ b/src/doc/man/includes/options-message-format.md @@ -0,0 +1,21 @@ +{{#option "`--message-format` _fmt_" }} +The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values: + +- `human` (default): Display in a human-readable text format. Conflicts with + `short` and `json`. +- `short`: Emit shorter, human-readable text messages. Conflicts with `human` + and `json`. +- `json`: Emit JSON messages to stdout. See + [the reference](../reference/external-tools.html#json-messages) + for more details. Conflicts with `human` and `short`. +- `json-diagnostic-short`: Ensure the `rendered` field of JSON messages contains + the "short" rendering from rustc. Cannot be used with `human` or `short`. +- `json-diagnostic-rendered-ansi`: Ensure the `rendered` field of JSON messages + contains embedded ANSI color codes for respecting rustc's default color + scheme. Cannot be used with `human` or `short`. +- `json-render-diagnostics`: Instruct Cargo to not include rustc diagnostics + in JSON messages printed, but instead Cargo itself should render the + JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others + coming from rustc are still emitted. Cannot be used with `human` or `short`. +{{/option}} diff --git a/src/doc/man/includes/options-new.md b/src/doc/man/includes/options-new.md new file mode 100644 index 0000000..e9792f0 --- /dev/null +++ b/src/doc/man/includes/options-new.md @@ -0,0 +1,39 @@ +{{#options}} + +{{#option "`--bin`" }} +Create a package with a binary target (`src/main.rs`). +This is the default behavior. +{{/option}} + +{{#option "`--lib`" }} +Create a package with a library target (`src/lib.rs`). +{{/option}} + +{{#option "`--edition` _edition_" }} +Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021 +{{/option}} + +{{#option "`--name` _name_" }} +Set the package name. Defaults to the directory name. +{{/option}} + +{{#option "`--vcs` _vcs_" }} +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to `git` or the configuration value +`cargo-new.vcs`, or `none` if already inside a VCS repository. +{{/option}} + +{{#option "`--registry` _registry_" }} +This sets the `publish` field in `Cargo.toml` to the given registry name +which will restrict publishing only to that registry. + +Registry names are defined in [Cargo config files](../reference/config.html). +If not specified, the default registry defined by the `registry.default` +config key is used. If the default registry is not set and `--registry` is not +used, the `publish` field will not be set which means that publishing will not +be restricted. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-profile-legacy-check.md b/src/doc/man/includes/options-profile-legacy-check.md new file mode 100644 index 0000000..0ec82e6 --- /dev/null +++ b/src/doc/man/includes/options-profile-legacy-check.md @@ -0,0 +1,10 @@ +{{#option "`--profile` _name_" }} +{{actionverb}} with the given profile. + +As a special case, specifying the `test` profile will also enable checking in +test mode which will enable checking tests and enable the `test` cfg option. +See [rustc tests](https://doc.rust-lang.org/rustc/tests/index.html) for more +detail. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} diff --git a/src/doc/man/includes/options-profile.md b/src/doc/man/includes/options-profile.md new file mode 100644 index 0000000..2452e7b --- /dev/null +++ b/src/doc/man/includes/options-profile.md @@ -0,0 +1,4 @@ +{{#option "`--profile` _name_" }} +{{actionverb}} with the given profile. +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} diff --git a/src/doc/man/includes/options-registry.md b/src/doc/man/includes/options-registry.md new file mode 100644 index 0000000..23e1706 --- /dev/null +++ b/src/doc/man/includes/options-registry.md @@ -0,0 +1,6 @@ +{{#option "`--registry` _registry_"}} +Name of the registry to use. Registry names are defined in [Cargo config +files](../reference/config.html). If not specified, the default registry is used, +which is defined by the `registry.default` config key which defaults to +`crates-io`. +{{/option}} diff --git a/src/doc/man/includes/options-release.md b/src/doc/man/includes/options-release.md new file mode 100644 index 0000000..723dbba --- /dev/null +++ b/src/doc/man/includes/options-release.md @@ -0,0 +1,4 @@ +{{#option "`-r`" "`--release`"}} +{{actionverb}} optimized artifacts with the `release` profile. +See also the `--profile` option for choosing a specific profile by name. +{{/option}} diff --git a/src/doc/man/includes/options-target-dir.md b/src/doc/man/includes/options-target-dir.md new file mode 100644 index 0000000..3646e95 --- /dev/null +++ b/src/doc/man/includes/options-target-dir.md @@ -0,0 +1,13 @@ +{{#option "`--target-dir` _directory_"}} +Directory for all generated artifacts and intermediate files. May also be +specified with the `CARGO_TARGET_DIR` environment variable, or the +`build.target-dir` [config value](../reference/config.html). +{{#if temp-target-dir}} Defaults to a new temporary folder located in the +temporary directory of the platform. + +When using `--path`, by default it will use `target` directory in the workspace +of the local crate unless `--target-dir` +is specified. +{{else}} Defaults to `target` in the root of the workspace. +{{/if}} +{{/option}} diff --git a/src/doc/man/includes/options-target-triple.md b/src/doc/man/includes/options-target-triple.md new file mode 100644 index 0000000..bb180f5 --- /dev/null +++ b/src/doc/man/includes/options-target-triple.md @@ -0,0 +1,16 @@ +{{#option "`--target` _triple_"}} +{{actionverb}} for the given architecture. +{{~#if target-default-to-all-arch}} The default is all architectures. +{{~else}} The default is the host architecture. +{{~/if}} The general format of the triple is +`<arch><sub>-<vendor>-<sys>-<abi>`. Run `rustc --print target-list` for a +list of supported targets. +{{~#if multitarget }} This flag may be specified multiple times. {{~/if}} + +This may also be specified with the `build.target` +[config value](../reference/config.html). + +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +[build cache](../guide/build-cache.html) documentation for more details. +{{/option}} diff --git a/src/doc/man/includes/options-targets-bin-auto-built.md b/src/doc/man/includes/options-targets-bin-auto-built.md new file mode 100644 index 0000000..c2234ab --- /dev/null +++ b/src/doc/man/includes/options-targets-bin-auto-built.md @@ -0,0 +1,8 @@ +Binary targets are automatically built if there is an integration test or +benchmark being selected to {{lower actionverb}}. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. diff --git a/src/doc/man/includes/options-targets-lib-bin.md b/src/doc/man/includes/options-targets-lib-bin.md new file mode 100644 index 0000000..14342ac --- /dev/null +++ b/src/doc/man/includes/options-targets-lib-bin.md @@ -0,0 +1,12 @@ +{{#option "`--lib`" }} +{{actionverb}} the package's library. +{{/option}} + +{{#option "`--bin` _name_..." }} +{{actionverb}} the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--bins`" }} +{{actionverb}} all binary targets. +{{/option}} diff --git a/src/doc/man/includes/options-targets.md b/src/doc/man/includes/options-targets.md new file mode 100644 index 0000000..3332001 --- /dev/null +++ b/src/doc/man/includes/options-targets.md @@ -0,0 +1,57 @@ +Passing target selection flags will {{lower actionverb}} only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +{{#options}} + +{{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + +{{#option "`--test` _name_..." }} +{{actionverb}} the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +{{/option}} + +{{#option "`--tests`" }} +{{actionverb}} all targets in test mode that have the `test = true` manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the `test` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--bench` _name_..." }} +{{actionverb}} the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +{{/option}} + +{{#option "`--benches`" }} +{{actionverb}} all targets in benchmark mode that have the `bench = true` +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the `bench` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--all-targets`" }} +{{actionverb}} all targets. This is equivalent to specifying `--lib --bins +--tests --benches --examples`. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-test.md b/src/doc/man/includes/options-test.md new file mode 100644 index 0000000..1d2447e --- /dev/null +++ b/src/doc/man/includes/options-test.md @@ -0,0 +1,14 @@ +{{#options}} + +{{#option "`--no-run`" }} +Compile, but don't run {{nouns}}. +{{/option}} + +{{#option "`--no-fail-fast`" }} +Run all {{nouns}} regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all {{nouns}} +within the executable to completion, this flag only applies to the executable +as a whole. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md new file mode 100644 index 0000000..d4e5998 --- /dev/null +++ b/src/doc/man/includes/options-timings.md @@ -0,0 +1,16 @@ +{{#option "`--timings=`_fmts_"}} +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; `--timings` without an argument will default to `--timings=html`. +Specifying an output format (rather than the default) is unstable and requires +`-Zunstable-options`. Valid output formats: + +- `html` (unstable, requires `-Zunstable-options`): Write a human-readable file `cargo-timing.html` to the + `target/cargo-timings` directory with a report of the compilation. Also write + a report to the same directory with a timestamp in the filename if you want + to look at older runs. HTML output is suitable for human consumption only, + and does not provide machine-readable timing data. +- `json` (unstable, requires `-Zunstable-options`): Emit machine-readable JSON + information about timing information. +{{/option}} + diff --git a/src/doc/man/includes/options-token.md b/src/doc/man/includes/options-token.md new file mode 100644 index 0000000..855204d --- /dev/null +++ b/src/doc/man/includes/options-token.md @@ -0,0 +1,11 @@ +{{#option "`--token` _token_" }} +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by {{man "cargo-login" 1}}). + +[Cargo config](../reference/config.html) environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment +variable. Tokens for other registries may be specified with environment +variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name +of the registry in all capital letters. +{{/option}} diff --git a/src/doc/man/includes/section-environment.md b/src/doc/man/includes/section-environment.md new file mode 100644 index 0000000..aae5f07 --- /dev/null +++ b/src/doc/man/includes/section-environment.md @@ -0,0 +1,4 @@ +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. diff --git a/src/doc/man/includes/section-exit-status.md b/src/doc/man/includes/section-exit-status.md new file mode 100644 index 0000000..a812336 --- /dev/null +++ b/src/doc/man/includes/section-exit-status.md @@ -0,0 +1,4 @@ +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. diff --git a/src/doc/man/includes/section-features.md b/src/doc/man/includes/section-features.md new file mode 100644 index 0000000..99c13fe --- /dev/null +++ b/src/doc/man/includes/section-features.md @@ -0,0 +1,26 @@ +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +{{#options}} + +{{#option "`-F` _features_" "`--features` _features_" }} +Space or comma separated list of features to activate. Features of workspace +members may be enabled with `package-name/feature-name` syntax. This flag may +be specified multiple times, which enables all specified features. +{{/option}} + +{{#option "`--all-features`" }} +Activate all available features of all selected packages. +{{/option}} + +{{#option "`--no-default-features`" }} +Do not activate the `default` feature of the selected packages. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-options-common.md b/src/doc/man/includes/section-options-common.md new file mode 100644 index 0000000..510db53 --- /dev/null +++ b/src/doc/man/includes/section-options-common.md @@ -0,0 +1,38 @@ +### Common Options + +{{#options}} + +{{#option "`+`_toolchain_"}} +If Cargo has been installed with rustup, and the first argument to `cargo` +begins with `+`, it will be interpreted as a rustup toolchain name (such +as `+stable` or `+nightly`). +See the [rustup documentation](https://rust-lang.github.io/rustup/overrides.html) +for more information about how toolchain overrides work. +{{/option}} + +{{#option "`--config` _KEY=VALUE_ or _PATH_"}} +Overrides a Cargo configuration value. The argument should be in TOML syntax of `KEY=VALUE`, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the [command-line overrides section](../reference/config.html#command-line-overrides) for more information. +{{/option}} + +{{#option "`-C` _PATH_"}} +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (`Cargo.toml`), as well as +the directories searched for discovering `.cargo/config.toml`, for example. + +This option is only available on the [nightly +channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and +requires the `-Z unstable-options` flag to enable (see +[#10098](https://github.com/rust-lang/cargo/issues/10098)). +{{/option}} + +{{#option "`-h`" "`--help`"}} +Prints help information. +{{/option}} + +{{#option "`-Z` _flag_"}} +Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for details. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-options-package.md b/src/doc/man/includes/section-options-package.md new file mode 100644 index 0000000..4fa732d --- /dev/null +++ b/src/doc/man/includes/section-options-package.md @@ -0,0 +1,13 @@ +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +{{#options}} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +The package to {{lower actionverb}}. See {{man "cargo-pkgid" 1}} for the SPEC +format. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-package-selection.md b/src/doc/man/includes/section-package-selection.md new file mode 100644 index 0000000..8d7d621 --- /dev/null +++ b/src/doc/man/includes/section-package-selection.md @@ -0,0 +1,42 @@ +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..."}} +{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like `*`, `?` and `[]`. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +{{/option}} + +{{#option "`--workspace`" }} +{{actionverb}} all members in the workspace. +{{/option}} + +{{#unless noall}} +{{#option "`--all`" }} +Deprecated alias for `--workspace`. +{{/option}} +{{/unless}} + +{{#option "`--exclude` _SPEC_..." }} +Exclude the specified packages. Must be used in conjunction with the +`--workspace` flag. This flag may be specified multiple times and supports +common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +{{/option}} + +{{/options}} diff --git a/src/doc/semver-check/Cargo.toml b/src/doc/semver-check/Cargo.toml new file mode 100644 index 0000000..bdfd8d7 --- /dev/null +++ b/src/doc/semver-check/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "semver-check" +version = "0.1.0" +authors = ["Eric Huss"] +edition = "2021" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +tempfile = "3.1.0" diff --git a/src/doc/semver-check/src/main.rs b/src/doc/semver-check/src/main.rs new file mode 100644 index 0000000..51aacbe --- /dev/null +++ b/src/doc/semver-check/src/main.rs @@ -0,0 +1,289 @@ +//! Test runner for the semver compatibility doc chapter. +//! +//! This extracts all the "rust" annotated code blocks and tests that they +//! either fail or succeed as expected. This also checks that the examples are +//! formatted correctly. +//! +//! An example with the word "MINOR" at the top is expected to successfully +//! build against the before and after. Otherwise it should fail. A comment of +//! "// Error:" will check that the given message appears in the error output. + +use std::error::Error; +use std::fs; +use std::path::Path; +use std::process::{Command, Output}; + +fn main() { + if let Err(e) = doit() { + println!("error: {}", e); + std::process::exit(1); + } +} + +const SEPARATOR: &str = "///////////////////////////////////////////////////////////"; + +fn doit() -> Result<(), Box<dyn Error>> { + let filename = std::env::args() + .nth(1) + .unwrap_or_else(|| "../src/reference/semver.md".to_string()); + let contents = fs::read_to_string(filename)?; + let mut lines = contents.lines().enumerate(); + + loop { + // Find a rust block. + let (block_start, run_program, deny_warnings) = loop { + match lines.next() { + Some((lineno, line)) => { + if line.trim().starts_with("```rust") && !line.contains("skip") { + break ( + lineno + 1, + line.contains("run-fail"), + !line.contains("dont-deny"), + ); + } + } + None => return Ok(()), + } + }; + // Read in the code block. + let mut block = Vec::new(); + loop { + match lines.next() { + Some((_, line)) => { + if line.trim() == "```" { + break; + } + block.push(line); + } + None => { + return Err(format!( + "rust block did not end for example starting on line {}", + block_start + ) + .into()); + } + } + } + // Split it into the separate source files. + let parts: Vec<_> = block.split(|line| line.trim() == SEPARATOR).collect(); + if parts.len() != 4 { + return Err(format!( + "expected 4 sections in example starting on line {}, got {}:\n{:?}", + block_start, + parts.len(), + parts + ) + .into()); + } + let join = |part: &[&str]| { + let mut result = String::new(); + result.push_str("#![allow(unused)]\n"); + if deny_warnings { + result.push_str("#![deny(warnings)]\n"); + } + result.push_str(&part.join("\n")); + if !result.ends_with('\n') { + result.push('\n'); + } + result + }; + let expect_success = parts[0][0].contains("MINOR"); + println!("Running test from line {}", block_start); + + let result = run_test( + join(parts[1]), + join(parts[2]), + join(parts[3]), + expect_success, + run_program, + ); + + if let Err(e) = result { + return Err(format!( + "test failed for example starting on line {}: {}", + block_start, e + ) + .into()); + } + } +} + +const CRATE_NAME: &str = "updated_crate"; + +fn run_test( + before: String, + after: String, + example: String, + expect_success: bool, + run_program: bool, +) -> Result<(), Box<dyn Error>> { + let tempdir = tempfile::TempDir::new()?; + let before_p = tempdir.path().join("before.rs"); + let after_p = tempdir.path().join("after.rs"); + let example_p = tempdir.path().join("example.rs"); + + let check_fn = if run_program { + run_check + } else { + compile_check + }; + + compile_check(before, &before_p, CRATE_NAME, false, true)?; + check_fn(example.clone(), &example_p, "example", true, true)?; + compile_check(after, &after_p, CRATE_NAME, false, true)?; + check_fn(example, &example_p, "example", true, expect_success)?; + Ok(()) +} + +fn check_formatting(path: &Path) -> Result<(), Box<dyn Error>> { + match Command::new("rustfmt") + .args(&["--edition=2018", "--check"]) + .arg(path) + .status() + { + Ok(status) => { + if !status.success() { + return Err(format!("failed to run rustfmt: {}", status).into()); + } + Ok(()) + } + Err(e) => Err(format!("failed to run rustfmt: {}", e).into()), + } +} + +fn compile( + contents: &str, + path: &Path, + crate_name: &str, + extern_path: bool, +) -> Result<Output, Box<dyn Error>> { + let crate_type = if contents.contains("fn main()") { + "bin" + } else { + "rlib" + }; + + fs::write(path, &contents)?; + check_formatting(path)?; + let out_dir = path.parent().unwrap(); + let mut cmd = Command::new("rustc"); + cmd.args(&[ + "--edition=2021", + "--crate-type", + crate_type, + "--crate-name", + crate_name, + "--out-dir", + ]); + cmd.arg(&out_dir); + if extern_path { + let epath = out_dir.join(format!("lib{}.rlib", CRATE_NAME)); + cmd.arg("--extern") + .arg(format!("{}={}", CRATE_NAME, epath.display())); + } + cmd.arg(path); + cmd.output().map_err(Into::into) +} + +fn compile_check( + mut contents: String, + path: &Path, + crate_name: &str, + extern_path: bool, + expect_success: bool, +) -> Result<(), Box<dyn Error>> { + // If the example has an error message, remove it so that it can be + // compared with the actual output, and also to avoid issues with rustfmt + // moving it around. + let expected_error = match contents.find("// Error:") { + Some(index) => { + let start = contents[..index].rfind(|ch| ch != ' ').unwrap(); + let end = contents[index..].find('\n').unwrap(); + let error = contents[index + 9..index + end].trim().to_string(); + contents.replace_range(start + 1..index + end, ""); + Some(error) + } + None => None, + }; + + let output = compile(&contents, path, crate_name, extern_path)?; + + let stderr = std::str::from_utf8(&output.stderr).unwrap(); + match (output.status.success(), expect_success) { + (true, true) => Ok(()), + (true, false) => Err(format!( + "expected failure, got success {}\n===== Contents:\n{}\n===== Output:\n{}\n", + path.display(), + contents, + stderr + ) + .into()), + (false, true) => Err(format!( + "expected success, got error {}\n===== Contents:\n{}\n===== Output:\n{}\n", + path.display(), + contents, + stderr + ) + .into()), + (false, false) => { + if expected_error.is_none() { + return Err("failing test should have an \"// Error:\" annotation ".into()); + } + let expected_error = expected_error.unwrap(); + if !stderr.contains(&expected_error) { + Err(format!( + "expected error message not found in compiler output\nExpected: {}\nGot:\n{}\n", + expected_error, stderr + ) + .into()) + } else { + Ok(()) + } + } + } +} + +fn run_check( + contents: String, + path: &Path, + crate_name: &str, + extern_path: bool, + expect_success: bool, +) -> Result<(), Box<dyn Error>> { + let compile_output = compile(&contents, path, crate_name, extern_path)?; + + if !compile_output.status.success() { + let stderr = std::str::from_utf8(&compile_output.stderr).unwrap(); + return Err(format!( + "expected success, got error {}\n===== Contents:\n{}\n===== Output:\n{}\n", + path.display(), + contents, + stderr + ) + .into()); + } + + let binary_path = path.parent().unwrap().join(crate_name); + + let output = Command::new(binary_path).output()?; + + let stderr = std::str::from_utf8(&output.stderr).unwrap(); + + match (output.status.success(), expect_success) { + (true, false) => Err(format!( + "expected panic, got success {}\n===== Contents:\n{}\n===== Output:\n{}\n", + path.display(), + contents, + stderr + ) + .into()), + (false, true) => Err(format!( + "expected success, got panic {}\n===== Contents:\n{}\n===== Output:\n{}\n", + path.display(), + contents, + stderr, + ) + .into()), + (_, _) => Ok(()), + } +} diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md new file mode 100644 index 0000000..c44bc86 --- /dev/null +++ b/src/doc/src/SUMMARY.md @@ -0,0 +1,92 @@ +# Summary + +[Introduction](index.md) + +* [Getting Started](getting-started/index.md) + * [Installation](getting-started/installation.md) + * [First Steps with Cargo](getting-started/first-steps.md) + +* [Cargo Guide](guide/index.md) + * [Why Cargo Exists](guide/why-cargo-exists.md) + * [Creating a New Package](guide/creating-a-new-project.md) + * [Working on an Existing Package](guide/working-on-an-existing-project.md) + * [Dependencies](guide/dependencies.md) + * [Package Layout](guide/project-layout.md) + * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md) + * [Tests](guide/tests.md) + * [Continuous Integration](guide/continuous-integration.md) + * [Cargo Home](guide/cargo-home.md) + * [Build Cache](guide/build-cache.md) + +* [Cargo Reference](reference/index.md) + * [Specifying Dependencies](reference/specifying-dependencies.md) + * [Overriding Dependencies](reference/overriding-dependencies.md) + * [The Manifest Format](reference/manifest.md) + * [Cargo Targets](reference/cargo-targets.md) + * [Workspaces](reference/workspaces.md) + * [Features](reference/features.md) + * [Features Examples](reference/features-examples.md) + * [Profiles](reference/profiles.md) + * [Configuration](reference/config.md) + * [Environment Variables](reference/environment-variables.md) + * [Build Scripts](reference/build-scripts.md) + * [Build Script Examples](reference/build-script-examples.md) + * [Publishing on crates.io](reference/publishing.md) + * [Package ID Specifications](reference/pkgid-spec.md) + * [Source Replacement](reference/source-replacement.md) + * [External Tools](reference/external-tools.md) + * [Registries](reference/registries.md) + * [Running a Registry](reference/running-a-registry.md) + * [Registry Index](reference/registry-index.md) + * [Registry Web API](reference/registry-web-api.md) + * [Dependency Resolution](reference/resolver.md) + * [SemVer Compatibility](reference/semver.md) + * [Future incompat report](reference/future-incompat-report.md) + * [Reporting build timings](reference/timings.md) + * [Unstable Features](reference/unstable.md) + +* [Cargo Commands](commands/index.md) + * [General Commands](commands/general-commands.md) + * [cargo](commands/cargo.md) + * [cargo help](commands/cargo-help.md) + * [cargo version](commands/cargo-version.md) + * [Build Commands](commands/build-commands.md) + * [cargo bench](commands/cargo-bench.md) + * [cargo build](commands/cargo-build.md) + * [cargo check](commands/cargo-check.md) + * [cargo clean](commands/cargo-clean.md) + * [cargo doc](commands/cargo-doc.md) + * [cargo fetch](commands/cargo-fetch.md) + * [cargo fix](commands/cargo-fix.md) + * [cargo run](commands/cargo-run.md) + * [cargo rustc](commands/cargo-rustc.md) + * [cargo rustdoc](commands/cargo-rustdoc.md) + * [cargo test](commands/cargo-test.md) + * [cargo report](commands/cargo-report.md) + * [Manifest Commands](commands/manifest-commands.md) + * [cargo add](commands/cargo-add.md) + * [cargo generate-lockfile](commands/cargo-generate-lockfile.md) + * [cargo locate-project](commands/cargo-locate-project.md) + * [cargo metadata](commands/cargo-metadata.md) + * [cargo pkgid](commands/cargo-pkgid.md) + * [cargo remove](commands/cargo-remove.md) + * [cargo tree](commands/cargo-tree.md) + * [cargo update](commands/cargo-update.md) + * [cargo vendor](commands/cargo-vendor.md) + * [cargo verify-project](commands/cargo-verify-project.md) + * [Package Commands](commands/package-commands.md) + * [cargo init](commands/cargo-init.md) + * [cargo install](commands/cargo-install.md) + * [cargo new](commands/cargo-new.md) + * [cargo search](commands/cargo-search.md) + * [cargo uninstall](commands/cargo-uninstall.md) + * [Publishing Commands](commands/publishing-commands.md) + * [cargo login](commands/cargo-login.md) + * [cargo owner](commands/cargo-owner.md) + * [cargo package](commands/cargo-package.md) + * [cargo publish](commands/cargo-publish.md) + * [cargo yank](commands/cargo-yank.md) + +* [FAQ](faq.md) +* [Appendix: Glossary](appendix/glossary.md) +* [Appendix: Git Authentication](appendix/git-authentication.md) diff --git a/src/doc/src/appendix/git-authentication.md b/src/doc/src/appendix/git-authentication.md new file mode 100644 index 0000000..8b2db5c --- /dev/null +++ b/src/doc/src/appendix/git-authentication.md @@ -0,0 +1,96 @@ +# Git Authentication + +Cargo supports some forms of authentication when using git dependencies and +registries. This appendix contains some information for setting up git +authentication in a way that works with Cargo. + +If you need other authentication methods, the [`net.git-fetch-with-cli`] +config value can be set to cause Cargo to execute the `git` executable to +handle fetching remote repositories instead of using the built-in support. +This can be enabled with the `CARGO_NET_GIT_FETCH_WITH_CLI=true` environment +variable. + +## HTTPS authentication + +HTTPS authentication requires the [`credential.helper`] mechanism. There are +multiple credential helpers, and you specify the one you want to use in your +global git configuration file. + +```ini +# ~/.gitconfig + +[credential] +helper = store +``` + +Cargo does not ask for passwords, so for most helpers you will need to give +the helper the initial username/password before running Cargo. One way to do +this is to run `git clone` of the private git repo and enter the +username/password. + +> **Tip:**<br> +> macOS users may want to consider using the osxkeychain helper.<br> +> Windows users may want to consider using the [GCM] helper. + +> **Note:** Windows users will need to make sure that the `sh` shell is +> available in your `PATH`. This typically is available with the Git for +> Windows installation. + +## SSH authentication + +SSH authentication requires `ssh-agent` to be running to acquire the SSH key. +Make sure the appropriate environment variables are set up (`SSH_AUTH_SOCK` on +most Unix-like systems), and that the correct keys are added (with `ssh-add`). + +Windows can use Pageant (part of [PuTTY]) or `ssh-agent`. +To use `ssh-agent`, Cargo needs to use the OpenSSH that is distributed as part +of Windows, as Cargo does not support the simulated Unix-domain sockets used +by MinGW or Cygwin. +More information about installing with Windows can be found at the [Microsoft +installation documentation] and the page on [key management] has instructions +on how to start `ssh-agent` and to add keys. + +> **Note:** Cargo does not support git's shorthand SSH URLs like +> `git@example.com:user/repo.git`. Use a full SSH URL like +> `ssh://git@example.com/user/repo.git`. + +> **Note:** SSH configuration files (like OpenSSH's `~/.ssh/config`) are not +> used by Cargo's built-in SSH library. More advanced requirements should use +> [`net.git-fetch-with-cli`]. + +### SSH Known Hosts + +When connecting to an SSH host, Cargo must verify the identity of the host +using "known hosts", which are a list of host keys. Cargo can look for these +known hosts in OpenSSH-style `known_hosts` files located in their standard +locations (`.ssh/known_hosts` in your home directory, or +`/etc/ssh/ssh_known_hosts` on Unix-like platforms or +`%PROGRAMDATA%\ssh\ssh_known_hosts` on Windows). More information about these +files can be found in the [sshd man page]. Alternatively, keys may be +configured in a Cargo configuration file with [`net.ssh.known-hosts`]. + +When connecting to an SSH host before the known hosts has been configured, +Cargo will display an error message instructing you how to add the host key. +This also includes a "fingerprint", which is a smaller hash of the host key, +which should be easier to visually verify. The server administrator can get +the fingerprint by running `ssh-keygen` against the public key (for example, +`ssh-keygen -l -f /etc/ssh/ssh_host_ecdsa_key.pub`). Well-known sites may +publish their fingerprints on the web; for example GitHub posts theirs at +<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints>. + +Cargo comes with the host keys for [github.com](https://github.com) built-in. +If those ever change, you can add the new keys to the config or known_hosts file. + +> **Note:** Cargo doesn't support the `@cert-authority` or `@revoked` +> markers in `known_hosts` files. To make use of this functionality, use +> [`net.git-fetch-with-cli`]. This is also a good tip if Cargo's SSH client +> isn't behaving the way you expect it to. + +[`credential.helper`]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage +[`net.git-fetch-with-cli`]: ../reference/config.md#netgit-fetch-with-cli +[`net.ssh.known-hosts`]: ../reference/config.md#netsshknown-hosts +[GCM]: https://github.com/microsoft/Git-Credential-Manager-Core/ +[PuTTY]: https://www.chiark.greenend.org.uk/~sgtatham/putty/ +[Microsoft installation documentation]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse +[key management]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement +[sshd man page]: https://man.openbsd.org/sshd#SSH_KNOWN_HOSTS_FILE_FORMAT diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md new file mode 100644 index 0000000..1437368 --- /dev/null +++ b/src/doc/src/appendix/glossary.md @@ -0,0 +1,274 @@ +# Glossary + +### Artifact + +An *artifact* is the file or set of files created as a result of the +compilation process. This includes linkable libraries, executable binaries, +and generated documentation. + +### Cargo + +*Cargo* is the Rust [*package manager*](#package-manager), and the primary +topic of this book. + +### Cargo.lock + +See [*lock file*](#lock-file). + +### Cargo.toml + +See [*manifest*](#manifest). + +### Crate + +A Rust *crate* is either a library or an executable program, referred to as +either a *library crate* or a *binary crate*, respectively. + +Every [target](#target) defined for a Cargo [package](#package) is a *crate*. + +Loosely, the term *crate* may refer to either the source code of the target or +to the compiled artifact that the target produces. It may also refer to a +compressed package fetched from a [registry](#registry). + +The source code for a given crate may be subdivided into [*modules*](#module). + +### Edition + +A *Rust edition* is a developmental landmark of the Rust language. The +[edition of a package][edition-field] is specified in the `Cargo.toml` +[manifest](#manifest), and individual targets can specify which edition they +use. See the [Edition Guide] for more information. + +### Feature + +The meaning of *feature* depends on the context: + +- A [*feature*][feature] is a named flag which allows for conditional + compilation. A feature can refer to an optional dependency, or an arbitrary + name defined in a `Cargo.toml` [manifest](#manifest) that can be checked + within source code. + +- Cargo has [*unstable feature flags*][cargo-unstable] which can be used to + enable experimental behavior of Cargo itself. + +- The Rust compiler and Rustdoc have their own unstable feature flags (see + [The Unstable Book][unstable-book] and [The Rustdoc + Book][rustdoc-unstable]). + +- CPU targets have [*target features*][target-feature] which specify + capabilities of a CPU. + +### Index + +The *index* is the searchable list of [*crates*](#crate) in a +[*registry*](#registry). + +### Lock file + +The `Cargo.lock` *lock file* is a file that captures the exact version of +every dependency used in a [*workspace*](#workspace) or +[*package*](#package). It is automatically generated by Cargo. See +[Cargo.toml vs Cargo.lock]. + +### Manifest + +A [*manifest*][manifest] is a description of a [package](#package) or a +[workspace](#workspace) in a file named `Cargo.toml`. + +A [*virtual manifest*][virtual] is a `Cargo.toml` file that only describes a +workspace, and does not include a package. + +### Member + +A *member* is a [*package*](#package) that belongs to a +[*workspace*](#workspace). + +### Module + +Rust's module system is used to organize code into logical units called +*modules*, which provide isolated namespaces within the code. + +The source code for a given [crate](#crate) may be subdivided into one or more +separate modules. This is usually done to organize the code into areas of +related functionality or to control the visible scope (public/private) of +symbols within the source (structs, functions, and so on). + +A [`Cargo.toml`](#manifest) file is primarily concerned with the +[package](#package) it defines, its crates, and the packages of the crates on +which they depend. Nevertheless, you will see the term "module" often when +working with Rust, so you should understand its relationship to a given crate. + +### Package + +A *package* is a collection of source files and a `Cargo.toml` +[*manifest*](#manifest) file which describes the package. A package has a name +and version which is used for specifying dependencies between packages. + +A package contains multiple [*targets*](#target), each of which is a +[*crate*](#crate). The `Cargo.toml` file describes the type of the crates +(binary or library) within the package, along with some metadata about each +one --- how each is to be built, what their direct dependencies are, etc., as +described throughout this book. + +The *package root* is the directory where the package's `Cargo.toml` manifest +is located. (Compare with [*workspace root*](#workspace).) + +The [*package ID specification*][pkgid-spec], or *SPEC*, is a string used to +uniquely reference a specific version of a package from a specific source. + +Small to medium sized Rust projects will only need a single package, though it +is common for them to have multiple crates. + +Larger projects may involve multiple packages, in which case Cargo +[*workspaces*](#workspace) can be used to manage common dependencies and other +related metadata between the packages. + +### Package manager + +Broadly speaking, a *package manager* is a program (or collection of related +programs) in a software ecosystem that automates the process of obtaining, +installing, and upgrading artifacts. Within a programming language ecosystem, +a package manager is a developer-focused tool whose primary functionality is +to download library artifacts and their dependencies from some central +repository; this capability is often combined with the ability to perform +software builds (by invoking the language-specific compiler). + +[*Cargo*](#cargo) is the package manager within the Rust ecosystem. Cargo +downloads your Rust [package](#package)’s dependencies +([*artifacts*](#artifact) known as [*crates*](#crate)), compiles your +packages, makes distributable packages, and (optionally) uploads them to +[crates.io][], the Rust community’s [*package registry*](#registry). + +### Package registry + +See [*registry*](#registry). + +### Project + +Another name for a [package](#package). + +### Registry + +A *registry* is a service that contains a collection of downloadable +[*crates*](#crate) that can be installed or used as dependencies for a +[*package*](#package). The default registry in the Rust ecosystem is +[crates.io](https://crates.io). The registry has an [*index*](#index) which +contains a list of all crates, and tells Cargo how to download the crates that +are needed. + +### Source + +A *source* is a provider that contains [*crates*](#crate) that may be included +as dependencies for a [*package*](#package). There are several kinds of +sources: + +- **Registry source** --- See [registry](#registry). +- **Local registry source** --- A set of crates stored as compressed files on + the filesystem. See [Local Registry Sources]. +- **Directory source** --- A set of crates stored as uncompressed files on the + filesystem. See [Directory Sources]. +- **Path source** --- An individual package located on the filesystem (such as a + [path dependency]) or a set of multiple packages (such as [path overrides]). +- **Git source** --- Packages located in a git repository (such as a [git + dependency] or [git source]). + +See [Source Replacement] for more information. + +### Spec + +See [package ID specification](#package). + +### Target + +The meaning of the term *target* depends on the context: + +- **Cargo Target** --- Cargo [*packages*](#package) consist of *targets* which + correspond to [*artifacts*](#artifact) that will be produced. Packages can + have library, binary, example, test, and benchmark targets. The + [list of targets][targets] are configured in the `Cargo.toml` + [*manifest*](#manifest), often inferred automatically by the [directory + layout] of the source files. +- **Target Directory** --- Cargo places all built artifacts and intermediate + files in the *target* directory. By default this is a directory named + `target` at the [*workspace*](#workspace) root, or the package root if not + using a workspace. The directory may be changed with the `--target-dir` + command-line option, the `CARGO_TARGET_DIR` [environment variable], or the + `build.target-dir` [config option]. +- **Target Architecture** --- The OS and machine architecture for the built + artifacts are typically referred to as a *target*. +- **Target Triple** --- A triple is a specific format for specifying a target + architecture. Triples may be referred to as a *target triple* which is the + architecture for the artifact produced, and the *host triple* which is the + architecture that the compiler is running on. The target triple can be + specified with the `--target` command-line option or the `build.target` + [config option]. The general format of the triple is + `<arch><sub>-<vendor>-<sys>-<abi>` where: + + - `arch` = The base CPU architecture, for example `x86_64`, `i686`, `arm`, + `thumb`, `mips`, etc. + - `sub` = The CPU sub-architecture, for example `arm` has `v7`, `v7s`, + `v5te`, etc. + - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `nvidia`, etc. + - `sys` = The system name, for example `linux`, `windows`, `darwin`, etc. + `none` is typically used for bare-metal without an OS. + - `abi` = The ABI, for example `gnu`, `android`, `eabi`, etc. + + Some parameters may be omitted. Run `rustc --print target-list` for a list of + supported targets. + +### Test Targets + +Cargo *test targets* generate binaries which help verify proper operation and +correctness of code. There are two types of test artifacts: + +* **Unit test** --- A *unit test* is an executable binary compiled directly from + a library or a binary target. It contains the entire contents of the library + or binary code, and runs `#[test]` annotated functions, intended to verify + individual units of code. +* **Integration test target** --- An [*integration test + target*][integration-tests] is an executable binary compiled from a *test + target* which is a distinct [*crate*](#crate) whose source is located in the + `tests` directory or specified by the [`[[test]]` table][targets] in the + `Cargo.toml` [*manifest*](#manifest). It is intended to only test the public + API of a library, or execute a binary to verify its operation. + +### Workspace + +A [*workspace*][workspace] is a collection of one or more +[*packages*](#package) that share common dependency resolution (with a shared +`Cargo.lock` [*lock file*](#lock-file)), output directory, and various +settings such as profiles. + +A [*virtual workspace*][virtual] is a workspace where the root `Cargo.toml` +[*manifest*](#manifest) does not define a package, and only lists the +workspace [*members*](#member). + +The *workspace root* is the directory where the workspace's `Cargo.toml` +manifest is located. (Compare with [*package root*](#package).) + + +[Cargo.toml vs Cargo.lock]: ../guide/cargo-toml-vs-cargo-lock.md +[Directory Sources]: ../reference/source-replacement.md#directory-sources +[Local Registry Sources]: ../reference/source-replacement.md#local-registry-sources +[Source Replacement]: ../reference/source-replacement.md +[cargo-unstable]: ../reference/unstable.md +[config option]: ../reference/config.md +[crates.io]: https://crates.io/ +[directory layout]: ../guide/project-layout.md +[edition guide]: ../../edition-guide/index.html +[edition-field]: ../reference/manifest.md#the-edition-field +[environment variable]: ../reference/environment-variables.md +[feature]: ../reference/features.md +[git dependency]: ../reference/specifying-dependencies.md#specifying-dependencies-from-git-repositories +[git source]: ../reference/source-replacement.md +[integration-tests]: ../reference/cargo-targets.md#integration-tests +[manifest]: ../reference/manifest.md +[path dependency]: ../reference/specifying-dependencies.md#specifying-path-dependencies +[path overrides]: ../reference/overriding-dependencies.md#paths-overrides +[pkgid-spec]: ../reference/pkgid-spec.md +[rustdoc-unstable]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html +[target-feature]: ../../reference/attributes/codegen.html#the-target_feature-attribute +[targets]: ../reference/cargo-targets.md#configuring-a-target +[unstable-book]: https://doc.rust-lang.org/nightly/unstable-book/index.html +[virtual]: ../reference/workspaces.md +[workspace]: ../reference/workspaces.md diff --git a/src/doc/src/commands/build-commands.md b/src/doc/src/commands/build-commands.md new file mode 100644 index 0000000..5cc6fff --- /dev/null +++ b/src/doc/src/commands/build-commands.md @@ -0,0 +1,13 @@ +# Build Commands +* [cargo bench](cargo-bench.md) +* [cargo build](cargo-build.md) +* [cargo check](cargo-check.md) +* [cargo clean](cargo-clean.md) +* [cargo doc](cargo-doc.md) +* [cargo fetch](cargo-fetch.md) +* [cargo fix](cargo-fix.md) +* [cargo run](cargo-run.md) +* [cargo rustc](cargo-rustc.md) +* [cargo rustdoc](cargo-rustdoc.md) +* [cargo test](cargo-test.md) +* [cargo report](cargo-report.md) diff --git a/src/doc/src/commands/cargo-add.md b/src/doc/src/commands/cargo-add.md new file mode 100644 index 0000000..d2698c0 --- /dev/null +++ b/src/doc/src/commands/cargo-add.md @@ -0,0 +1,280 @@ +# cargo-add(1) + + + + +## NAME + +cargo-add --- Add dependencies to a Cargo.toml manifest file + +## SYNOPSIS + +`cargo add` [_options_] _crate_...\ +`cargo add` [_options_] `--path` _path_\ +`cargo add` [_options_] `--git` _url_ [_crate_...]\ + + +## DESCRIPTION + +This command can add or modify dependencies. + +The source for the dependency can be specified with: + +* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_" +* `--path` _path_: Fetch from the specified _path_ +* `--git` _url_: Pull from a git repo at _url_ + +If no source is specified, then a best effort will be made to select one, including: + +* Existing dependencies in other tables (like `dev-dependencies`) +* Workspace members +* Latest release in the registry + +When you add a package that is already present, the existing entry will be updated with the flags specified. + +Upon successful invocation, the enabled (`+`) and disabled (`-`) [features] of the specified +dependency will be listed in the command's output. + +[features]: ../reference/features.md + +## OPTIONS + +### Source options + +<dl> + +<dt class="option-term" id="option-cargo-add---git"><a class="option-anchor" href="#option-cargo-add---git"></a><code>--git</code> <em>url</em></dt> +<dd class="option-desc"><a href="../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories">Git URL to add the specified crate from</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---branch"><a class="option-anchor" href="#option-cargo-add---branch"></a><code>--branch</code> <em>branch</em></dt> +<dd class="option-desc">Branch to use when adding from git.</dd> + + +<dt class="option-term" id="option-cargo-add---tag"><a class="option-anchor" href="#option-cargo-add---tag"></a><code>--tag</code> <em>tag</em></dt> +<dd class="option-desc">Tag to use when adding from git.</dd> + + +<dt class="option-term" id="option-cargo-add---rev"><a class="option-anchor" href="#option-cargo-add---rev"></a><code>--rev</code> <em>sha</em></dt> +<dd class="option-desc">Specific commit to use when adding from git.</dd> + + +<dt class="option-term" id="option-cargo-add---path"><a class="option-anchor" href="#option-cargo-add---path"></a><code>--path</code> <em>path</em></dt> +<dd class="option-desc"><a href="../reference/specifying-dependencies.html#specifying-path-dependencies">Filesystem path</a> to local crate to add.</dd> + + +<dt class="option-term" id="option-cargo-add---registry"><a class="option-anchor" href="#option-cargo-add---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + + +</dl> + +### Section options + +<dl> + +<dt class="option-term" id="option-cargo-add---dev"><a class="option-anchor" href="#option-cargo-add---dev"></a><code>--dev</code></dt> +<dd class="option-desc">Add as a <a href="../reference/specifying-dependencies.html#development-dependencies">development dependency</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---build"><a class="option-anchor" href="#option-cargo-add---build"></a><code>--build</code></dt> +<dd class="option-desc">Add as a <a href="../reference/specifying-dependencies.html#build-dependencies">build dependency</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---target"><a class="option-anchor" href="#option-cargo-add---target"></a><code>--target</code> <em>target</em></dt> +<dd class="option-desc">Add as a dependency to the <a href="../reference/specifying-dependencies.html#platform-specific-dependencies">given target platform</a>.</dd> + + +</dl> + + +</dl> + +### Dependency options + +<dl> + +<dt class="option-term" id="option-cargo-add---dry-run"><a class="option-anchor" href="#option-cargo-add---dry-run"></a><code>--dry-run</code></dt> +<dd class="option-desc">Don’t actually write the manifest</dd> + + +<dt class="option-term" id="option-cargo-add---rename"><a class="option-anchor" href="#option-cargo-add---rename"></a><code>--rename</code> <em>name</em></dt> +<dd class="option-desc"><a href="../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml">Rename</a> the dependency.</dd> + + +<dt class="option-term" id="option-cargo-add---optional"><a class="option-anchor" href="#option-cargo-add---optional"></a><code>--optional</code></dt> +<dd class="option-desc">Mark the dependency as <a href="../reference/features.html#optional-dependencies">optional</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---no-optional"><a class="option-anchor" href="#option-cargo-add---no-optional"></a><code>--no-optional</code></dt> +<dd class="option-desc">Mark the dependency as <a href="../reference/features.html#optional-dependencies">required</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---no-default-features"><a class="option-anchor" href="#option-cargo-add---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Disable the <a href="../reference/features.html#dependency-features">default features</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---default-features"><a class="option-anchor" href="#option-cargo-add---default-features"></a><code>--default-features</code></dt> +<dd class="option-desc">Re-enable the <a href="../reference/features.html#dependency-features">default features</a>.</dd> + + +<dt class="option-term" id="option-cargo-add--F"><a class="option-anchor" href="#option-cargo-add--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-add---features"><a class="option-anchor" href="#option-cargo-add---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of <a href="../reference/features.html#dependency-features">features to +activate</a>. When adding multiple +crates, the features for a specific crate may be enabled with +<code>package-name/feature-name</code> syntax. This flag may be specified multiple times, +which enables all specified features.</dd> + + +</dl> + + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-add--v"><a class="option-anchor" href="#option-cargo-add--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-add---verbose"><a class="option-anchor" href="#option-cargo-add---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-add--q"><a class="option-anchor" href="#option-cargo-add--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-add---quiet"><a class="option-anchor" href="#option-cargo-add---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-add---color"><a class="option-anchor" href="#option-cargo-add---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-add---manifest-path"><a class="option-anchor" href="#option-cargo-add---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-add--p"><a class="option-anchor" href="#option-cargo-add--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-add---package"><a class="option-anchor" href="#option-cargo-add---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">Add dependencies to only the specified package.</dd> + + +<dt class="option-term" id="option-cargo-add---frozen"><a class="option-anchor" href="#option-cargo-add---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-add---locked"><a class="option-anchor" href="#option-cargo-add---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-add---offline"><a class="option-anchor" href="#option-cargo-add---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-add-+toolchain"><a class="option-anchor" href="#option-cargo-add-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-add---config"><a class="option-anchor" href="#option-cargo-add---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-add--C"><a class="option-anchor" href="#option-cargo-add--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-add--h"><a class="option-anchor" href="#option-cargo-add--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-add---help"><a class="option-anchor" href="#option-cargo-add---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-add--Z"><a class="option-anchor" href="#option-cargo-add--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Add `regex` as a dependency + + cargo add regex + +2. Add `trybuild` as a dev-dependency + + cargo add --dev trybuild + +3. Add an older version of `nom` as a dependency + + cargo add nom@5 + +4. Add support for serializing data structures to json with `derive`s + + cargo add serde serde_json -F serde/derive + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-remove(1)](cargo-remove.html) diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md new file mode 100644 index 0000000..50c461c --- /dev/null +++ b/src/doc/src/commands/cargo-bench.md @@ -0,0 +1,499 @@ +# cargo-bench(1) + + + + +## NAME + +cargo-bench --- Execute benchmarks of a package + +## SYNOPSIS + +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] + +## DESCRIPTION + +Compile and execute benchmarks. + +The benchmark filtering argument _benchname_ and all the arguments following +the two dashes (`--`) are passed to the benchmark binaries and thus to +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help` and check out the rustc +book's chapter on how tests work at +<https://doc.rust-lang.org/rustc/tests/index.html>. + +As an example, this will run only the benchmark named `foo` (and skip other +similarly named benchmarks like `foobar`): + + cargo bench -- foo --exact + +Benchmarks are built with the `--test` option to `rustc` which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the `#[bench]` attribute. +Cargo passes the `--bench` flag to the test harness to tell it to run +only benchmarks. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running benchmarks. + +> **Note**: The +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +> is currently unstable and only available on the +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). +> There are some packages available on +> [crates.io](https://crates.io/keywords/benchmark) that may help with +> running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +By default, `cargo bench` uses the [`bench` profile], which enables +optimizations and disables debugging information. If you need to debug a +benchmark, you can use the `--profile=dev` command-line option to switch to +the dev profile. You can then run the debug-enabled benchmark within a +debugger. + +[`bench` profile]: ../reference/profiles.html#bench + +## OPTIONS + +### Benchmark Options + +<dl> + +<dt class="option-term" id="option-cargo-bench---no-run"><a class="option-anchor" href="#option-cargo-bench---no-run"></a><code>--no-run</code></dt> +<dd class="option-desc">Compile, but don’t run benchmarks.</dd> + + +<dt class="option-term" id="option-cargo-bench---no-fail-fast"><a class="option-anchor" href="#option-cargo-bench---no-fail-fast"></a><code>--no-fail-fast</code></dt> +<dd class="option-desc">Run all benchmarks regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all benchmarks +within the executable to completion, this flag only applies to the executable +as a whole.</dd> + + +</dl> + + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-bench--p"><a class="option-anchor" href="#option-cargo-bench--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-bench---package"><a class="option-anchor" href="#option-cargo-bench---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Benchmark only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-bench---workspace"><a class="option-anchor" href="#option-cargo-bench---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Benchmark all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-bench---all"><a class="option-anchor" href="#option-cargo-bench---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-bench---exclude"><a class="option-anchor" href="#option-cargo-bench---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo bench` will build the +following targets of the selected packages: + +- lib --- used to link with binaries and benchmarks +- bins (only if benchmark targets are built and required features are + available) +- lib as a benchmark +- bins as benchmarks +- benchmark targets + +The default behavior can be changed by setting the `bench` flag for the target +in the manifest settings. Setting examples to `bench = true` will build and +run the example as a benchmark. Setting targets to `bench = false` will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the `bench` flag and will always benchmark the given +target. + +Binary targets are automatically built if there is an integration test or +benchmark being selected to benchmark. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + +Passing target selection flags will benchmark only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-bench---lib"><a class="option-anchor" href="#option-cargo-bench---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Benchmark the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-bench---bin"><a class="option-anchor" href="#option-cargo-bench---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Benchmark the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-bench---bins"><a class="option-anchor" href="#option-cargo-bench---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Benchmark all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-bench---example"><a class="option-anchor" href="#option-cargo-bench---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Benchmark the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-bench---examples"><a class="option-anchor" href="#option-cargo-bench---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Benchmark all example targets.</dd> + + +<dt class="option-term" id="option-cargo-bench---test"><a class="option-anchor" href="#option-cargo-bench---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Benchmark the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-bench---tests"><a class="option-anchor" href="#option-cargo-bench---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Benchmark all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-bench---bench"><a class="option-anchor" href="#option-cargo-bench---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Benchmark the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-bench---benches"><a class="option-anchor" href="#option-cargo-bench---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Benchmark all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-bench---all-targets"><a class="option-anchor" href="#option-cargo-bench---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Benchmark all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-bench--F"><a class="option-anchor" href="#option-cargo-bench--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-bench---features"><a class="option-anchor" href="#option-cargo-bench---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-bench---all-features"><a class="option-anchor" href="#option-cargo-bench---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-bench---no-default-features"><a class="option-anchor" href="#option-cargo-bench---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-bench---target"><a class="option-anchor" href="#option-cargo-bench---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Benchmark for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-bench---profile"><a class="option-anchor" href="#option-cargo-bench---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Benchmark with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-bench---ignore-rust-version"><a class="option-anchor" href="#option-cargo-bench---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Benchmark the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-bench---timings=fmts"><a class="option-anchor" href="#option-cargo-bench---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-bench---target-dir"><a class="option-anchor" href="#option-cargo-bench---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g., for debugging) by +passing `--nocapture` to the benchmark binaries: + + cargo bench -- --nocapture + +<dl> + +<dt class="option-term" id="option-cargo-bench--v"><a class="option-anchor" href="#option-cargo-bench--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-bench---verbose"><a class="option-anchor" href="#option-cargo-bench---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-bench--q"><a class="option-anchor" href="#option-cargo-bench--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-bench---quiet"><a class="option-anchor" href="#option-cargo-bench---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-bench---color"><a class="option-anchor" href="#option-cargo-bench---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-bench---message-format"><a class="option-anchor" href="#option-cargo-bench---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-bench---manifest-path"><a class="option-anchor" href="#option-cargo-bench---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-bench---frozen"><a class="option-anchor" href="#option-cargo-bench---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-bench---locked"><a class="option-anchor" href="#option-cargo-bench---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-bench---offline"><a class="option-anchor" href="#option-cargo-bench---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-bench-+toolchain"><a class="option-anchor" href="#option-cargo-bench-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-bench---config"><a class="option-anchor" href="#option-cargo-bench---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-bench--C"><a class="option-anchor" href="#option-cargo-bench--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-bench--h"><a class="option-anchor" href="#option-cargo-bench--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-bench---help"><a class="option-anchor" href="#option-cargo-bench---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-bench--Z"><a class="option-anchor" href="#option-cargo-bench--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +The `--jobs` argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. + +<dl> +<dt class="option-term" id="option-cargo-bench--j"><a class="option-anchor" href="#option-cargo-bench--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-bench---jobs"><a class="option-anchor" href="#option-cargo-bench---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-bench---keep-going"><a class="option-anchor" href="#option-cargo-bench---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build and execute all the benchmarks of the current package: + + cargo bench + +2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-test(1)](cargo-test.html) diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md new file mode 100644 index 0000000..4d22f9d --- /dev/null +++ b/src/doc/src/commands/cargo-build.md @@ -0,0 +1,445 @@ +# cargo-build(1) + + + +## NAME + +cargo-build --- Compile the current package + +## SYNOPSIS + +`cargo build` [_options_] + +## DESCRIPTION + +Compile local packages and all of their dependencies. + +## OPTIONS + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-build--p"><a class="option-anchor" href="#option-cargo-build--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-build---package"><a class="option-anchor" href="#option-cargo-build---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Build only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-build---workspace"><a class="option-anchor" href="#option-cargo-build---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Build all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-build---all"><a class="option-anchor" href="#option-cargo-build---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-build---exclude"><a class="option-anchor" href="#option-cargo-build---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo build` will build all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + +Passing target selection flags will build only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-build---lib"><a class="option-anchor" href="#option-cargo-build---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Build the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-build---bin"><a class="option-anchor" href="#option-cargo-build---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-build---bins"><a class="option-anchor" href="#option-cargo-build---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Build all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-build---example"><a class="option-anchor" href="#option-cargo-build---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-build---examples"><a class="option-anchor" href="#option-cargo-build---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Build all example targets.</dd> + + +<dt class="option-term" id="option-cargo-build---test"><a class="option-anchor" href="#option-cargo-build---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-build---tests"><a class="option-anchor" href="#option-cargo-build---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Build all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-build---bench"><a class="option-anchor" href="#option-cargo-build---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-build---benches"><a class="option-anchor" href="#option-cargo-build---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Build all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-build---all-targets"><a class="option-anchor" href="#option-cargo-build---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Build all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-build--F"><a class="option-anchor" href="#option-cargo-build--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-build---features"><a class="option-anchor" href="#option-cargo-build---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-build---all-features"><a class="option-anchor" href="#option-cargo-build---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-build---no-default-features"><a class="option-anchor" href="#option-cargo-build---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-build---target"><a class="option-anchor" href="#option-cargo-build---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Build for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-build--r"><a class="option-anchor" href="#option-cargo-build--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-build---release"><a class="option-anchor" href="#option-cargo-build---release"></a><code>--release</code></dt> +<dd class="option-desc">Build optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-build---profile"><a class="option-anchor" href="#option-cargo-build---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Build with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-build---ignore-rust-version"><a class="option-anchor" href="#option-cargo-build---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-build---timings=fmts"><a class="option-anchor" href="#option-cargo-build---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-build---target-dir"><a class="option-anchor" href="#option-cargo-build---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-build---out-dir"><a class="option-anchor" href="#option-cargo-build---out-dir"></a><code>--out-dir</code> <em>directory</em></dt> +<dd class="option-desc">Copy final artifacts to this directory.</p> +<p>This option is unstable and available only on the +<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a> +and requires the <code>-Z unstable-options</code> flag to enable. +See <a href="https://github.com/rust-lang/cargo/issues/6790">https://github.com/rust-lang/cargo/issues/6790</a> for more information.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-build--v"><a class="option-anchor" href="#option-cargo-build--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-build---verbose"><a class="option-anchor" href="#option-cargo-build---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-build--q"><a class="option-anchor" href="#option-cargo-build--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-build---quiet"><a class="option-anchor" href="#option-cargo-build---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-build---color"><a class="option-anchor" href="#option-cargo-build---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-build---message-format"><a class="option-anchor" href="#option-cargo-build---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +<dt class="option-term" id="option-cargo-build---build-plan"><a class="option-anchor" href="#option-cargo-build---build-plan"></a><code>--build-plan</code></dt> +<dd class="option-desc">Outputs a series of JSON messages to stdout that indicate the commands to run +the build.</p> +<p>This option is unstable and available only on the +<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a> +and requires the <code>-Z unstable-options</code> flag to enable. +See <a href="https://github.com/rust-lang/cargo/issues/5579">https://github.com/rust-lang/cargo/issues/5579</a> for more information.</dd> + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-build---manifest-path"><a class="option-anchor" href="#option-cargo-build---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-build---frozen"><a class="option-anchor" href="#option-cargo-build---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-build---locked"><a class="option-anchor" href="#option-cargo-build---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-build---offline"><a class="option-anchor" href="#option-cargo-build---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-build-+toolchain"><a class="option-anchor" href="#option-cargo-build-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-build---config"><a class="option-anchor" href="#option-cargo-build---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-build--C"><a class="option-anchor" href="#option-cargo-build--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-build--h"><a class="option-anchor" href="#option-cargo-build--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-build---help"><a class="option-anchor" href="#option-cargo-build---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-build--Z"><a class="option-anchor" href="#option-cargo-build--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-build--j"><a class="option-anchor" href="#option-cargo-build--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-build---jobs"><a class="option-anchor" href="#option-cargo-build---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-build---keep-going"><a class="option-anchor" href="#option-cargo-build---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +<dt class="option-term" id="option-cargo-build---future-incompat-report"><a class="option-anchor" href="#option-cargo-build---future-incompat-report"></a><code>--future-incompat-report</code></dt> +<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command</p> +<p>See <a href="cargo-report.html">cargo-report(1)</a></dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build the local package and all of its dependencies: + + cargo build + +2. Build with optimizations: + + cargo build --release + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-rustc(1)](cargo-rustc.html) diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md new file mode 100644 index 0000000..2d10af8 --- /dev/null +++ b/src/doc/src/commands/cargo-check.md @@ -0,0 +1,426 @@ +# cargo-check(1) + + + +## NAME + +cargo-check --- Check the current package + +## SYNOPSIS + +`cargo check` [_options_] + +## DESCRIPTION + +Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running `cargo build`. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. Some diagnostics and errors are only emitted during code +generation, so they inherently won't be reported with `cargo check`. + +## OPTIONS + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-check--p"><a class="option-anchor" href="#option-cargo-check--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-check---package"><a class="option-anchor" href="#option-cargo-check---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Check only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-check---workspace"><a class="option-anchor" href="#option-cargo-check---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Check all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-check---all"><a class="option-anchor" href="#option-cargo-check---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-check---exclude"><a class="option-anchor" href="#option-cargo-check---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo check` will check all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +Passing target selection flags will check only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-check---lib"><a class="option-anchor" href="#option-cargo-check---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Check the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-check---bin"><a class="option-anchor" href="#option-cargo-check---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Check the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-check---bins"><a class="option-anchor" href="#option-cargo-check---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Check all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-check---example"><a class="option-anchor" href="#option-cargo-check---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Check the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-check---examples"><a class="option-anchor" href="#option-cargo-check---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Check all example targets.</dd> + + +<dt class="option-term" id="option-cargo-check---test"><a class="option-anchor" href="#option-cargo-check---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Check the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-check---tests"><a class="option-anchor" href="#option-cargo-check---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Check all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-check---bench"><a class="option-anchor" href="#option-cargo-check---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Check the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-check---benches"><a class="option-anchor" href="#option-cargo-check---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Check all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-check---all-targets"><a class="option-anchor" href="#option-cargo-check---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Check all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-check--F"><a class="option-anchor" href="#option-cargo-check--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-check---features"><a class="option-anchor" href="#option-cargo-check---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-check---all-features"><a class="option-anchor" href="#option-cargo-check---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-check---no-default-features"><a class="option-anchor" href="#option-cargo-check---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-check---target"><a class="option-anchor" href="#option-cargo-check---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Check for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-check--r"><a class="option-anchor" href="#option-cargo-check--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-check---release"><a class="option-anchor" href="#option-cargo-check---release"></a><code>--release</code></dt> +<dd class="option-desc">Check optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-check---profile"><a class="option-anchor" href="#option-cargo-check---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Check with the given profile.</p> +<p>As a special case, specifying the <code>test</code> profile will also enable checking in +test mode which will enable checking tests and enable the <code>test</code> cfg option. +See <a href="https://doc.rust-lang.org/rustc/tests/index.html">rustc tests</a> for more +detail.</p> +<p>See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-check---ignore-rust-version"><a class="option-anchor" href="#option-cargo-check---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Check the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-check---timings=fmts"><a class="option-anchor" href="#option-cargo-check---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-check---target-dir"><a class="option-anchor" href="#option-cargo-check---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-check--v"><a class="option-anchor" href="#option-cargo-check--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-check---verbose"><a class="option-anchor" href="#option-cargo-check---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-check--q"><a class="option-anchor" href="#option-cargo-check--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-check---quiet"><a class="option-anchor" href="#option-cargo-check---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-check---color"><a class="option-anchor" href="#option-cargo-check---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-check---message-format"><a class="option-anchor" href="#option-cargo-check---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-check---manifest-path"><a class="option-anchor" href="#option-cargo-check---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-check---frozen"><a class="option-anchor" href="#option-cargo-check---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-check---locked"><a class="option-anchor" href="#option-cargo-check---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-check---offline"><a class="option-anchor" href="#option-cargo-check---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-check-+toolchain"><a class="option-anchor" href="#option-cargo-check-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-check---config"><a class="option-anchor" href="#option-cargo-check---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-check--C"><a class="option-anchor" href="#option-cargo-check--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-check--h"><a class="option-anchor" href="#option-cargo-check--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-check---help"><a class="option-anchor" href="#option-cargo-check---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-check--Z"><a class="option-anchor" href="#option-cargo-check--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-check--j"><a class="option-anchor" href="#option-cargo-check--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-check---jobs"><a class="option-anchor" href="#option-cargo-check---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-check---keep-going"><a class="option-anchor" href="#option-cargo-check---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +<dt class="option-term" id="option-cargo-check---future-incompat-report"><a class="option-anchor" href="#option-cargo-check---future-incompat-report"></a><code>--future-incompat-report</code></dt> +<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command</p> +<p>See <a href="cargo-report.html">cargo-report(1)</a></dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Check the local package for errors: + + cargo check + +2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md new file mode 100644 index 0000000..683d539 --- /dev/null +++ b/src/doc/src/commands/cargo-clean.md @@ -0,0 +1,204 @@ +# cargo-clean(1) + + + +## NAME + +cargo-clean --- Remove generated artifacts + +## SYNOPSIS + +`cargo clean` [_options_] + +## DESCRIPTION + +Remove artifacts from the target directory that Cargo has generated in the +past. + +With no options, `cargo clean` will delete the entire target directory. + +## OPTIONS + +### Package Selection + +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. + +<dl> +<dt class="option-term" id="option-cargo-clean--p"><a class="option-anchor" href="#option-cargo-clean--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-clean---package"><a class="option-anchor" href="#option-cargo-clean---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Clean only the specified packages. This flag may be specified +multiple times. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC format.</dd> + +</dl> + +### Clean Options + +<dl> + +<dt class="option-term" id="option-cargo-clean---doc"><a class="option-anchor" href="#option-cargo-clean---doc"></a><code>--doc</code></dt> +<dd class="option-desc">This option will cause <code>cargo clean</code> to remove only the <code>doc</code> directory in +the target directory.</dd> + + +<dt class="option-term" id="option-cargo-clean---release"><a class="option-anchor" href="#option-cargo-clean---release"></a><code>--release</code></dt> +<dd class="option-desc">Remove all artifacts in the <code>release</code> directory.</dd> + + +<dt class="option-term" id="option-cargo-clean---profile"><a class="option-anchor" href="#option-cargo-clean---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Remove all artifacts in the directory with the given profile name.</dd> + + +<dt class="option-term" id="option-cargo-clean---target-dir"><a class="option-anchor" href="#option-cargo-clean---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-clean---target"><a class="option-anchor" href="#option-cargo-clean---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Clean for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-clean--v"><a class="option-anchor" href="#option-cargo-clean--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-clean---verbose"><a class="option-anchor" href="#option-cargo-clean---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-clean--q"><a class="option-anchor" href="#option-cargo-clean--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-clean---quiet"><a class="option-anchor" href="#option-cargo-clean---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-clean---color"><a class="option-anchor" href="#option-cargo-clean---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-clean---manifest-path"><a class="option-anchor" href="#option-cargo-clean---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-clean---frozen"><a class="option-anchor" href="#option-cargo-clean---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-clean---locked"><a class="option-anchor" href="#option-cargo-clean---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-clean---offline"><a class="option-anchor" href="#option-cargo-clean---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-clean-+toolchain"><a class="option-anchor" href="#option-cargo-clean-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-clean---config"><a class="option-anchor" href="#option-cargo-clean---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-clean--C"><a class="option-anchor" href="#option-cargo-clean--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-clean--h"><a class="option-anchor" href="#option-cargo-clean--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-clean---help"><a class="option-anchor" href="#option-cargo-clean---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-clean--Z"><a class="option-anchor" href="#option-cargo-clean--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Remove the entire target directory: + + cargo clean + +2. Remove only the release artifacts: + + cargo clean --release + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md new file mode 100644 index 0000000..e20366e --- /dev/null +++ b/src/doc/src/commands/cargo-doc.md @@ -0,0 +1,391 @@ +# cargo-doc(1) + + + +## NAME + +cargo-doc --- Build a package's documentation + +## SYNOPSIS + +`cargo doc` [_options_] + +## DESCRIPTION + +Build the documentation for the local package and all dependencies. The output +is placed in `target/doc` in rustdoc's usual format. + +## OPTIONS + +### Documentation Options + +<dl> + +<dt class="option-term" id="option-cargo-doc---open"><a class="option-anchor" href="#option-cargo-doc---open"></a><code>--open</code></dt> +<dd class="option-desc">Open the docs in a browser after building them. This will use your default +browser unless you define another one in the <code>BROWSER</code> environment variable +or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration +option.</dd> + + +<dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt> +<dd class="option-desc">Do not build documentation for dependencies.</dd> + + +<dt class="option-term" id="option-cargo-doc---document-private-items"><a class="option-anchor" href="#option-cargo-doc---document-private-items"></a><code>--document-private-items</code></dt> +<dd class="option-desc">Include non-public items in the documentation. This will be enabled by default if documenting a binary target.</dd> + + +</dl> + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-doc--p"><a class="option-anchor" href="#option-cargo-doc--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-doc---package"><a class="option-anchor" href="#option-cargo-doc---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Document only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-doc---workspace"><a class="option-anchor" href="#option-cargo-doc---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Document all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-doc---all"><a class="option-anchor" href="#option-cargo-doc---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-doc---exclude"><a class="option-anchor" href="#option-cargo-doc---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo doc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +The default behavior can be changed by setting `doc = false` for the target in +the manifest settings. Using target selection options will ignore the `doc` +flag and will always document the given target. + +<dl> +<dt class="option-term" id="option-cargo-doc---lib"><a class="option-anchor" href="#option-cargo-doc---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Document the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-doc---bin"><a class="option-anchor" href="#option-cargo-doc---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-doc---bins"><a class="option-anchor" href="#option-cargo-doc---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Document all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-doc---example"><a class="option-anchor" href="#option-cargo-doc---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-doc---examples"><a class="option-anchor" href="#option-cargo-doc---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Document all example targets.</dd> + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-doc--F"><a class="option-anchor" href="#option-cargo-doc--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-doc---features"><a class="option-anchor" href="#option-cargo-doc---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-doc---all-features"><a class="option-anchor" href="#option-cargo-doc---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-doc---no-default-features"><a class="option-anchor" href="#option-cargo-doc---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-doc---target"><a class="option-anchor" href="#option-cargo-doc---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Document for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-doc--r"><a class="option-anchor" href="#option-cargo-doc--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-doc---release"><a class="option-anchor" href="#option-cargo-doc---release"></a><code>--release</code></dt> +<dd class="option-desc">Document optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-doc---profile"><a class="option-anchor" href="#option-cargo-doc---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Document with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-doc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-doc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-doc---timings=fmts"><a class="option-anchor" href="#option-cargo-doc---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-doc---target-dir"><a class="option-anchor" href="#option-cargo-doc---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-doc--v"><a class="option-anchor" href="#option-cargo-doc--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-doc---verbose"><a class="option-anchor" href="#option-cargo-doc---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-doc--q"><a class="option-anchor" href="#option-cargo-doc--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-doc---quiet"><a class="option-anchor" href="#option-cargo-doc---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-doc---color"><a class="option-anchor" href="#option-cargo-doc---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-doc---message-format"><a class="option-anchor" href="#option-cargo-doc---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-doc---manifest-path"><a class="option-anchor" href="#option-cargo-doc---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-doc---frozen"><a class="option-anchor" href="#option-cargo-doc---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-doc---locked"><a class="option-anchor" href="#option-cargo-doc---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-doc---offline"><a class="option-anchor" href="#option-cargo-doc---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-doc-+toolchain"><a class="option-anchor" href="#option-cargo-doc-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-doc---config"><a class="option-anchor" href="#option-cargo-doc---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-doc--C"><a class="option-anchor" href="#option-cargo-doc--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-doc--h"><a class="option-anchor" href="#option-cargo-doc--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-doc---help"><a class="option-anchor" href="#option-cargo-doc---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-doc--Z"><a class="option-anchor" href="#option-cargo-doc--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-doc--j"><a class="option-anchor" href="#option-cargo-doc--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-doc---jobs"><a class="option-anchor" href="#option-cargo-doc---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-doc---keep-going"><a class="option-anchor" href="#option-cargo-doc---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build the local package documentation and its dependencies and output to + `target/doc`. + + cargo doc + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-rustdoc(1)](cargo-rustdoc.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md new file mode 100644 index 0000000..2b4c175 --- /dev/null +++ b/src/doc/src/commands/cargo-fetch.md @@ -0,0 +1,174 @@ +# cargo-fetch(1) + + + + +## NAME + +cargo-fetch --- Fetch dependencies of a package from the network + +## SYNOPSIS + +`cargo fetch` [_options_] + +## DESCRIPTION + +If a `Cargo.lock` file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands will be able to run offline after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch) +plugin which adds a command to download popular crates. This may be useful if +you plan to use Cargo without a network with the `--offline` flag. + +## OPTIONS + +### Fetch options + +<dl> +<dt class="option-term" id="option-cargo-fetch---target"><a class="option-anchor" href="#option-cargo-fetch---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Fetch for the given architecture. The default is all architectures. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-fetch--v"><a class="option-anchor" href="#option-cargo-fetch--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-fetch---verbose"><a class="option-anchor" href="#option-cargo-fetch---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-fetch--q"><a class="option-anchor" href="#option-cargo-fetch--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-fetch---quiet"><a class="option-anchor" href="#option-cargo-fetch---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-fetch---color"><a class="option-anchor" href="#option-cargo-fetch---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-fetch---manifest-path"><a class="option-anchor" href="#option-cargo-fetch---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-fetch---frozen"><a class="option-anchor" href="#option-cargo-fetch---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-fetch---locked"><a class="option-anchor" href="#option-cargo-fetch---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-fetch---offline"><a class="option-anchor" href="#option-cargo-fetch---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-fetch-+toolchain"><a class="option-anchor" href="#option-cargo-fetch-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-fetch---config"><a class="option-anchor" href="#option-cargo-fetch---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-fetch--C"><a class="option-anchor" href="#option-cargo-fetch--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-fetch--h"><a class="option-anchor" href="#option-cargo-fetch--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-fetch---help"><a class="option-anchor" href="#option-cargo-fetch---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-fetch--Z"><a class="option-anchor" href="#option-cargo-fetch--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Fetch all dependencies: + + cargo fetch + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-update(1)](cargo-update.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html) diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md new file mode 100644 index 0000000..2545a29 --- /dev/null +++ b/src/doc/src/commands/cargo-fix.md @@ -0,0 +1,504 @@ +# cargo-fix(1) + + + +## NAME + +cargo-fix --- Automatically fix lint warnings reported by rustc + +## SYNOPSIS + +`cargo fix` [_options_] + +## DESCRIPTION + +This Cargo subcommand will automatically take rustc's suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! + +Executing `cargo fix` will under the hood execute [cargo-check(1)](cargo-check.html). Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you'd like to apply all fixes to the current package, you can run: + + cargo fix + +which behaves the same as `cargo check --all-targets`. + +`cargo fix` is only capable of fixing code that is normally compiled with +`cargo check`. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: + + cargo fix --features foo + +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. + + cargo fix --target x86_64-pc-windows-gnu + +If you encounter any problems with `cargo fix` or otherwise have any questions +or feature requests please don't hesitate to file an issue at +<https://github.com/rust-lang/cargo>. + +### Edition migration + +The `cargo fix` subcommand can also be used to migrate a package from one +[edition] to the next. The general procedure is: + +1. Run `cargo fix --edition`. Consider also using the `--all-features` flag if + your project has multiple features. You may also want to run `cargo fix + --edition` multiple times with different `--target` flags if your project + has platform-specific code gated by `cfg` attributes. +2. Modify `Cargo.toml` to set the [edition field] to the new edition. +3. Run your project tests to verify that everything still works. If new + warnings are issued, you may want to consider running `cargo fix` again + (without the `--edition` flag) to apply any suggestions given by the + compiler. + +And hopefully that's it! Just keep in mind of the caveats mentioned above that +`cargo fix` cannot update code for inactive features or `cfg` expressions. +Also, in some rare cases the compiler is unable to automatically migrate all +code to the new edition, and this may require manual changes after building +with the new edition. + +[edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html +[edition field]: ../reference/manifest.html#the-edition-field + +## OPTIONS + +### Fix options + +<dl> + +<dt class="option-term" id="option-cargo-fix---broken-code"><a class="option-anchor" href="#option-cargo-fix---broken-code"></a><code>--broken-code</code></dt> +<dd class="option-desc">Fix code even if it already has compiler errors. This is useful if <code>cargo fix</code> +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix.</dd> + + +<dt class="option-term" id="option-cargo-fix---edition"><a class="option-anchor" href="#option-cargo-fix---edition"></a><code>--edition</code></dt> +<dd class="option-desc">Apply changes that will update the code to the next edition. This will not +update the edition in the <code>Cargo.toml</code> manifest, which must be updated +manually after <code>cargo fix --edition</code> has finished.</dd> + + +<dt class="option-term" id="option-cargo-fix---edition-idioms"><a class="option-anchor" href="#option-cargo-fix---edition-idioms"></a><code>--edition-idioms</code></dt> +<dd class="option-desc">Apply suggestions that will update code to the preferred style for the current +edition.</dd> + + +<dt class="option-term" id="option-cargo-fix---allow-no-vcs"><a class="option-anchor" href="#option-cargo-fix---allow-no-vcs"></a><code>--allow-no-vcs</code></dt> +<dd class="option-desc">Fix code even if a VCS was not detected.</dd> + + +<dt class="option-term" id="option-cargo-fix---allow-dirty"><a class="option-anchor" href="#option-cargo-fix---allow-dirty"></a><code>--allow-dirty</code></dt> +<dd class="option-desc">Fix code even if the working directory has changes.</dd> + + +<dt class="option-term" id="option-cargo-fix---allow-staged"><a class="option-anchor" href="#option-cargo-fix---allow-staged"></a><code>--allow-staged</code></dt> +<dd class="option-desc">Fix code even if the working directory has staged changes.</dd> + + +</dl> + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-fix--p"><a class="option-anchor" href="#option-cargo-fix--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-fix---package"><a class="option-anchor" href="#option-cargo-fix---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Fix only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-fix---workspace"><a class="option-anchor" href="#option-cargo-fix---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Fix all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-fix---all"><a class="option-anchor" href="#option-cargo-fix---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-fix---exclude"><a class="option-anchor" href="#option-cargo-fix---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo fix` will fix all targets +(`--all-targets` implied). Binaries are skipped if they have +`required-features` that are missing. + +Passing target selection flags will fix only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-fix---lib"><a class="option-anchor" href="#option-cargo-fix---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Fix the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-fix---bin"><a class="option-anchor" href="#option-cargo-fix---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Fix the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-fix---bins"><a class="option-anchor" href="#option-cargo-fix---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Fix all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-fix---example"><a class="option-anchor" href="#option-cargo-fix---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Fix the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-fix---examples"><a class="option-anchor" href="#option-cargo-fix---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Fix all example targets.</dd> + + +<dt class="option-term" id="option-cargo-fix---test"><a class="option-anchor" href="#option-cargo-fix---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Fix the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-fix---tests"><a class="option-anchor" href="#option-cargo-fix---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Fix all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-fix---bench"><a class="option-anchor" href="#option-cargo-fix---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Fix the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-fix---benches"><a class="option-anchor" href="#option-cargo-fix---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Fix all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-fix---all-targets"><a class="option-anchor" href="#option-cargo-fix---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Fix all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-fix--F"><a class="option-anchor" href="#option-cargo-fix--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-fix---features"><a class="option-anchor" href="#option-cargo-fix---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-fix---all-features"><a class="option-anchor" href="#option-cargo-fix---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-fix---no-default-features"><a class="option-anchor" href="#option-cargo-fix---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-fix---target"><a class="option-anchor" href="#option-cargo-fix---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Fix for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-fix--r"><a class="option-anchor" href="#option-cargo-fix--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-fix---release"><a class="option-anchor" href="#option-cargo-fix---release"></a><code>--release</code></dt> +<dd class="option-desc">Fix optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-fix---profile"><a class="option-anchor" href="#option-cargo-fix---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Fix with the given profile.</p> +<p>As a special case, specifying the <code>test</code> profile will also enable checking in +test mode which will enable checking tests and enable the <code>test</code> cfg option. +See <a href="https://doc.rust-lang.org/rustc/tests/index.html">rustc tests</a> for more +detail.</p> +<p>See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-fix---ignore-rust-version"><a class="option-anchor" href="#option-cargo-fix---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Fix the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-fix---timings=fmts"><a class="option-anchor" href="#option-cargo-fix---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-fix---target-dir"><a class="option-anchor" href="#option-cargo-fix---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-fix--v"><a class="option-anchor" href="#option-cargo-fix--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-fix---verbose"><a class="option-anchor" href="#option-cargo-fix---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-fix--q"><a class="option-anchor" href="#option-cargo-fix--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-fix---quiet"><a class="option-anchor" href="#option-cargo-fix---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-fix---color"><a class="option-anchor" href="#option-cargo-fix---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-fix---message-format"><a class="option-anchor" href="#option-cargo-fix---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-fix---manifest-path"><a class="option-anchor" href="#option-cargo-fix---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-fix---frozen"><a class="option-anchor" href="#option-cargo-fix---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-fix---locked"><a class="option-anchor" href="#option-cargo-fix---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-fix---offline"><a class="option-anchor" href="#option-cargo-fix---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-fix-+toolchain"><a class="option-anchor" href="#option-cargo-fix-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-fix---config"><a class="option-anchor" href="#option-cargo-fix---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-fix--C"><a class="option-anchor" href="#option-cargo-fix--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-fix--h"><a class="option-anchor" href="#option-cargo-fix--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-fix---help"><a class="option-anchor" href="#option-cargo-fix---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-fix--Z"><a class="option-anchor" href="#option-cargo-fix--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-fix--j"><a class="option-anchor" href="#option-cargo-fix--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-fix---jobs"><a class="option-anchor" href="#option-cargo-fix---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-fix---keep-going"><a class="option-anchor" href="#option-cargo-fix---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Apply compiler suggestions to the local package: + + cargo fix + +2. Update a package to prepare it for the next edition: + + cargo fix --edition + +3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-check(1)](cargo-check.html) diff --git a/src/doc/src/commands/cargo-generate-lockfile.md b/src/doc/src/commands/cargo-generate-lockfile.md new file mode 100644 index 0000000..0d5633f --- /dev/null +++ b/src/doc/src/commands/cargo-generate-lockfile.md @@ -0,0 +1,148 @@ +# cargo-generate-lockfile(1) + +## NAME + +cargo-generate-lockfile --- Generate the lockfile for a package + +## SYNOPSIS + +`cargo generate-lockfile` [_options_] + +## DESCRIPTION + +This command will create the `Cargo.lock` lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt with the latest +available version of every package. + +See also [cargo-update(1)](cargo-update.html) which is also capable of creating a `Cargo.lock` +lockfile and has more options for controlling update behavior. + +## OPTIONS + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-generate-lockfile--v"><a class="option-anchor" href="#option-cargo-generate-lockfile--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-generate-lockfile---verbose"><a class="option-anchor" href="#option-cargo-generate-lockfile---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile--q"><a class="option-anchor" href="#option-cargo-generate-lockfile--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-generate-lockfile---quiet"><a class="option-anchor" href="#option-cargo-generate-lockfile---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile---color"><a class="option-anchor" href="#option-cargo-generate-lockfile---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-generate-lockfile---manifest-path"><a class="option-anchor" href="#option-cargo-generate-lockfile---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-generate-lockfile---frozen"><a class="option-anchor" href="#option-cargo-generate-lockfile---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-generate-lockfile---locked"><a class="option-anchor" href="#option-cargo-generate-lockfile---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile---offline"><a class="option-anchor" href="#option-cargo-generate-lockfile---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-generate-lockfile-+toolchain"><a class="option-anchor" href="#option-cargo-generate-lockfile-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile---config"><a class="option-anchor" href="#option-cargo-generate-lockfile---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile--C"><a class="option-anchor" href="#option-cargo-generate-lockfile--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile--h"><a class="option-anchor" href="#option-cargo-generate-lockfile--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-generate-lockfile---help"><a class="option-anchor" href="#option-cargo-generate-lockfile---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-generate-lockfile--Z"><a class="option-anchor" href="#option-cargo-generate-lockfile--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-update(1)](cargo-update.html) diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md new file mode 100644 index 0000000..db5cb34 --- /dev/null +++ b/src/doc/src/commands/cargo-help.md @@ -0,0 +1,26 @@ +# cargo-help(1) + +## NAME + +cargo-help --- Get help for a Cargo command + +## SYNOPSIS + +`cargo help` [_subcommand_] + +## DESCRIPTION + +Prints a help message for the given command. + +## EXAMPLES + +1. Get help for a command: + + cargo help build + +2. Help is also available with the `--help` flag: + + cargo build --help + +## SEE ALSO +[cargo(1)](cargo.html) diff --git a/src/doc/src/commands/cargo-init.md b/src/doc/src/commands/cargo-init.md new file mode 100644 index 0000000..414e08a --- /dev/null +++ b/src/doc/src/commands/cargo-init.md @@ -0,0 +1,161 @@ +# cargo-init(1) + +## NAME + +cargo-init --- Create a new Cargo package in an existing directory + +## SYNOPSIS + +`cargo init` [_options_] [_path_] + +## DESCRIPTION + +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +See [cargo-new(1)](cargo-new.html) for a similar command which will create a new package in +a new directory. + +## OPTIONS + +### Init Options + +<dl> + +<dt class="option-term" id="option-cargo-init---bin"><a class="option-anchor" href="#option-cargo-init---bin"></a><code>--bin</code></dt> +<dd class="option-desc">Create a package with a binary target (<code>src/main.rs</code>). +This is the default behavior.</dd> + + +<dt class="option-term" id="option-cargo-init---lib"><a class="option-anchor" href="#option-cargo-init---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Create a package with a library target (<code>src/lib.rs</code>).</dd> + + +<dt class="option-term" id="option-cargo-init---edition"><a class="option-anchor" href="#option-cargo-init---edition"></a><code>--edition</code> <em>edition</em></dt> +<dd class="option-desc">Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021</dd> + + +<dt class="option-term" id="option-cargo-init---name"><a class="option-anchor" href="#option-cargo-init---name"></a><code>--name</code> <em>name</em></dt> +<dd class="option-desc">Set the package name. Defaults to the directory name.</dd> + + +<dt class="option-term" id="option-cargo-init---vcs"><a class="option-anchor" href="#option-cargo-init---vcs"></a><code>--vcs</code> <em>vcs</em></dt> +<dd class="option-desc">Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to <code>git</code> or the configuration value +<code>cargo-new.vcs</code>, or <code>none</code> if already inside a VCS repository.</dd> + + +<dt class="option-term" id="option-cargo-init---registry"><a class="option-anchor" href="#option-cargo-init---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name +which will restrict publishing only to that registry.</p> +<p>Registry names are defined in <a href="../reference/config.html">Cargo config files</a>. +If not specified, the default registry defined by the <code>registry.default</code> +config key is used. If the default registry is not set and <code>--registry</code> is not +used, the <code>publish</code> field will not be set which means that publishing will not +be restricted.</dd> + + +</dl> + + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-init--v"><a class="option-anchor" href="#option-cargo-init--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-init---verbose"><a class="option-anchor" href="#option-cargo-init---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-init--q"><a class="option-anchor" href="#option-cargo-init--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-init---quiet"><a class="option-anchor" href="#option-cargo-init---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-init---color"><a class="option-anchor" href="#option-cargo-init---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-init-+toolchain"><a class="option-anchor" href="#option-cargo-init-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-init---config"><a class="option-anchor" href="#option-cargo-init---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-init--C"><a class="option-anchor" href="#option-cargo-init--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-init--h"><a class="option-anchor" href="#option-cargo-init--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-init---help"><a class="option-anchor" href="#option-cargo-init---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-init--Z"><a class="option-anchor" href="#option-cargo-init--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a binary Cargo package in the current directory: + + cargo init + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-new(1)](cargo-new.html) diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md new file mode 100644 index 0000000..af5f03c --- /dev/null +++ b/src/doc/src/commands/cargo-install.md @@ -0,0 +1,445 @@ +# cargo-install(1) + + + +## NAME + +cargo-install --- Build and install a Rust binary + +## SYNOPSIS + +`cargo install` [_options_] _crate_[@_version_]...\ +`cargo install` [_options_] `--path` _path_\ +`cargo install` [_options_] `--git` _url_ [_crate_...]\ +`cargo install` [_options_] `--list` + +## DESCRIPTION + +This command manages Cargo's local set of installed binary crates. Only +packages which have executable `[[bin]]` or `[[example]]` targets can be +installed, and all executables are installed into the installation root's +`bin` folder. + +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` + + +There are multiple sources from which a crate can be installed. The default +location is crates.io but the `--git`, `--path`, and `--registry` flags can +change this source. If the source contains more than one package (such as +crates.io or a git repository with multiple crates) the _crate_ argument is +required to indicate which crate should be installed. + +Crates from crates.io can optionally specify the version they wish to install +via the `--version` flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the `--bin` argument can selectively install only +one of them, and if you'd rather install examples the `--example` argument can +be used as well. + +If the package is already installed, Cargo will reinstall it if the installed +version does not appear to be up-to-date. If any of the following values +change, then Cargo will reinstall the package: + +- The package version and source. +- The set of binary names installed. +- The chosen features. +- The profile (`--profile`). +- The target (`--target`). + +Installing with `--path` will always build and install, unless there are +conflicting binaries from another package. The `--force` flag may be used to +force Cargo to always reinstall the package. + +If the source is crates.io or `--git` then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the `CARGO_TARGET_DIR` environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. + +### Dealing with the Lockfile + +By default, the `Cargo.lock` file that is included with the package will be +ignored. This means that Cargo will recompute which versions of dependencies +to use, possibly using newer versions that have been released since the +package was published. The `--locked` flag can be used to force Cargo to use +the packaged `Cargo.lock` file if it is available. This may be useful for +ensuring reproducible builds, to use the exact same set of dependencies that +were available when the package was published. It may also be useful if a +newer version of a dependency is published that no longer builds on your +system, or has other problems. The downside to using `--locked` is that you +will not receive any fixes or updates to any dependency. Note that Cargo did +not start publishing `Cargo.lock` files until version 1.37, which means +packages published with prior versions will not have a `Cargo.lock` file +available. + +### Configuration Discovery + +This command operates on system or user level, not project level. +This means that the local [configuration discovery] is ignored. +Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`. +If the package is installed with `--path $PATH`, the local configuration +will be used, beginning discovery at `$PATH/.cargo/config.toml`. + +[configuration discovery]: ../reference/config.html#hierarchical-structure + +## OPTIONS + +### Install Options + +<dl> + +<dt class="option-term" id="option-cargo-install---vers"><a class="option-anchor" href="#option-cargo-install---vers"></a><code>--vers</code> <em>version</em></dt> +<dt class="option-term" id="option-cargo-install---version"><a class="option-anchor" href="#option-cargo-install---version"></a><code>--version</code> <em>version</em></dt> +<dd class="option-desc">Specify a version to install. This may be a <a href="../reference/specifying-dependencies.md">version +requirement</a>, like <code>~1.2</code>, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as <code>^</code> or <code>~</code>), then it must be in the form +<em>MAJOR.MINOR.PATCH</em>, and will install exactly that version; it is <em>not</em> +treated as a caret requirement like Cargo dependencies are.</dd> + + +<dt class="option-term" id="option-cargo-install---git"><a class="option-anchor" href="#option-cargo-install---git"></a><code>--git</code> <em>url</em></dt> +<dd class="option-desc">Git URL to install the specified crate from.</dd> + + +<dt class="option-term" id="option-cargo-install---branch"><a class="option-anchor" href="#option-cargo-install---branch"></a><code>--branch</code> <em>branch</em></dt> +<dd class="option-desc">Branch to use when installing from git.</dd> + + +<dt class="option-term" id="option-cargo-install---tag"><a class="option-anchor" href="#option-cargo-install---tag"></a><code>--tag</code> <em>tag</em></dt> +<dd class="option-desc">Tag to use when installing from git.</dd> + + +<dt class="option-term" id="option-cargo-install---rev"><a class="option-anchor" href="#option-cargo-install---rev"></a><code>--rev</code> <em>sha</em></dt> +<dd class="option-desc">Specific commit to use when installing from git.</dd> + + +<dt class="option-term" id="option-cargo-install---path"><a class="option-anchor" href="#option-cargo-install---path"></a><code>--path</code> <em>path</em></dt> +<dd class="option-desc">Filesystem path to local crate to install.</dd> + + +<dt class="option-term" id="option-cargo-install---list"><a class="option-anchor" href="#option-cargo-install---list"></a><code>--list</code></dt> +<dd class="option-desc">List all installed packages and their versions.</dd> + + +<dt class="option-term" id="option-cargo-install--f"><a class="option-anchor" href="#option-cargo-install--f"></a><code>-f</code></dt> +<dt class="option-term" id="option-cargo-install---force"><a class="option-anchor" href="#option-cargo-install---force"></a><code>--force</code></dt> +<dd class="option-desc">Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of <code>rustc</code>.</dd> + + +<dt class="option-term" id="option-cargo-install---no-track"><a class="option-anchor" href="#option-cargo-install---no-track"></a><code>--no-track</code></dt> +<dd class="option-desc">By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the <code>--force</code> flag is used. This also disables Cargo’s ability to +protect against multiple concurrent invocations of Cargo installing at the +same time.</dd> + + +<dt class="option-term" id="option-cargo-install---bin"><a class="option-anchor" href="#option-cargo-install---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Install only the specified binary.</dd> + + +<dt class="option-term" id="option-cargo-install---bins"><a class="option-anchor" href="#option-cargo-install---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Install all binaries.</dd> + + +<dt class="option-term" id="option-cargo-install---example"><a class="option-anchor" href="#option-cargo-install---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Install only the specified example.</dd> + + +<dt class="option-term" id="option-cargo-install---examples"><a class="option-anchor" href="#option-cargo-install---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Install all examples.</dd> + + +<dt class="option-term" id="option-cargo-install---root"><a class="option-anchor" href="#option-cargo-install---root"></a><code>--root</code> <em>dir</em></dt> +<dd class="option-desc">Directory to install packages into.</dd> + + +<dt class="option-term" id="option-cargo-install---registry"><a class="option-anchor" href="#option-cargo-install---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + + +<dt class="option-term" id="option-cargo-install---index"><a class="option-anchor" href="#option-cargo-install---index"></a><code>--index</code> <em>index</em></dt> +<dd class="option-desc">The URL of the registry index to use.</dd> + + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-install--F"><a class="option-anchor" href="#option-cargo-install--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-install---features"><a class="option-anchor" href="#option-cargo-install---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-install---all-features"><a class="option-anchor" href="#option-cargo-install---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-install---no-default-features"><a class="option-anchor" href="#option-cargo-install---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-install---target"><a class="option-anchor" href="#option-cargo-install---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Install for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-install---target-dir"><a class="option-anchor" href="#option-cargo-install---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to a new temporary folder located in the +temporary directory of the platform. </p> +<p>When using <code>--path</code>, by default it will use <code>target</code> directory in the workspace +of the local crate unless <code>--target-dir</code> +is specified.</dd> + + + +<dt class="option-term" id="option-cargo-install---debug"><a class="option-anchor" href="#option-cargo-install---debug"></a><code>--debug</code></dt> +<dd class="option-desc">Build with the <code>dev</code> profile instead the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + +<dt class="option-term" id="option-cargo-install---profile"><a class="option-anchor" href="#option-cargo-install---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Install with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-install---timings=fmts"><a class="option-anchor" href="#option-cargo-install---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-install---frozen"><a class="option-anchor" href="#option-cargo-install---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-install---locked"><a class="option-anchor" href="#option-cargo-install---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-install---offline"><a class="option-anchor" href="#option-cargo-install---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-install--j"><a class="option-anchor" href="#option-cargo-install--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-install---jobs"><a class="option-anchor" href="#option-cargo-install---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-install---keep-going"><a class="option-anchor" href="#option-cargo-install---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-install--v"><a class="option-anchor" href="#option-cargo-install--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-install---verbose"><a class="option-anchor" href="#option-cargo-install---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-install--q"><a class="option-anchor" href="#option-cargo-install--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-install---quiet"><a class="option-anchor" href="#option-cargo-install---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-install---color"><a class="option-anchor" href="#option-cargo-install---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-install---message-format"><a class="option-anchor" href="#option-cargo-install---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-install-+toolchain"><a class="option-anchor" href="#option-cargo-install-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-install---config"><a class="option-anchor" href="#option-cargo-install---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-install--C"><a class="option-anchor" href="#option-cargo-install--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-install--h"><a class="option-anchor" href="#option-cargo-install--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-install---help"><a class="option-anchor" href="#option-cargo-install---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-install--Z"><a class="option-anchor" href="#option-cargo-install--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Install or upgrade a package from crates.io: + + cargo install ripgrep + +2. Install or reinstall the package in the current directory: + + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-uninstall(1)](cargo-uninstall.html), [cargo-search(1)](cargo-search.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo-locate-project.md b/src/doc/src/commands/cargo-locate-project.md new file mode 100644 index 0000000..44152ee --- /dev/null +++ b/src/doc/src/commands/cargo-locate-project.md @@ -0,0 +1,143 @@ +# cargo-locate-project(1) + +## NAME + +cargo-locate-project --- Print a JSON representation of a Cargo.toml file's location + +## SYNOPSIS + +`cargo locate-project` [_options_] + +## DESCRIPTION + +This command will print a JSON object to stdout with the full path to the manifest. The +manifest is found by searching upward for a file named `Cargo.toml` starting from the current +working directory. + +If the project happens to be a part of a workspace, the manifest of the project, rather than +the workspace root, is output. This can be overridden by the `--workspace` flag. The root +workspace is found by traversing further upward or by using the field `package.workspace` after +locating the manifest of a workspace member. + +## OPTIONS + +<dl> + +<dt class="option-term" id="option-cargo-locate-project---workspace"><a class="option-anchor" href="#option-cargo-locate-project---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Locate the <code>Cargo.toml</code> at the root of the workspace, as opposed to the current +workspace member.</dd> + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-locate-project---message-format"><a class="option-anchor" href="#option-cargo-locate-project---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The representation in which to print the project location. Valid values:</p> +<ul> +<li><code>json</code> (default): JSON object with the path under the key “root”.</li> +<li><code>plain</code>: Just the path.</li> +</ul></dd> + + +<dt class="option-term" id="option-cargo-locate-project--v"><a class="option-anchor" href="#option-cargo-locate-project--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-locate-project---verbose"><a class="option-anchor" href="#option-cargo-locate-project---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-locate-project--q"><a class="option-anchor" href="#option-cargo-locate-project--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-locate-project---quiet"><a class="option-anchor" href="#option-cargo-locate-project---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-locate-project---color"><a class="option-anchor" href="#option-cargo-locate-project---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-locate-project---manifest-path"><a class="option-anchor" href="#option-cargo-locate-project---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-locate-project-+toolchain"><a class="option-anchor" href="#option-cargo-locate-project-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-locate-project---config"><a class="option-anchor" href="#option-cargo-locate-project---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-locate-project--C"><a class="option-anchor" href="#option-cargo-locate-project--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-locate-project--h"><a class="option-anchor" href="#option-cargo-locate-project--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-locate-project---help"><a class="option-anchor" href="#option-cargo-locate-project---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-locate-project--Z"><a class="option-anchor" href="#option-cargo-locate-project--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Display the path to the manifest based on the current directory: + + cargo locate-project + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-metadata(1)](cargo-metadata.html) diff --git a/src/doc/src/commands/cargo-login.md b/src/doc/src/commands/cargo-login.md new file mode 100644 index 0000000..cd6677e --- /dev/null +++ b/src/doc/src/commands/cargo-login.md @@ -0,0 +1,129 @@ +# cargo-login(1) + +## NAME + +cargo-login --- Save an API token from the registry locally + +## SYNOPSIS + +`cargo login` [_options_] [_token_] + +## DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication, such as [cargo-publish(1)](cargo-publish.html), will be automatically +authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` +defaults to `.cargo` in your home directory. + +If the _token_ argument is not specified, it will be read from stdin. + +The API token for crates.io may be retrieved from <https://crates.io/me>. + +Take care to keep the token secret, it should not be shared with anyone else. + +## OPTIONS + +### Login Options + +<dl> +<dt class="option-term" id="option-cargo-login---registry"><a class="option-anchor" href="#option-cargo-login---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-login--v"><a class="option-anchor" href="#option-cargo-login--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-login---verbose"><a class="option-anchor" href="#option-cargo-login---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-login--q"><a class="option-anchor" href="#option-cargo-login--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-login---quiet"><a class="option-anchor" href="#option-cargo-login---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-login---color"><a class="option-anchor" href="#option-cargo-login---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-login-+toolchain"><a class="option-anchor" href="#option-cargo-login-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-login---config"><a class="option-anchor" href="#option-cargo-login---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-login--C"><a class="option-anchor" href="#option-cargo-login--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-login--h"><a class="option-anchor" href="#option-cargo-login--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-login---help"><a class="option-anchor" href="#option-cargo-login---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-login--Z"><a class="option-anchor" href="#option-cargo-login--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Save the API token to disk: + + cargo login + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md new file mode 100644 index 0000000..711a4d7 --- /dev/null +++ b/src/doc/src/commands/cargo-metadata.md @@ -0,0 +1,478 @@ +# cargo-metadata(1) + +## NAME + +cargo-metadata --- Machine-readable metadata about the current package + +## SYNOPSIS + +`cargo metadata` [_options_] + +## DESCRIPTION + +Output JSON to stdout containing information about the workspace members and +resolved dependencies of the current package. + +It is recommended to include the `--format-version` flag to future-proof +your code to ensure the output is in the format you are expecting. + +See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) +for a Rust API for reading the metadata. + +## OUTPUT FORMAT + +The output has the following format: + +```javascript +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* The file system path for a local path dependency. + not present if not a path dependency. + */ + "path": "/path/to/dep", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether the target should be documented by `cargo doc`. */ + "doc": true, + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe <user@example.com>" + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The homepage value from the manifest or null if not specified. */ + "homepage": "https://rust-lang.org", + /* The documentation value from the manifest or null if not specified. */ + "documentation": "https://doc.rust-lang.org/stable/std", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } +} +```` + +## OPTIONS + +### Output Options + +<dl> + +<dt class="option-term" id="option-cargo-metadata---no-deps"><a class="option-anchor" href="#option-cargo-metadata---no-deps"></a><code>--no-deps</code></dt> +<dd class="option-desc">Output information only about the workspace members and don’t fetch +dependencies.</dd> + + +<dt class="option-term" id="option-cargo-metadata---format-version"><a class="option-anchor" href="#option-cargo-metadata---format-version"></a><code>--format-version</code> <em>version</em></dt> +<dd class="option-desc">Specify the version of the output format to use. Currently <code>1</code> is the only +possible value.</dd> + + +<dt class="option-term" id="option-cargo-metadata---filter-platform"><a class="option-anchor" href="#option-cargo-metadata---filter-platform"></a><code>--filter-platform</code> <em>triple</em></dt> +<dd class="option-desc">This filters the <code>resolve</code> output to only include dependencies for the +given <a href="../appendix/glossary.html#target">target triple</a>. +Without this flag, the resolve includes all targets.</p> +<p>Note that the dependencies listed in the “packages” array still includes all +dependencies. Each package definition is intended to be an unaltered +reproduction of the information within <code>Cargo.toml</code>.</dd> + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-metadata--F"><a class="option-anchor" href="#option-cargo-metadata--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-metadata---features"><a class="option-anchor" href="#option-cargo-metadata---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-metadata---all-features"><a class="option-anchor" href="#option-cargo-metadata---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-metadata---no-default-features"><a class="option-anchor" href="#option-cargo-metadata---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-metadata--v"><a class="option-anchor" href="#option-cargo-metadata--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-metadata---verbose"><a class="option-anchor" href="#option-cargo-metadata---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-metadata--q"><a class="option-anchor" href="#option-cargo-metadata--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-metadata---quiet"><a class="option-anchor" href="#option-cargo-metadata---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-metadata---color"><a class="option-anchor" href="#option-cargo-metadata---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-metadata---manifest-path"><a class="option-anchor" href="#option-cargo-metadata---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-metadata---frozen"><a class="option-anchor" href="#option-cargo-metadata---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-metadata---locked"><a class="option-anchor" href="#option-cargo-metadata---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-metadata---offline"><a class="option-anchor" href="#option-cargo-metadata---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-metadata-+toolchain"><a class="option-anchor" href="#option-cargo-metadata-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-metadata---config"><a class="option-anchor" href="#option-cargo-metadata---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-metadata--C"><a class="option-anchor" href="#option-cargo-metadata--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-metadata--h"><a class="option-anchor" href="#option-cargo-metadata--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-metadata---help"><a class="option-anchor" href="#option-cargo-metadata---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-metadata--Z"><a class="option-anchor" href="#option-cargo-metadata--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Output JSON about the current package: + + cargo metadata --format-version=1 + +## SEE ALSO +[cargo(1)](cargo.html) diff --git a/src/doc/src/commands/cargo-new.md b/src/doc/src/commands/cargo-new.md new file mode 100644 index 0000000..b6c9c50 --- /dev/null +++ b/src/doc/src/commands/cargo-new.md @@ -0,0 +1,156 @@ +# cargo-new(1) + +## NAME + +cargo-new --- Create a new Cargo package + +## SYNOPSIS + +`cargo new` [_options_] _path_ + +## DESCRIPTION + +This command will create a new Cargo package in the given directory. This +includes a simple template with a `Cargo.toml` manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see `--vcs` below). + +See [cargo-init(1)](cargo-init.html) for a similar command which will create a new manifest +in an existing directory. + +## OPTIONS + +### New Options + +<dl> + +<dt class="option-term" id="option-cargo-new---bin"><a class="option-anchor" href="#option-cargo-new---bin"></a><code>--bin</code></dt> +<dd class="option-desc">Create a package with a binary target (<code>src/main.rs</code>). +This is the default behavior.</dd> + + +<dt class="option-term" id="option-cargo-new---lib"><a class="option-anchor" href="#option-cargo-new---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Create a package with a library target (<code>src/lib.rs</code>).</dd> + + +<dt class="option-term" id="option-cargo-new---edition"><a class="option-anchor" href="#option-cargo-new---edition"></a><code>--edition</code> <em>edition</em></dt> +<dd class="option-desc">Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021</dd> + + +<dt class="option-term" id="option-cargo-new---name"><a class="option-anchor" href="#option-cargo-new---name"></a><code>--name</code> <em>name</em></dt> +<dd class="option-desc">Set the package name. Defaults to the directory name.</dd> + + +<dt class="option-term" id="option-cargo-new---vcs"><a class="option-anchor" href="#option-cargo-new---vcs"></a><code>--vcs</code> <em>vcs</em></dt> +<dd class="option-desc">Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to <code>git</code> or the configuration value +<code>cargo-new.vcs</code>, or <code>none</code> if already inside a VCS repository.</dd> + + +<dt class="option-term" id="option-cargo-new---registry"><a class="option-anchor" href="#option-cargo-new---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name +which will restrict publishing only to that registry.</p> +<p>Registry names are defined in <a href="../reference/config.html">Cargo config files</a>. +If not specified, the default registry defined by the <code>registry.default</code> +config key is used. If the default registry is not set and <code>--registry</code> is not +used, the <code>publish</code> field will not be set which means that publishing will not +be restricted.</dd> + + +</dl> + + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-new--v"><a class="option-anchor" href="#option-cargo-new--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-new---verbose"><a class="option-anchor" href="#option-cargo-new---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-new--q"><a class="option-anchor" href="#option-cargo-new--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-new---quiet"><a class="option-anchor" href="#option-cargo-new---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-new---color"><a class="option-anchor" href="#option-cargo-new---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-new-+toolchain"><a class="option-anchor" href="#option-cargo-new-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-new---config"><a class="option-anchor" href="#option-cargo-new---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-new--C"><a class="option-anchor" href="#option-cargo-new--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-new--h"><a class="option-anchor" href="#option-cargo-new--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-new---help"><a class="option-anchor" href="#option-cargo-new---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-new--Z"><a class="option-anchor" href="#option-cargo-new--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a binary Cargo package in the given directory: + + cargo new foo + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-init(1)](cargo-init.html) diff --git a/src/doc/src/commands/cargo-owner.md b/src/doc/src/commands/cargo-owner.md new file mode 100644 index 0000000..a19a2c3 --- /dev/null +++ b/src/doc/src/commands/cargo-owner.md @@ -0,0 +1,175 @@ +# cargo-owner(1) + +## NAME + +cargo-owner --- Manage the owners of a crate on the registry + +## SYNOPSIS + +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] + +## DESCRIPTION + +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care! + +This command requires you to be authenticated with either the `--token` option +or using [cargo-login(1)](cargo-login.html). + +If the crate name is not specified, it will use the package name from the +current directory. + +See [the reference](../reference/publishing.html#cargo-owner) for more +information about owners and publishing. + +## OPTIONS + +### Owner Options + +<dl> + +<dt class="option-term" id="option-cargo-owner--a"><a class="option-anchor" href="#option-cargo-owner--a"></a><code>-a</code></dt> +<dt class="option-term" id="option-cargo-owner---add"><a class="option-anchor" href="#option-cargo-owner---add"></a><code>--add</code> <em>login</em>…</dt> +<dd class="option-desc">Invite the given user or team as an owner.</dd> + + +<dt class="option-term" id="option-cargo-owner--r"><a class="option-anchor" href="#option-cargo-owner--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-owner---remove"><a class="option-anchor" href="#option-cargo-owner---remove"></a><code>--remove</code> <em>login</em>…</dt> +<dd class="option-desc">Remove the given user or team as an owner.</dd> + + +<dt class="option-term" id="option-cargo-owner--l"><a class="option-anchor" href="#option-cargo-owner--l"></a><code>-l</code></dt> +<dt class="option-term" id="option-cargo-owner---list"><a class="option-anchor" href="#option-cargo-owner---list"></a><code>--list</code></dt> +<dd class="option-desc">List owners of a crate.</dd> + + +<dt class="option-term" id="option-cargo-owner---token"><a class="option-anchor" href="#option-cargo-owner---token"></a><code>--token</code> <em>token</em></dt> +<dd class="option-desc">API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by <a href="cargo-login.html">cargo-login(1)</a>).</p> +<p><a href="../reference/config.html">Cargo config</a> environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment +variable. Tokens for other registries may be specified with environment +variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name +of the registry in all capital letters.</dd> + + + +<dt class="option-term" id="option-cargo-owner---index"><a class="option-anchor" href="#option-cargo-owner---index"></a><code>--index</code> <em>index</em></dt> +<dd class="option-desc">The URL of the registry index to use.</dd> + + + +<dt class="option-term" id="option-cargo-owner---registry"><a class="option-anchor" href="#option-cargo-owner---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-owner--v"><a class="option-anchor" href="#option-cargo-owner--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-owner---verbose"><a class="option-anchor" href="#option-cargo-owner---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-owner--q"><a class="option-anchor" href="#option-cargo-owner--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-owner---quiet"><a class="option-anchor" href="#option-cargo-owner---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-owner---color"><a class="option-anchor" href="#option-cargo-owner---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-owner-+toolchain"><a class="option-anchor" href="#option-cargo-owner-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-owner---config"><a class="option-anchor" href="#option-cargo-owner---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-owner--C"><a class="option-anchor" href="#option-cargo-owner--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-owner--h"><a class="option-anchor" href="#option-cargo-owner--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-owner---help"><a class="option-anchor" href="#option-cargo-owner---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-owner--Z"><a class="option-anchor" href="#option-cargo-owner--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. List owners of a package: + + cargo owner --list foo + +2. Invite an owner to a package: + + cargo owner --add username foo + +3. Remove an owner from a package: + + cargo owner --remove username foo + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-login(1)](cargo-login.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md new file mode 100644 index 0000000..cb4e02b --- /dev/null +++ b/src/doc/src/commands/cargo-package.md @@ -0,0 +1,333 @@ +# cargo-package(1) + + + + +## NAME + +cargo-package --- Assemble the local package into a distributable tarball + +## SYNOPSIS + +`cargo package` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory. The resulting file will +be stored in the `target/package` directory. This performs the following +steps: + +1. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. + `dev-dependencies` do not have this restriction. +2. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the + manifest. + - `Cargo.lock` is automatically included if the package contains an + executable binary or example target. [cargo-install(1)](cargo-install.html) will use the + packaged lock file if the `--locked` flag is used. + - A `.cargo_vcs_info.json` file is included that contains information + about the current VCS checkout hash if available (not included with + `--allow-dirty`). +3. Extract the `.crate` file and build it to verify it can build. + - This will rebuild your package from scratch to ensure that it can be + built from a pristine state. The `--no-verify` flag can be used to skip + this step. +4. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +### .cargo_vcs_info.json format + +Will generate a `.cargo_vcs_info.json` in the following format + +```javascript +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +``` + +`path_in_vcs` will be set to a repo-relative path for packages +in subdirectories of the version control repository. + +## OPTIONS + +### Package Options + +<dl> + +<dt class="option-term" id="option-cargo-package--l"><a class="option-anchor" href="#option-cargo-package--l"></a><code>-l</code></dt> +<dt class="option-term" id="option-cargo-package---list"><a class="option-anchor" href="#option-cargo-package---list"></a><code>--list</code></dt> +<dd class="option-desc">Print files included in a package without making one.</dd> + + +<dt class="option-term" id="option-cargo-package---no-verify"><a class="option-anchor" href="#option-cargo-package---no-verify"></a><code>--no-verify</code></dt> +<dd class="option-desc">Don’t verify the contents by building them.</dd> + + +<dt class="option-term" id="option-cargo-package---no-metadata"><a class="option-anchor" href="#option-cargo-package---no-metadata"></a><code>--no-metadata</code></dt> +<dd class="option-desc">Ignore warnings about a lack of human-usable metadata (such as the description +or the license).</dd> + + +<dt class="option-term" id="option-cargo-package---allow-dirty"><a class="option-anchor" href="#option-cargo-package---allow-dirty"></a><code>--allow-dirty</code></dt> +<dd class="option-desc">Allow working directories with uncommitted VCS changes to be packaged.</dd> + + +</dl> + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-package--p"><a class="option-anchor" href="#option-cargo-package--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-package---package"><a class="option-anchor" href="#option-cargo-package---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Package only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-package---workspace"><a class="option-anchor" href="#option-cargo-package---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Package all members in the workspace.</dd> + + + + +<dt class="option-term" id="option-cargo-package---exclude"><a class="option-anchor" href="#option-cargo-package---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-package---target"><a class="option-anchor" href="#option-cargo-package---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Package for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-package---target-dir"><a class="option-anchor" href="#option-cargo-package---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-package--F"><a class="option-anchor" href="#option-cargo-package--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-package---features"><a class="option-anchor" href="#option-cargo-package---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-package---all-features"><a class="option-anchor" href="#option-cargo-package---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-package---no-default-features"><a class="option-anchor" href="#option-cargo-package---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-package---manifest-path"><a class="option-anchor" href="#option-cargo-package---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-package---frozen"><a class="option-anchor" href="#option-cargo-package---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-package---locked"><a class="option-anchor" href="#option-cargo-package---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-package---offline"><a class="option-anchor" href="#option-cargo-package---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-package--j"><a class="option-anchor" href="#option-cargo-package--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-package---jobs"><a class="option-anchor" href="#option-cargo-package---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-package---keep-going"><a class="option-anchor" href="#option-cargo-package---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-package--v"><a class="option-anchor" href="#option-cargo-package--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-package---verbose"><a class="option-anchor" href="#option-cargo-package---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-package--q"><a class="option-anchor" href="#option-cargo-package--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-package---quiet"><a class="option-anchor" href="#option-cargo-package---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-package---color"><a class="option-anchor" href="#option-cargo-package---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-package-+toolchain"><a class="option-anchor" href="#option-cargo-package-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-package---config"><a class="option-anchor" href="#option-cargo-package---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-package--C"><a class="option-anchor" href="#option-cargo-package--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-package--h"><a class="option-anchor" href="#option-cargo-package--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-package---help"><a class="option-anchor" href="#option-cargo-package---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-package--Z"><a class="option-anchor" href="#option-cargo-package--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a compressed `.crate` file of the current package: + + cargo package + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md new file mode 100644 index 0000000..32f80ad --- /dev/null +++ b/src/doc/src/commands/cargo-pkgid.md @@ -0,0 +1,189 @@ +# cargo-pkgid(1) + +## NAME + +cargo-pkgid --- Print a fully qualified package specification + +## SYNOPSIS + +`cargo pkgid` [_options_] [_spec_] + +## DESCRIPTION + +Given a _spec_ argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if _spec_ is ambiguous as to which package it refers to in +the dependency graph. If no _spec_ is given, then the specifier for the local +package is printed. + +This command requires that a lockfile is available and dependencies have been +fetched. + +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a _spec_ can be one of the +following: + +SPEC Structure | Example SPEC +---------------------------|-------------- +_name_ | `bitflags` +_name_`@`_version_ | `bitflags@1.0.4` +_url_ | `https://github.com/rust-lang/cargo` +_url_`#`_version_ | `https://github.com/rust-lang/cargo#0.33.0` +_url_`#`_name_ | `https://github.com/rust-lang/crates.io-index#bitflags` +_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io@0.21.0` + +## OPTIONS + +### Package Selection + +<dl> + +<dt class="option-term" id="option-cargo-pkgid--p"><a class="option-anchor" href="#option-cargo-pkgid--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-pkgid---package"><a class="option-anchor" href="#option-cargo-pkgid---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">Get the package ID for the given package instead of the current package.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-pkgid--v"><a class="option-anchor" href="#option-cargo-pkgid--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-pkgid---verbose"><a class="option-anchor" href="#option-cargo-pkgid---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-pkgid--q"><a class="option-anchor" href="#option-cargo-pkgid--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-pkgid---quiet"><a class="option-anchor" href="#option-cargo-pkgid---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-pkgid---color"><a class="option-anchor" href="#option-cargo-pkgid---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-pkgid---manifest-path"><a class="option-anchor" href="#option-cargo-pkgid---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-pkgid---frozen"><a class="option-anchor" href="#option-cargo-pkgid---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-pkgid---locked"><a class="option-anchor" href="#option-cargo-pkgid---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-pkgid---offline"><a class="option-anchor" href="#option-cargo-pkgid---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-pkgid-+toolchain"><a class="option-anchor" href="#option-cargo-pkgid-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-pkgid---config"><a class="option-anchor" href="#option-cargo-pkgid---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-pkgid--C"><a class="option-anchor" href="#option-cargo-pkgid--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-pkgid--h"><a class="option-anchor" href="#option-cargo-pkgid--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-pkgid---help"><a class="option-anchor" href="#option-cargo-pkgid---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-pkgid--Z"><a class="option-anchor" href="#option-cargo-pkgid--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Retrieve package specification for `foo` package: + + cargo pkgid foo + +2. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo@1.0.0 + +3. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +4. Retrieve package specification for `foo` from a local package: + + cargo pkgid file:///path/to/local/package#foo + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html), [cargo-metadata(1)](cargo-metadata.html) diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md new file mode 100644 index 0000000..186d56a --- /dev/null +++ b/src/doc/src/commands/cargo-publish.md @@ -0,0 +1,299 @@ +# cargo-publish(1) + + + +## NAME + +cargo-publish --- Upload a package to the registry + +## SYNOPSIS + +`cargo publish` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory and upload it to a +registry. The default registry is <https://crates.io>. This performs the +following steps: + +1. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on + which registries you are allowed to publish to. +2. Create a `.crate` file by following the steps in [cargo-package(1)](cargo-package.html). +3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using [cargo-login(1)](cargo-login.html). + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Publish Options + +<dl> + +<dt class="option-term" id="option-cargo-publish---dry-run"><a class="option-anchor" href="#option-cargo-publish---dry-run"></a><code>--dry-run</code></dt> +<dd class="option-desc">Perform all checks without uploading.</dd> + + +<dt class="option-term" id="option-cargo-publish---token"><a class="option-anchor" href="#option-cargo-publish---token"></a><code>--token</code> <em>token</em></dt> +<dd class="option-desc">API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by <a href="cargo-login.html">cargo-login(1)</a>).</p> +<p><a href="../reference/config.html">Cargo config</a> environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment +variable. Tokens for other registries may be specified with environment +variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name +of the registry in all capital letters.</dd> + + + +<dt class="option-term" id="option-cargo-publish---no-verify"><a class="option-anchor" href="#option-cargo-publish---no-verify"></a><code>--no-verify</code></dt> +<dd class="option-desc">Don’t verify the contents by building them.</dd> + + +<dt class="option-term" id="option-cargo-publish---allow-dirty"><a class="option-anchor" href="#option-cargo-publish---allow-dirty"></a><code>--allow-dirty</code></dt> +<dd class="option-desc">Allow working directories with uncommitted VCS changes to be packaged.</dd> + + +<dt class="option-term" id="option-cargo-publish---index"><a class="option-anchor" href="#option-cargo-publish---index"></a><code>--index</code> <em>index</em></dt> +<dd class="option-desc">The URL of the registry index to use.</dd> + + + +<dt class="option-term" id="option-cargo-publish---registry"><a class="option-anchor" href="#option-cargo-publish---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to publish to. Registry names are defined in <a href="../reference/config.html">Cargo +config files</a>. If not specified, and there is a +<a href="../reference/manifest.html#the-publish-field"><code>package.publish</code></a> field in +<code>Cargo.toml</code> with a single registry, then it will publish to that registry. +Otherwise it will use the default registry, which is defined by the +<a href="../reference/config.html#registrydefault"><code>registry.default</code></a> config key +which defaults to <code>crates-io</code>.</dd> + + +</dl> + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +<dl> + +<dt class="option-term" id="option-cargo-publish--p"><a class="option-anchor" href="#option-cargo-publish--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-publish---package"><a class="option-anchor" href="#option-cargo-publish---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">The package to publish. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC +format.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-publish---target"><a class="option-anchor" href="#option-cargo-publish---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Publish for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-publish---target-dir"><a class="option-anchor" href="#option-cargo-publish---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-publish--F"><a class="option-anchor" href="#option-cargo-publish--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-publish---features"><a class="option-anchor" href="#option-cargo-publish---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-publish---all-features"><a class="option-anchor" href="#option-cargo-publish---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-publish---no-default-features"><a class="option-anchor" href="#option-cargo-publish---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-publish---manifest-path"><a class="option-anchor" href="#option-cargo-publish---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-publish---frozen"><a class="option-anchor" href="#option-cargo-publish---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-publish---locked"><a class="option-anchor" href="#option-cargo-publish---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-publish---offline"><a class="option-anchor" href="#option-cargo-publish---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-publish--j"><a class="option-anchor" href="#option-cargo-publish--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-publish---jobs"><a class="option-anchor" href="#option-cargo-publish---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-publish---keep-going"><a class="option-anchor" href="#option-cargo-publish---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-publish--v"><a class="option-anchor" href="#option-cargo-publish--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-publish---verbose"><a class="option-anchor" href="#option-cargo-publish---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-publish--q"><a class="option-anchor" href="#option-cargo-publish--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-publish---quiet"><a class="option-anchor" href="#option-cargo-publish---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-publish---color"><a class="option-anchor" href="#option-cargo-publish---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-publish-+toolchain"><a class="option-anchor" href="#option-cargo-publish-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-publish---config"><a class="option-anchor" href="#option-cargo-publish---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-publish--C"><a class="option-anchor" href="#option-cargo-publish--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-publish--h"><a class="option-anchor" href="#option-cargo-publish--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-publish---help"><a class="option-anchor" href="#option-cargo-publish---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-publish--Z"><a class="option-anchor" href="#option-cargo-publish--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Publish the current package: + + cargo publish + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-package(1)](cargo-package.html), [cargo-login(1)](cargo-login.html) diff --git a/src/doc/src/commands/cargo-remove.md b/src/doc/src/commands/cargo-remove.md new file mode 100644 index 0000000..4f47907 --- /dev/null +++ b/src/doc/src/commands/cargo-remove.md @@ -0,0 +1,192 @@ +# cargo-remove(1) + + + +## NAME + +cargo-remove --- Remove dependencies from a Cargo.toml manifest file + +## SYNOPSIS + +`cargo remove` [_options_] _dependency_... + +## DESCRIPTION + +Remove one or more dependencies from a `Cargo.toml` manifest. + +## OPTIONS + +### Section options + +<dl> + +<dt class="option-term" id="option-cargo-remove---dev"><a class="option-anchor" href="#option-cargo-remove---dev"></a><code>--dev</code></dt> +<dd class="option-desc">Remove as a <a href="../reference/specifying-dependencies.html#development-dependencies">development dependency</a>.</dd> + + +<dt class="option-term" id="option-cargo-remove---build"><a class="option-anchor" href="#option-cargo-remove---build"></a><code>--build</code></dt> +<dd class="option-desc">Remove as a <a href="../reference/specifying-dependencies.html#build-dependencies">build dependency</a>.</dd> + + +<dt class="option-term" id="option-cargo-remove---target"><a class="option-anchor" href="#option-cargo-remove---target"></a><code>--target</code> <em>target</em></dt> +<dd class="option-desc">Remove as a dependency to the <a href="../reference/specifying-dependencies.html#platform-specific-dependencies">given target platform</a>.</dd> + + +</dl> + +### Miscellaneous Options + +<dl> + +<dt class="option-term" id="option-cargo-remove---dry-run"><a class="option-anchor" href="#option-cargo-remove---dry-run"></a><code>--dry-run</code></dt> +<dd class="option-desc">Don’t actually write to the manifest.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-remove--v"><a class="option-anchor" href="#option-cargo-remove--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-remove---verbose"><a class="option-anchor" href="#option-cargo-remove---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-remove--q"><a class="option-anchor" href="#option-cargo-remove--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-remove---quiet"><a class="option-anchor" href="#option-cargo-remove---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-remove---color"><a class="option-anchor" href="#option-cargo-remove---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-remove---manifest-path"><a class="option-anchor" href="#option-cargo-remove---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-remove---frozen"><a class="option-anchor" href="#option-cargo-remove---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-remove---locked"><a class="option-anchor" href="#option-cargo-remove---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-remove---offline"><a class="option-anchor" href="#option-cargo-remove---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Package Selection + +<dl> + +<dt class="option-term" id="option-cargo-remove--p"><a class="option-anchor" href="#option-cargo-remove--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-remove---package"><a class="option-anchor" href="#option-cargo-remove---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Package to remove from.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-remove-+toolchain"><a class="option-anchor" href="#option-cargo-remove-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-remove---config"><a class="option-anchor" href="#option-cargo-remove---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-remove--C"><a class="option-anchor" href="#option-cargo-remove--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-remove--h"><a class="option-anchor" href="#option-cargo-remove--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-remove---help"><a class="option-anchor" href="#option-cargo-remove---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-remove--Z"><a class="option-anchor" href="#option-cargo-remove--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Remove `regex` as a dependency + + cargo remove regex + +2. Remove `trybuild` as a dev-dependency + + cargo remove --dev trybuild + +3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table + + cargo remove --target x86_64-pc-windows-gnu nom + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-add(1)](cargo-add.html) diff --git a/src/doc/src/commands/cargo-report.md b/src/doc/src/commands/cargo-report.md new file mode 100644 index 0000000..130449d --- /dev/null +++ b/src/doc/src/commands/cargo-report.md @@ -0,0 +1,43 @@ +# cargo-report(1) + +## NAME + +cargo-report --- Generate and display various kinds of reports + +## SYNOPSIS + +`cargo report` _type_ [_options_] + +### DESCRIPTION + +Displays a report of the given _type_ --- currently, only `future-incompat` is supported + +## OPTIONS + +<dl> + +<dt class="option-term" id="option-cargo-report---id"><a class="option-anchor" href="#option-cargo-report---id"></a><code>--id</code> <em>id</em></dt> +<dd class="option-desc">Show the report with the specified Cargo-generated id</dd> + + +<dt class="option-term" id="option-cargo-report--p"><a class="option-anchor" href="#option-cargo-report--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-report---package"><a class="option-anchor" href="#option-cargo-report---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Only display a report for the specified package</dd> + + +</dl> + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +## SEE ALSO +[Future incompat report](../reference/future-incompat-report.html) + +[cargo(1)](cargo.html) diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md new file mode 100644 index 0000000..a7f56e7 --- /dev/null +++ b/src/doc/src/commands/cargo-run.md @@ -0,0 +1,332 @@ +# cargo-run(1) + + +## NAME + +cargo-run --- Run the current package + +## SYNOPSIS + +`cargo run` [_options_] [`--` _args_] + +## DESCRIPTION + +Run a binary or example of the local package. + +All the arguments following the two dashes (`--`) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +`--` go to the binary, the ones before go to Cargo. + +## OPTIONS + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +<dl> + +<dt class="option-term" id="option-cargo-run--p"><a class="option-anchor" href="#option-cargo-run--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-run---package"><a class="option-anchor" href="#option-cargo-run---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">The package to run. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC +format.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo run` will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. Or, the `default-run` field may be specified in the `[package]` +section of `Cargo.toml` to choose the name of the binary to run by default. + +<dl> + +<dt class="option-term" id="option-cargo-run---bin"><a class="option-anchor" href="#option-cargo-run---bin"></a><code>--bin</code> <em>name</em></dt> +<dd class="option-desc">Run the specified binary.</dd> + + +<dt class="option-term" id="option-cargo-run---example"><a class="option-anchor" href="#option-cargo-run---example"></a><code>--example</code> <em>name</em></dt> +<dd class="option-desc">Run the specified example.</dd> + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-run--F"><a class="option-anchor" href="#option-cargo-run--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-run---features"><a class="option-anchor" href="#option-cargo-run---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-run---all-features"><a class="option-anchor" href="#option-cargo-run---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-run---no-default-features"><a class="option-anchor" href="#option-cargo-run---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-run---target"><a class="option-anchor" href="#option-cargo-run---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Run for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-run--r"><a class="option-anchor" href="#option-cargo-run--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-run---release"><a class="option-anchor" href="#option-cargo-run---release"></a><code>--release</code></dt> +<dd class="option-desc">Run optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-run---profile"><a class="option-anchor" href="#option-cargo-run---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Run with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-run---ignore-rust-version"><a class="option-anchor" href="#option-cargo-run---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Run the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-run---timings=fmts"><a class="option-anchor" href="#option-cargo-run---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-run---target-dir"><a class="option-anchor" href="#option-cargo-run---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-run--v"><a class="option-anchor" href="#option-cargo-run--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-run---verbose"><a class="option-anchor" href="#option-cargo-run---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-run--q"><a class="option-anchor" href="#option-cargo-run--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-run---quiet"><a class="option-anchor" href="#option-cargo-run---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-run---color"><a class="option-anchor" href="#option-cargo-run---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-run---message-format"><a class="option-anchor" href="#option-cargo-run---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-run---manifest-path"><a class="option-anchor" href="#option-cargo-run---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-run---frozen"><a class="option-anchor" href="#option-cargo-run---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-run---locked"><a class="option-anchor" href="#option-cargo-run---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-run---offline"><a class="option-anchor" href="#option-cargo-run---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-run-+toolchain"><a class="option-anchor" href="#option-cargo-run-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-run---config"><a class="option-anchor" href="#option-cargo-run---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-run--C"><a class="option-anchor" href="#option-cargo-run--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-run--h"><a class="option-anchor" href="#option-cargo-run--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-run---help"><a class="option-anchor" href="#option-cargo-run---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-run--Z"><a class="option-anchor" href="#option-cargo-run--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-run--j"><a class="option-anchor" href="#option-cargo-run--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-run---jobs"><a class="option-anchor" href="#option-cargo-run---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-run---keep-going"><a class="option-anchor" href="#option-cargo-run---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build the local package and run its main target (assuming only one binary): + + cargo run + +2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md new file mode 100644 index 0000000..158d726 --- /dev/null +++ b/src/doc/src/commands/cargo-rustc.md @@ -0,0 +1,444 @@ +# cargo-rustc(1) + + + +## NAME + +cargo-rustc --- Compile the current package, and pass extra options to the compiler + +## SYNOPSIS + +`cargo rustc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be compiled along with all of its dependencies. The specified +_args_ will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as `-L`, `--extern`, and `--crate-type`, and the specified +_args_ will simply be added to the compiler invocation. + +See <https://doc.rust-lang.org/rustc/index.html> for documentation on rustc +flags. + +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. + +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +[environment variable](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). + +## OPTIONS + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +<dl> + +<dt class="option-term" id="option-cargo-rustc--p"><a class="option-anchor" href="#option-cargo-rustc--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-rustc---package"><a class="option-anchor" href="#option-cargo-rustc---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">The package to build. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC +format.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + +Passing target selection flags will build only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-rustc---lib"><a class="option-anchor" href="#option-cargo-rustc---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Build the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-rustc---bin"><a class="option-anchor" href="#option-cargo-rustc---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustc---bins"><a class="option-anchor" href="#option-cargo-rustc---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Build all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-rustc---example"><a class="option-anchor" href="#option-cargo-rustc---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustc---examples"><a class="option-anchor" href="#option-cargo-rustc---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Build all example targets.</dd> + + +<dt class="option-term" id="option-cargo-rustc---test"><a class="option-anchor" href="#option-cargo-rustc---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustc---tests"><a class="option-anchor" href="#option-cargo-rustc---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Build all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-rustc---bench"><a class="option-anchor" href="#option-cargo-rustc---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Build the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustc---benches"><a class="option-anchor" href="#option-cargo-rustc---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Build all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-rustc---all-targets"><a class="option-anchor" href="#option-cargo-rustc---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Build all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-rustc--F"><a class="option-anchor" href="#option-cargo-rustc--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-rustc---features"><a class="option-anchor" href="#option-cargo-rustc---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-rustc---all-features"><a class="option-anchor" href="#option-cargo-rustc---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-rustc---no-default-features"><a class="option-anchor" href="#option-cargo-rustc---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-rustc---target"><a class="option-anchor" href="#option-cargo-rustc---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Build for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-rustc--r"><a class="option-anchor" href="#option-cargo-rustc--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-rustc---release"><a class="option-anchor" href="#option-cargo-rustc---release"></a><code>--release</code></dt> +<dd class="option-desc">Build optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-rustc---profile"><a class="option-anchor" href="#option-cargo-rustc---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Build with the given profile.</p> +<p>The <code>rustc</code> subcommand will treat the following named profiles with special behaviors:</p> +<ul> +<li><code>check</code> — Builds in the same way as the <a href="cargo-check.html">cargo-check(1)</a> command with +the <code>dev</code> profile.</li> +<li><code>test</code> — Builds in the same way as the <a href="cargo-test.html">cargo-test(1)</a> command, +enabling building in test mode which will enable tests and enable the <code>test</code> +cfg option. See <a href="https://doc.rust-lang.org/rustc/tests/index.html">rustc +tests</a> for more detail.</li> +<li><code>bench</code> — Builds in the same was as the <a href="cargo-bench.html">cargo-bench(1)</a> command, +similar to the <code>test</code> profile.</li> +</ul> +<p>See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + +<dt class="option-term" id="option-cargo-rustc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-rustc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-rustc---timings=fmts"><a class="option-anchor" href="#option-cargo-rustc---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +<dt class="option-term" id="option-cargo-rustc---crate-type"><a class="option-anchor" href="#option-cargo-rustc---crate-type"></a><code>--crate-type</code> <em>crate-type</em></dt> +<dd class="option-desc">Build for the given crate type. This flag accepts a comma-separated list of +1 or more crate types, of which the allowed values are the same as <code>crate-type</code> +field in the manifest for configurating a Cargo target. See +<a href="../reference/cargo-targets.html#the-crate-type-field"><code>crate-type</code> field</a> +for possible values.</p> +<p>If the manifest contains a list, and <code>--crate-type</code> is provided, +the command-line argument value will override what is in the manifest.</p> +<p>This flag only works when building a <code>lib</code> or <code>example</code> library target.</dd> + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-rustc---target-dir"><a class="option-anchor" href="#option-cargo-rustc---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-rustc--v"><a class="option-anchor" href="#option-cargo-rustc--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-rustc---verbose"><a class="option-anchor" href="#option-cargo-rustc---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-rustc--q"><a class="option-anchor" href="#option-cargo-rustc--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-rustc---quiet"><a class="option-anchor" href="#option-cargo-rustc---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-rustc---color"><a class="option-anchor" href="#option-cargo-rustc---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-rustc---message-format"><a class="option-anchor" href="#option-cargo-rustc---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-rustc---manifest-path"><a class="option-anchor" href="#option-cargo-rustc---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-rustc---frozen"><a class="option-anchor" href="#option-cargo-rustc---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-rustc---locked"><a class="option-anchor" href="#option-cargo-rustc---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-rustc---offline"><a class="option-anchor" href="#option-cargo-rustc---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-rustc-+toolchain"><a class="option-anchor" href="#option-cargo-rustc-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-rustc---config"><a class="option-anchor" href="#option-cargo-rustc---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-rustc--C"><a class="option-anchor" href="#option-cargo-rustc--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-rustc--h"><a class="option-anchor" href="#option-cargo-rustc--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-rustc---help"><a class="option-anchor" href="#option-cargo-rustc---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-rustc--Z"><a class="option-anchor" href="#option-cargo-rustc--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-rustc--j"><a class="option-anchor" href="#option-cargo-rustc--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-rustc---jobs"><a class="option-anchor" href="#option-cargo-rustc---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-rustc---keep-going"><a class="option-anchor" href="#option-cargo-rustc---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +<dt class="option-term" id="option-cargo-rustc---future-incompat-report"><a class="option-anchor" href="#option-cargo-rustc---future-incompat-report"></a><code>--future-incompat-report</code></dt> +<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command</p> +<p>See <a href="cargo-report.html">cargo-report(1)</a></dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + +2. Try an experimental flag on the nightly compiler, such as this which prints + the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +3. Override `crate-type` field in Cargo.toml with command-line option: + + cargo rustc --lib --crate-type lib,cdylib + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html), [rustc(1)](https://doc.rust-lang.org/rustc/index.html) diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md new file mode 100644 index 0000000..cfd08d2 --- /dev/null +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -0,0 +1,409 @@ +# cargo-rustdoc(1) + + + +## NAME + +cargo-rustdoc --- Build a package's documentation, using specified custom flags + +## SYNOPSIS + +`cargo rustdoc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be documented with the specified _args_ being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as `-L`, `--extern`, and `--crate-type`, and the specified _args_ will simply +be added to the rustdoc invocation. + +See <https://doc.rust-lang.org/rustdoc/index.html> for documentation on rustdoc +flags. + +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. + +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). + +## OPTIONS + +### Documentation Options + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc---open"><a class="option-anchor" href="#option-cargo-rustdoc---open"></a><code>--open</code></dt> +<dd class="option-desc">Open the docs in a browser after building them. This will use your default +browser unless you define another one in the <code>BROWSER</code> environment variable +or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration +option.</dd> + + +</dl> + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc--p"><a class="option-anchor" href="#option-cargo-rustdoc--p"></a><code>-p</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-rustdoc---package"><a class="option-anchor" href="#option-cargo-rustdoc---package"></a><code>--package</code> <em>spec</em></dt> +<dd class="option-desc">The package to document. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC +format.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo rustdoc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +Passing target selection flags will document only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc---lib"><a class="option-anchor" href="#option-cargo-rustdoc---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Document the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---bin"><a class="option-anchor" href="#option-cargo-rustdoc---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---bins"><a class="option-anchor" href="#option-cargo-rustdoc---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Document all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---example"><a class="option-anchor" href="#option-cargo-rustdoc---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---examples"><a class="option-anchor" href="#option-cargo-rustdoc---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Document all example targets.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---test"><a class="option-anchor" href="#option-cargo-rustdoc---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---tests"><a class="option-anchor" href="#option-cargo-rustdoc---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Document all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---bench"><a class="option-anchor" href="#option-cargo-rustdoc---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Document the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---benches"><a class="option-anchor" href="#option-cargo-rustdoc---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Document all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---all-targets"><a class="option-anchor" href="#option-cargo-rustdoc---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Document all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc--F"><a class="option-anchor" href="#option-cargo-rustdoc--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-rustdoc---features"><a class="option-anchor" href="#option-cargo-rustdoc---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---all-features"><a class="option-anchor" href="#option-cargo-rustdoc---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---no-default-features"><a class="option-anchor" href="#option-cargo-rustdoc---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc---target"><a class="option-anchor" href="#option-cargo-rustdoc---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Document for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc--r"><a class="option-anchor" href="#option-cargo-rustdoc--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-rustdoc---release"><a class="option-anchor" href="#option-cargo-rustdoc---release"></a><code>--release</code></dt> +<dd class="option-desc">Document optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---profile"><a class="option-anchor" href="#option-cargo-rustdoc---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Document with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-rustdoc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---timings=fmts"><a class="option-anchor" href="#option-cargo-rustdoc---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-rustdoc---target-dir"><a class="option-anchor" href="#option-cargo-rustdoc---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-rustdoc--v"><a class="option-anchor" href="#option-cargo-rustdoc--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-rustdoc---verbose"><a class="option-anchor" href="#option-cargo-rustdoc---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc--q"><a class="option-anchor" href="#option-cargo-rustdoc--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-rustdoc---quiet"><a class="option-anchor" href="#option-cargo-rustdoc---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---color"><a class="option-anchor" href="#option-cargo-rustdoc---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---message-format"><a class="option-anchor" href="#option-cargo-rustdoc---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo-rustdoc---manifest-path"><a class="option-anchor" href="#option-cargo-rustdoc---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-rustdoc---frozen"><a class="option-anchor" href="#option-cargo-rustdoc---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-rustdoc---locked"><a class="option-anchor" href="#option-cargo-rustdoc---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---offline"><a class="option-anchor" href="#option-cargo-rustdoc---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-rustdoc-+toolchain"><a class="option-anchor" href="#option-cargo-rustdoc-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---config"><a class="option-anchor" href="#option-cargo-rustdoc---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc--C"><a class="option-anchor" href="#option-cargo-rustdoc--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-rustdoc--h"><a class="option-anchor" href="#option-cargo-rustdoc--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-rustdoc---help"><a class="option-anchor" href="#option-cargo-rustdoc---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc--Z"><a class="option-anchor" href="#option-cargo-rustdoc--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +<dl> +<dt class="option-term" id="option-cargo-rustdoc--j"><a class="option-anchor" href="#option-cargo-rustdoc--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-rustdoc---jobs"><a class="option-anchor" href="#option-cargo-rustdoc---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-rustdoc---keep-going"><a class="option-anchor" href="#option-cargo-rustdoc---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-doc(1)](cargo-doc.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-search.md b/src/doc/src/commands/cargo-search.md new file mode 100644 index 0000000..58440be --- /dev/null +++ b/src/doc/src/commands/cargo-search.md @@ -0,0 +1,133 @@ +# cargo-search(1) + +## NAME + +cargo-search --- Search packages in crates.io + +## SYNOPSIS + +`cargo search` [_options_] [_query_...] + +## DESCRIPTION + +This performs a textual search for crates on <https://crates.io>. The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +## OPTIONS + +### Search Options + +<dl> + +<dt class="option-term" id="option-cargo-search---limit"><a class="option-anchor" href="#option-cargo-search---limit"></a><code>--limit</code> <em>limit</em></dt> +<dd class="option-desc">Limit the number of results (default: 10, max: 100).</dd> + + +<dt class="option-term" id="option-cargo-search---index"><a class="option-anchor" href="#option-cargo-search---index"></a><code>--index</code> <em>index</em></dt> +<dd class="option-desc">The URL of the registry index to use.</dd> + + + +<dt class="option-term" id="option-cargo-search---registry"><a class="option-anchor" href="#option-cargo-search---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-search--v"><a class="option-anchor" href="#option-cargo-search--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-search---verbose"><a class="option-anchor" href="#option-cargo-search---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-search--q"><a class="option-anchor" href="#option-cargo-search--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-search---quiet"><a class="option-anchor" href="#option-cargo-search---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-search---color"><a class="option-anchor" href="#option-cargo-search---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-search-+toolchain"><a class="option-anchor" href="#option-cargo-search-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-search---config"><a class="option-anchor" href="#option-cargo-search---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-search--C"><a class="option-anchor" href="#option-cargo-search--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-search--h"><a class="option-anchor" href="#option-cargo-search--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-search---help"><a class="option-anchor" href="#option-cargo-search---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-search--Z"><a class="option-anchor" href="#option-cargo-search--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Search for a package from crates.io: + + cargo search serde + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-install(1)](cargo-install.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md new file mode 100644 index 0000000..d127235 --- /dev/null +++ b/src/doc/src/commands/cargo-test.md @@ -0,0 +1,536 @@ +# cargo-test(1) + + + + +## NAME + +cargo-test --- Execute unit and integration tests of a package + +## SYNOPSIS + +`cargo test` [_options_] [_testname_] [`--` _test-options_] + +## DESCRIPTION + +Compile and execute unit, integration, and documentation tests. + +The test filtering argument `TESTNAME` and all the arguments following the two +dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's +built in unit-test and micro-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after `--` go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of `cargo test -- --help` and check out the rustc book's chapter on +how tests work at <https://doc.rust-lang.org/rustc/tests/index.html>. + +As an example, this will filter for tests with `foo` in their name and run them +on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + +Tests are built with the `--test` option to `rustc` which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the `#[test]` attribute in multiple threads. +`#[bench]` annotated functions will also be run with one iteration to verify +that they are functional. + +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running tests. + +### Documentation tests + +Documentation tests are also run by default, which is handled by `rustdoc`. It +extracts code samples from documentation comments of the library target, and +then executes them. + +Different from normal test targets, each code block compiles to a doctest +executable on the fly with `rustc`. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as `--jobs` might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. + +See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information +on writing doc tests. + +## OPTIONS + +### Test Options + +<dl> + +<dt class="option-term" id="option-cargo-test---no-run"><a class="option-anchor" href="#option-cargo-test---no-run"></a><code>--no-run</code></dt> +<dd class="option-desc">Compile, but don’t run tests.</dd> + + +<dt class="option-term" id="option-cargo-test---no-fail-fast"><a class="option-anchor" href="#option-cargo-test---no-fail-fast"></a><code>--no-fail-fast</code></dt> +<dd class="option-desc">Run all tests regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all tests +within the executable to completion, this flag only applies to the executable +as a whole.</dd> + + +</dl> + + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-test--p"><a class="option-anchor" href="#option-cargo-test--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-test---package"><a class="option-anchor" href="#option-cargo-test---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Test only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-test---workspace"><a class="option-anchor" href="#option-cargo-test---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Test all members in the workspace.</dd> + + + +<dt class="option-term" id="option-cargo-test---all"><a class="option-anchor" href="#option-cargo-test---all"></a><code>--all</code></dt> +<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> + + + +<dt class="option-term" id="option-cargo-test---exclude"><a class="option-anchor" href="#option-cargo-test---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Target Selection + +When no target selection options are given, `cargo test` will build the +following targets of the selected packages: + +- lib --- used to link with binaries, examples, integration tests, and doc tests +- bins (only if integration tests are built and required features are + available) +- examples --- to ensure they compile +- lib as a unit test +- bins as unit tests +- integration tests +- doc tests for the lib target + +The default behavior can be changed by setting the `test` flag for the target +in the manifest settings. Setting examples to `test = true` will build and run +the example as a test. Setting targets to `test = false` will stop them from +being tested by default. Target selection options that take a target by name +ignore the `test` flag and will always test the given target. + +Doc tests for libraries may be disabled by setting `doctest = false` for the +library in the manifest. + +Binary targets are automatically built if there is an integration test or +benchmark being selected to test. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + +Passing target selection flags will test only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +<dl> + +<dt class="option-term" id="option-cargo-test---lib"><a class="option-anchor" href="#option-cargo-test---lib"></a><code>--lib</code></dt> +<dd class="option-desc">Test the package’s library.</dd> + + +<dt class="option-term" id="option-cargo-test---bin"><a class="option-anchor" href="#option-cargo-test---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Test the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-test---bins"><a class="option-anchor" href="#option-cargo-test---bins"></a><code>--bins</code></dt> +<dd class="option-desc">Test all binary targets.</dd> + + + +<dt class="option-term" id="option-cargo-test---example"><a class="option-anchor" href="#option-cargo-test---example"></a><code>--example</code> <em>name</em>…</dt> +<dd class="option-desc">Test the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-test---examples"><a class="option-anchor" href="#option-cargo-test---examples"></a><code>--examples</code></dt> +<dd class="option-desc">Test all example targets.</dd> + + +<dt class="option-term" id="option-cargo-test---test"><a class="option-anchor" href="#option-cargo-test---test"></a><code>--test</code> <em>name</em>…</dt> +<dd class="option-desc">Test the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-test---tests"><a class="option-anchor" href="#option-cargo-test---tests"></a><code>--tests</code></dt> +<dd class="option-desc">Test all targets in test mode that have the <code>test = true</code> manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the <code>test</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-test---bench"><a class="option-anchor" href="#option-cargo-test---bench"></a><code>--bench</code> <em>name</em>…</dt> +<dd class="option-desc">Test the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns.</dd> + + +<dt class="option-term" id="option-cargo-test---benches"><a class="option-anchor" href="#option-cargo-test---benches"></a><code>--benches</code></dt> +<dd class="option-desc">Test all targets in benchmark mode that have the <code>bench = true</code> +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the <code>bench</code> flag in the +manifest settings for the target.</dd> + + +<dt class="option-term" id="option-cargo-test---all-targets"><a class="option-anchor" href="#option-cargo-test---all-targets"></a><code>--all-targets</code></dt> +<dd class="option-desc">Test all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> + + +</dl> + + +<dl> + +<dt class="option-term" id="option-cargo-test---doc"><a class="option-anchor" href="#option-cargo-test---doc"></a><code>--doc</code></dt> +<dd class="option-desc">Test only the library’s documentation. This cannot be mixed with other +target options.</dd> + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-test--F"><a class="option-anchor" href="#option-cargo-test--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-test---features"><a class="option-anchor" href="#option-cargo-test---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-test---all-features"><a class="option-anchor" href="#option-cargo-test---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-test---no-default-features"><a class="option-anchor" href="#option-cargo-test---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Compilation Options + +<dl> + +<dt class="option-term" id="option-cargo-test---target"><a class="option-anchor" href="#option-cargo-test---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Test for the given architecture. The default is the host architecture. The general format of the triple is +<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a +list of supported targets. This flag may be specified multiple times.</p> +<p>This may also be specified with the <code>build.target</code> +<a href="../reference/config.html">config value</a>.</p> +<p>Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> + + + +<dt class="option-term" id="option-cargo-test--r"><a class="option-anchor" href="#option-cargo-test--r"></a><code>-r</code></dt> +<dt class="option-term" id="option-cargo-test---release"><a class="option-anchor" href="#option-cargo-test---release"></a><code>--release</code></dt> +<dd class="option-desc">Test optimized artifacts with the <code>release</code> profile. +See also the <code>--profile</code> option for choosing a specific profile by name.</dd> + + + +<dt class="option-term" id="option-cargo-test---profile"><a class="option-anchor" href="#option-cargo-test---profile"></a><code>--profile</code> <em>name</em></dt> +<dd class="option-desc">Test with the given profile. +See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> + + + +<dt class="option-term" id="option-cargo-test---ignore-rust-version"><a class="option-anchor" href="#option-cargo-test---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> +<dd class="option-desc">Test the target even if the selected Rust compiler is older than the +required Rust version as configured in the project’s <code>rust-version</code> field.</dd> + + + +<dt class="option-term" id="option-cargo-test---timings=fmts"><a class="option-anchor" href="#option-cargo-test---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> +<dd class="option-desc">Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. +Specifying an output format (rather than the default) is unstable and requires +<code>-Zunstable-options</code>. Valid output formats:</p> +<ul> +<li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the +<code>target/cargo-timings</code> directory with a report of the compilation. Also write +a report to the same directory with a timestamp in the filename if you want +to look at older runs. HTML output is suitable for human consumption only, +and does not provide machine-readable timing data.</li> +<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON +information about timing information.</li> +</ul></dd> + + + + +</dl> + +### Output Options + +<dl> +<dt class="option-term" id="option-cargo-test---target-dir"><a class="option-anchor" href="#option-cargo-test---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> +<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be +specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the +<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. +Defaults to <code>target</code> in the root of the workspace.</dd> + + +</dl> + +### Display Options + +By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g., for debugging) by passing +`--nocapture` to the test binaries: + + cargo test -- --nocapture + +<dl> + +<dt class="option-term" id="option-cargo-test--v"><a class="option-anchor" href="#option-cargo-test--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-test---verbose"><a class="option-anchor" href="#option-cargo-test---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-test--q"><a class="option-anchor" href="#option-cargo-test--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-test---quiet"><a class="option-anchor" href="#option-cargo-test---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-test---color"><a class="option-anchor" href="#option-cargo-test---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +<dt class="option-term" id="option-cargo-test---message-format"><a class="option-anchor" href="#option-cargo-test---message-format"></a><code>--message-format</code> <em>fmt</em></dt> +<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values:</p> +<ul> +<li><code>human</code> (default): Display in a human-readable text format. Conflicts with +<code>short</code> and <code>json</code>.</li> +<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> +and <code>json</code>.</li> +<li><code>json</code>: Emit JSON messages to stdout. See +<a href="../reference/external-tools.html#json-messages">the reference</a> +for more details. Conflicts with <code>human</code> and <code>short</code>.</li> +<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains +the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages +contains embedded ANSI color codes for respecting rustc’s default color +scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> +<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> +</ul></dd> + + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-test---manifest-path"><a class="option-anchor" href="#option-cargo-test---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-test---frozen"><a class="option-anchor" href="#option-cargo-test---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-test---locked"><a class="option-anchor" href="#option-cargo-test---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-test---offline"><a class="option-anchor" href="#option-cargo-test---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-test-+toolchain"><a class="option-anchor" href="#option-cargo-test-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-test---config"><a class="option-anchor" href="#option-cargo-test---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-test--C"><a class="option-anchor" href="#option-cargo-test--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-test--h"><a class="option-anchor" href="#option-cargo-test--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-test---help"><a class="option-anchor" href="#option-cargo-test---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-test--Z"><a class="option-anchor" href="#option-cargo-test--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +### Miscellaneous Options + +The `--jobs` argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + +<dl> + +<dt class="option-term" id="option-cargo-test--j"><a class="option-anchor" href="#option-cargo-test--j"></a><code>-j</code> <em>N</em></dt> +<dt class="option-term" id="option-cargo-test---jobs"><a class="option-anchor" href="#option-cargo-test---jobs"></a><code>--jobs</code> <em>N</em></dt> +<dd class="option-desc">Number of parallel jobs to run. May also be specified with the +<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0.</dd> + + +<dt class="option-term" id="option-cargo-test---keep-going"><a class="option-anchor" href="#option-cargo-test---keep-going"></a><code>--keep-going</code></dt> +<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +<code>-Zunstable-options</code>.</dd> + + +<dt class="option-term" id="option-cargo-test---future-incompat-report"><a class="option-anchor" href="#option-cargo-test---future-incompat-report"></a><code>--future-incompat-report</code></dt> +<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command</p> +<p>See <a href="cargo-report.html">cargo-report(1)</a></dd> + + + +</dl> + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Execute all the unit and integration tests of the current package: + + cargo test + +2. Run only tests whose names match against a filter string: + + cargo test name_filter + +3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-bench(1)](cargo-bench.html), [types of tests](../reference/cargo-targets.html#tests), [how to write tests](https://doc.rust-lang.org/rustc/tests/index.html) diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md new file mode 100644 index 0000000..e3c19e4 --- /dev/null +++ b/src/doc/src/commands/cargo-tree.md @@ -0,0 +1,435 @@ +# cargo-tree(1) + + + +## NAME + +cargo-tree --- Display a tree visualization of a dependency graph + +## SYNOPSIS + +`cargo tree` [_options_] + +## DESCRIPTION + +This command will display a tree of dependencies to the terminal. An example +of a simple project that depends on the "rand" package: + +``` +myproject v0.1.0 (/myproject) +└── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) +[build-dependencies] +└── cc v1.0.50 +``` + +Packages marked with `(*)` have been "de-duplicated". The dependencies for the +package have already been shown elsewhere in the graph, and so are not +repeated. Use the `--no-dedupe` option to repeat the duplicates. + +The `-e` flag can be used to select the dependency kinds to display. The +"features" kind changes the output to display the features enabled by +each dependency. For example, `cargo tree -e features`: + +``` +myproject v0.1.0 (/myproject) +└── log feature "serde" + └── log v0.4.8 + ├── serde v1.0.106 + └── cfg-if feature "default" + └── cfg-if v0.1.10 +``` + +In this tree, `myproject` depends on `log` with the `serde` feature. `log` in +turn depends on `cfg-if` with "default" features. When using `-e features` it +can be helpful to use `-i` flag to show how the features flow into a package. +See the examples below for more detail. + +### Feature Unification + +This command shows a graph much closer to a feature-unified graph Cargo will +build, rather than what you list in `Cargo.toml`. For instance, if you specify +the same dependency in both `[dependencies]` and `[dev-dependencies]` but with +different features on. This command may merge all features and show a `(*)` on +one of the dependency to indicate the duplicate. + +As a result, for a mostly equivalent overview of what `cargo build` does, +`cargo tree -e normal,build` is pretty close; for a mostly equivalent overview +of what `cargo test` does, `cargo tree` is pretty close. However, it doesn't +guarantee the exact equivalence to what Cargo is going to build, since a +compilation is complex and depends on lots of different factors. + +To learn more about feature unification, check out this +[dedicated section](../reference/features.html#feature-unification). + +## OPTIONS + +### Tree Options + +<dl> + +<dt class="option-term" id="option-cargo-tree--i"><a class="option-anchor" href="#option-cargo-tree--i"></a><code>-i</code> <em>spec</em></dt> +<dt class="option-term" id="option-cargo-tree---invert"><a class="option-anchor" href="#option-cargo-tree---invert"></a><code>--invert</code> <em>spec</em></dt> +<dd class="option-desc">Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package.</p> +<p>Note that in a workspace, by default it will only display the package’s +reverse dependencies inside the tree of the workspace member in the current +directory. The <code>--workspace</code> flag can be used to extend it so that it will +show the package’s reverse dependencies across the entire workspace. The <code>-p</code> +flag can be used to display the package’s reverse dependencies only with the +subtree of the package given to <code>-p</code>.</dd> + + +<dt class="option-term" id="option-cargo-tree---prune"><a class="option-anchor" href="#option-cargo-tree---prune"></a><code>--prune</code> <em>spec</em></dt> +<dd class="option-desc">Prune the given package from the display of the dependency tree.</dd> + + +<dt class="option-term" id="option-cargo-tree---depth"><a class="option-anchor" href="#option-cargo-tree---depth"></a><code>--depth</code> <em>depth</em></dt> +<dd class="option-desc">Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example.</dd> + + +<dt class="option-term" id="option-cargo-tree---no-dedupe"><a class="option-anchor" href="#option-cargo-tree---no-dedupe"></a><code>--no-dedupe</code></dt> +<dd class="option-desc">Do not de-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re-display its +dependencies, and will include a <code>(*)</code> to indicate it has already been shown. +This flag will cause those duplicates to be repeated.</dd> + + +<dt class="option-term" id="option-cargo-tree--d"><a class="option-anchor" href="#option-cargo-tree--d"></a><code>-d</code></dt> +<dt class="option-term" id="option-cargo-tree---duplicates"><a class="option-anchor" href="#option-cargo-tree---duplicates"></a><code>--duplicates</code></dt> +<dd class="option-desc">Show only dependencies which come in multiple versions (implies <code>--invert</code>). +When used with the <code>-p</code> flag, only shows duplicates within the subtree of the +given package.</p> +<p>It can be beneficial for build times and executable sizes to avoid building +that same package multiple times. This flag can help identify the offending +packages. You can then investigate if the package that depends on the +duplicate with the older version can be updated to the newer version so that +only one instance is built.</dd> + + +<dt class="option-term" id="option-cargo-tree--e"><a class="option-anchor" href="#option-cargo-tree--e"></a><code>-e</code> <em>kinds</em></dt> +<dt class="option-term" id="option-cargo-tree---edges"><a class="option-anchor" href="#option-cargo-tree---edges"></a><code>--edges</code> <em>kinds</em></dt> +<dd class="option-desc">The dependency kinds to display. Takes a comma separated list of values:</p> +<ul> +<li><code>all</code> — Show all edge kinds.</li> +<li><code>normal</code> — Show normal dependencies.</li> +<li><code>build</code> — Show build dependencies.</li> +<li><code>dev</code> — Show development dependencies.</li> +<li><code>features</code> — Show features enabled by each dependency. If this is the only +kind given, then it will automatically include the other dependency kinds.</li> +<li><code>no-normal</code> — Do not include normal dependencies.</li> +<li><code>no-build</code> — Do not include build dependencies.</li> +<li><code>no-dev</code> — Do not include development dependencies.</li> +<li><code>no-proc-macro</code> — Do not include procedural macro dependencies.</li> +</ul> +<p>The <code>normal</code>, <code>build</code>, <code>dev</code>, and <code>all</code> dependency kinds cannot be mixed with +<code>no-normal</code>, <code>no-build</code>, or <code>no-dev</code> dependency kinds.</p> +<p>The default is <code>normal,build,dev</code>.</dd> + + +<dt class="option-term" id="option-cargo-tree---target"><a class="option-anchor" href="#option-cargo-tree---target"></a><code>--target</code> <em>triple</em></dt> +<dd class="option-desc">Filter dependencies matching the given <a href="../appendix/glossary.html#target">target triple</a>. +The default is the host platform. Use the value <code>all</code> to include <em>all</em> targets.</dd> + + +</dl> + +### Tree Formatting Options + +<dl> + +<dt class="option-term" id="option-cargo-tree---charset"><a class="option-anchor" href="#option-cargo-tree---charset"></a><code>--charset</code> <em>charset</em></dt> +<dd class="option-desc">Chooses the character set to use for the tree. Valid values are “utf8” or +“ascii”. Default is “utf8”.</dd> + + +<dt class="option-term" id="option-cargo-tree--f"><a class="option-anchor" href="#option-cargo-tree--f"></a><code>-f</code> <em>format</em></dt> +<dt class="option-term" id="option-cargo-tree---format"><a class="option-anchor" href="#option-cargo-tree---format"></a><code>--format</code> <em>format</em></dt> +<dd class="option-desc">Set the format string for each package. The default is “{p}”.</p> +<p>This is an arbitrary string which will be used to display each package. The following +strings will be replaced with the corresponding value:</p> +<ul> +<li><code>{p}</code> — The package name.</li> +<li><code>{l}</code> — The package license.</li> +<li><code>{r}</code> — The package repository URL.</li> +<li><code>{f}</code> — Comma-separated list of package features that are enabled.</li> +<li><code>{lib}</code> — The name, as used in a <code>use</code> statement, of the package’s library.</li> +</ul></dd> + + +<dt class="option-term" id="option-cargo-tree---prefix"><a class="option-anchor" href="#option-cargo-tree---prefix"></a><code>--prefix</code> <em>prefix</em></dt> +<dd class="option-desc">Sets how each line is displayed. The <em>prefix</em> value can be one of:</p> +<ul> +<li><code>indent</code> (default) — Shows each line indented as a tree.</li> +<li><code>depth</code> — Show as a list, with the numeric depth printed before each entry.</li> +<li><code>none</code> — Show as a flat list.</li> +</ul></dd> + + +</dl> + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +<dl> + +<dt class="option-term" id="option-cargo-tree--p"><a class="option-anchor" href="#option-cargo-tree--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-tree---package"><a class="option-anchor" href="#option-cargo-tree---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Display only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.</dd> + + +<dt class="option-term" id="option-cargo-tree---workspace"><a class="option-anchor" href="#option-cargo-tree---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Display all members in the workspace.</dd> + + + + +<dt class="option-term" id="option-cargo-tree---exclude"><a class="option-anchor" href="#option-cargo-tree---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt> +<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the +<code>--workspace</code> flag. This flag may be specified multiple times and supports +common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.</dd> + + +</dl> + + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-tree---manifest-path"><a class="option-anchor" href="#option-cargo-tree---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-tree---frozen"><a class="option-anchor" href="#option-cargo-tree---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-tree---locked"><a class="option-anchor" href="#option-cargo-tree---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-tree---offline"><a class="option-anchor" href="#option-cargo-tree---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +<dl> + +<dt class="option-term" id="option-cargo-tree--F"><a class="option-anchor" href="#option-cargo-tree--F"></a><code>-F</code> <em>features</em></dt> +<dt class="option-term" id="option-cargo-tree---features"><a class="option-anchor" href="#option-cargo-tree---features"></a><code>--features</code> <em>features</em></dt> +<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace +members may be enabled with <code>package-name/feature-name</code> syntax. This flag may +be specified multiple times, which enables all specified features.</dd> + + +<dt class="option-term" id="option-cargo-tree---all-features"><a class="option-anchor" href="#option-cargo-tree---all-features"></a><code>--all-features</code></dt> +<dd class="option-desc">Activate all available features of all selected packages.</dd> + + +<dt class="option-term" id="option-cargo-tree---no-default-features"><a class="option-anchor" href="#option-cargo-tree---no-default-features"></a><code>--no-default-features</code></dt> +<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> + + +</dl> + + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-tree--v"><a class="option-anchor" href="#option-cargo-tree--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-tree---verbose"><a class="option-anchor" href="#option-cargo-tree---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-tree--q"><a class="option-anchor" href="#option-cargo-tree--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-tree---quiet"><a class="option-anchor" href="#option-cargo-tree---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-tree---color"><a class="option-anchor" href="#option-cargo-tree---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-tree-+toolchain"><a class="option-anchor" href="#option-cargo-tree-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-tree---config"><a class="option-anchor" href="#option-cargo-tree---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-tree--C"><a class="option-anchor" href="#option-cargo-tree--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-tree--h"><a class="option-anchor" href="#option-cargo-tree--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-tree---help"><a class="option-anchor" href="#option-cargo-tree---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-tree--Z"><a class="option-anchor" href="#option-cargo-tree--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Display the tree for the package in the current directory: + + cargo tree + +2. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +4. Show all packages that are built multiple times. This can happen if multiple + semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). + + cargo tree -d + +5. Explain why features are enabled for the `syn` package: + + cargo tree -e features -i syn + + The `-e features` flag is used to show features. The `-i` flag is used to + invert the graph so that it displays the packages that depend on `syn`. An + example of what this would display: + + ``` + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + ``` + + To read this graph, you can follow the chain for each feature from the root + to see why it is included. For example, the "full" feature is added by the + `rustversion` crate which is included from `myproject` (with the default + features), and `myproject` is the package selected on the command-line. All + of the other `syn` features are added by the "default" feature ("quote" is + added by "printing" and "proc-macro", both of which are default features). + + If you're having difficulty cross-referencing the de-duplicated `(*)` + entries, try with the `--no-dedupe` flag to get the full output. + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-metadata(1)](cargo-metadata.html) diff --git a/src/doc/src/commands/cargo-uninstall.md b/src/doc/src/commands/cargo-uninstall.md new file mode 100644 index 0000000..5b43d0a --- /dev/null +++ b/src/doc/src/commands/cargo-uninstall.md @@ -0,0 +1,143 @@ +# cargo-uninstall(1) + +## NAME + +cargo-uninstall --- Remove a Rust binary + +## SYNOPSIS + +`cargo uninstall` [_options_] [_spec_...] + +## DESCRIPTION + +This command removes a package installed with [cargo-install(1)](cargo-install.html). The _spec_ +argument is a package ID specification of the package to remove (see +[cargo-pkgid(1)](cargo-pkgid.html)). + +By default all binaries are removed for a crate but the `--bin` and +`--example` flags can be used to only remove particular binaries. + +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` + + +## OPTIONS + +### Install Options + +<dl> + +<dt class="option-term" id="option-cargo-uninstall--p"><a class="option-anchor" href="#option-cargo-uninstall--p"></a><code>-p</code></dt> +<dt class="option-term" id="option-cargo-uninstall---package"><a class="option-anchor" href="#option-cargo-uninstall---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Package to uninstall.</dd> + + +<dt class="option-term" id="option-cargo-uninstall---bin"><a class="option-anchor" href="#option-cargo-uninstall---bin"></a><code>--bin</code> <em>name</em>…</dt> +<dd class="option-desc">Only uninstall the binary <em>name</em>.</dd> + + +<dt class="option-term" id="option-cargo-uninstall---root"><a class="option-anchor" href="#option-cargo-uninstall---root"></a><code>--root</code> <em>dir</em></dt> +<dd class="option-desc">Directory to uninstall packages from.</dd> + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-uninstall--v"><a class="option-anchor" href="#option-cargo-uninstall--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-uninstall---verbose"><a class="option-anchor" href="#option-cargo-uninstall---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-uninstall--q"><a class="option-anchor" href="#option-cargo-uninstall--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-uninstall---quiet"><a class="option-anchor" href="#option-cargo-uninstall---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-uninstall---color"><a class="option-anchor" href="#option-cargo-uninstall---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-uninstall-+toolchain"><a class="option-anchor" href="#option-cargo-uninstall-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-uninstall---config"><a class="option-anchor" href="#option-cargo-uninstall---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-uninstall--C"><a class="option-anchor" href="#option-cargo-uninstall--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-uninstall--h"><a class="option-anchor" href="#option-cargo-uninstall--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-uninstall---help"><a class="option-anchor" href="#option-cargo-uninstall---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-uninstall--Z"><a class="option-anchor" href="#option-cargo-uninstall--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-install(1)](cargo-install.html) diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md new file mode 100644 index 0000000..c0ab4e9 --- /dev/null +++ b/src/doc/src/commands/cargo-update.md @@ -0,0 +1,196 @@ +# cargo-update(1) + +## NAME + +cargo-update --- Update dependencies as recorded in the local lock file + +## SYNOPSIS + +`cargo update` [_options_] + +## DESCRIPTION + +This command will update dependencies in the `Cargo.lock` file to the latest +version. If the `Cargo.lock` file does not exist, it will be created with the +latest available versions. + +## OPTIONS + +### Update Options + +<dl> + +<dt class="option-term" id="option-cargo-update--p"><a class="option-anchor" href="#option-cargo-update--p"></a><code>-p</code> <em>spec</em>…</dt> +<dt class="option-term" id="option-cargo-update---package"><a class="option-anchor" href="#option-cargo-update---package"></a><code>--package</code> <em>spec</em>…</dt> +<dd class="option-desc">Update only the specified packages. This flag may be specified +multiple times. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC format.</p> +<p>If packages are specified with the <code>-p</code> flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions.</p> +<p>If <code>-p</code> is not specified, all dependencies are updated.</dd> + + +<dt class="option-term" id="option-cargo-update---aggressive"><a class="option-anchor" href="#option-cargo-update---aggressive"></a><code>--aggressive</code></dt> +<dd class="option-desc">When used with <code>-p</code>, dependencies of <em>spec</em> are forced to update as well. +Cannot be used with <code>--precise</code>.</dd> + + +<dt class="option-term" id="option-cargo-update---precise"><a class="option-anchor" href="#option-cargo-update---precise"></a><code>--precise</code> <em>precise</em></dt> +<dd class="option-desc">When used with <code>-p</code>, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag).</dd> + + +<dt class="option-term" id="option-cargo-update--w"><a class="option-anchor" href="#option-cargo-update--w"></a><code>-w</code></dt> +<dt class="option-term" id="option-cargo-update---workspace"><a class="option-anchor" href="#option-cargo-update---workspace"></a><code>--workspace</code></dt> +<dd class="option-desc">Attempt to update only packages defined in the workspace. Other packages +are updated only if they don’t already exist in the lockfile. This +option is useful for updating <code>Cargo.lock</code> after you’ve changed version +numbers in <code>Cargo.toml</code>.</dd> + + +<dt class="option-term" id="option-cargo-update---dry-run"><a class="option-anchor" href="#option-cargo-update---dry-run"></a><code>--dry-run</code></dt> +<dd class="option-desc">Displays what would be updated, but doesn’t actually write the lockfile.</dd> + + +</dl> + +### Display Options + +<dl> +<dt class="option-term" id="option-cargo-update--v"><a class="option-anchor" href="#option-cargo-update--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-update---verbose"><a class="option-anchor" href="#option-cargo-update---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-update--q"><a class="option-anchor" href="#option-cargo-update--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-update---quiet"><a class="option-anchor" href="#option-cargo-update---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-update---color"><a class="option-anchor" href="#option-cargo-update---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-update---manifest-path"><a class="option-anchor" href="#option-cargo-update---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-update---frozen"><a class="option-anchor" href="#option-cargo-update---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-update---locked"><a class="option-anchor" href="#option-cargo-update---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-update---offline"><a class="option-anchor" href="#option-cargo-update---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-update-+toolchain"><a class="option-anchor" href="#option-cargo-update-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-update---config"><a class="option-anchor" href="#option-cargo-update---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-update--C"><a class="option-anchor" href="#option-cargo-update--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-update--h"><a class="option-anchor" href="#option-cargo-update--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-update---help"><a class="option-anchor" href="#option-cargo-update---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-update--Z"><a class="option-anchor" href="#option-cargo-update--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Update all dependencies in the lockfile: + + cargo update + +2. Update only specific dependencies: + + cargo update -p foo -p bar + +3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html) diff --git a/src/doc/src/commands/cargo-vendor.md b/src/doc/src/commands/cargo-vendor.md new file mode 100644 index 0000000..235ce5b --- /dev/null +++ b/src/doc/src/commands/cargo-vendor.md @@ -0,0 +1,193 @@ +# cargo-vendor(1) + +## NAME + +cargo-vendor --- Vendor all dependencies locally + +## SYNOPSIS + +`cargo vendor` [_options_] [_path_] + +## DESCRIPTION + +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at `<path>`. After this command completes +the vendor directory specified by `<path>` will contain all remote sources from +dependencies specified. Additional manifests beyond the default one can be +specified with the `-s` option. + +The `cargo vendor` command will also print out the configuration necessary +to use the vendored sources, which you will need to add to `.cargo/config.toml`. + +## OPTIONS + +### Vendor Options + +<dl> + +<dt class="option-term" id="option-cargo-vendor--s"><a class="option-anchor" href="#option-cargo-vendor--s"></a><code>-s</code> <em>manifest</em></dt> +<dt class="option-term" id="option-cargo-vendor---sync"><a class="option-anchor" href="#option-cargo-vendor---sync"></a><code>--sync</code> <em>manifest</em></dt> +<dd class="option-desc">Specify an extra <code>Cargo.toml</code> manifest to workspaces which should also be +vendored and synced to the output. May be specified multiple times.</dd> + + +<dt class="option-term" id="option-cargo-vendor---no-delete"><a class="option-anchor" href="#option-cargo-vendor---no-delete"></a><code>--no-delete</code></dt> +<dd class="option-desc">Don’t delete the “vendor” directory when vendoring, but rather keep all +existing contents of the vendor directory</dd> + + +<dt class="option-term" id="option-cargo-vendor---respect-source-config"><a class="option-anchor" href="#option-cargo-vendor---respect-source-config"></a><code>--respect-source-config</code></dt> +<dd class="option-desc">Instead of ignoring <code>[source]</code> configuration by default in <code>.cargo/config.toml</code> +read it and use it when downloading crates from crates.io, for example</dd> + + +<dt class="option-term" id="option-cargo-vendor---versioned-dirs"><a class="option-anchor" href="#option-cargo-vendor---versioned-dirs"></a><code>--versioned-dirs</code></dt> +<dd class="option-desc">Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the “vendor” directory +to be versioned, which makes it easier to track the history of vendored +packages over time, and can help with the performance of re-vendoring when +only a subset of the packages have changed.</dd> + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-vendor---manifest-path"><a class="option-anchor" href="#option-cargo-vendor---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-vendor---frozen"><a class="option-anchor" href="#option-cargo-vendor---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-vendor---locked"><a class="option-anchor" href="#option-cargo-vendor---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-vendor---offline"><a class="option-anchor" href="#option-cargo-vendor---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-vendor--v"><a class="option-anchor" href="#option-cargo-vendor--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-vendor---verbose"><a class="option-anchor" href="#option-cargo-vendor---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-vendor--q"><a class="option-anchor" href="#option-cargo-vendor--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-vendor---quiet"><a class="option-anchor" href="#option-cargo-vendor---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-vendor---color"><a class="option-anchor" href="#option-cargo-vendor---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-vendor-+toolchain"><a class="option-anchor" href="#option-cargo-vendor-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-vendor---config"><a class="option-anchor" href="#option-cargo-vendor---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-vendor--C"><a class="option-anchor" href="#option-cargo-vendor--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-vendor--h"><a class="option-anchor" href="#option-cargo-vendor--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-vendor---help"><a class="option-anchor" href="#option-cargo-vendor---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-vendor--Z"><a class="option-anchor" href="#option-cargo-vendor--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Vendor all dependencies into a local "vendor" folder + + cargo vendor + +2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +## SEE ALSO +[cargo(1)](cargo.html) + diff --git a/src/doc/src/commands/cargo-verify-project.md b/src/doc/src/commands/cargo-verify-project.md new file mode 100644 index 0000000..4f4f5b7 --- /dev/null +++ b/src/doc/src/commands/cargo-verify-project.md @@ -0,0 +1,153 @@ +# cargo-verify-project(1) + +## NAME + +cargo-verify-project --- Check correctness of crate manifest + +## SYNOPSIS + +`cargo verify-project` [_options_] + +## DESCRIPTION + +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +## OPTIONS + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-verify-project--v"><a class="option-anchor" href="#option-cargo-verify-project--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-verify-project---verbose"><a class="option-anchor" href="#option-cargo-verify-project---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-verify-project--q"><a class="option-anchor" href="#option-cargo-verify-project--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-verify-project---quiet"><a class="option-anchor" href="#option-cargo-verify-project---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-verify-project---color"><a class="option-anchor" href="#option-cargo-verify-project---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Manifest Options + +<dl> + +<dt class="option-term" id="option-cargo-verify-project---manifest-path"><a class="option-anchor" href="#option-cargo-verify-project---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> +<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the +<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> + + + +<dt class="option-term" id="option-cargo-verify-project---frozen"><a class="option-anchor" href="#option-cargo-verify-project---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo-verify-project---locked"><a class="option-anchor" href="#option-cargo-verify-project---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo-verify-project---offline"><a class="option-anchor" href="#option-cargo-verify-project---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-verify-project-+toolchain"><a class="option-anchor" href="#option-cargo-verify-project-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-verify-project---config"><a class="option-anchor" href="#option-cargo-verify-project---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-verify-project--C"><a class="option-anchor" href="#option-cargo-verify-project--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-verify-project--h"><a class="option-anchor" href="#option-cargo-verify-project--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-verify-project---help"><a class="option-anchor" href="#option-cargo-verify-project---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-verify-project--Z"><a class="option-anchor" href="#option-cargo-verify-project--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: The workspace is OK. +* `1`: The workspace is invalid. + +## EXAMPLES + +1. Check the current workspace for errors: + + cargo verify-project + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-package(1)](cargo-package.html) diff --git a/src/doc/src/commands/cargo-version.md b/src/doc/src/commands/cargo-version.md new file mode 100644 index 0000000..e9e12a0 --- /dev/null +++ b/src/doc/src/commands/cargo-version.md @@ -0,0 +1,42 @@ +# cargo-version(1) + +## NAME + +cargo-version --- Show version information + +## SYNOPSIS + +`cargo version` [_options_] + +## DESCRIPTION + +Displays the version of Cargo. + +## OPTIONS + +<dl> + +<dt class="option-term" id="option-cargo-version--v"><a class="option-anchor" href="#option-cargo-version--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-version---verbose"><a class="option-anchor" href="#option-cargo-version---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Display additional version information.</dd> + + +</dl> + +## EXAMPLES + +1. Display the version: + + cargo version + +2. The version is also available via flags: + + cargo --version + cargo -V + +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +[cargo(1)](cargo.html) diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md new file mode 100644 index 0000000..b87f7f2 --- /dev/null +++ b/src/doc/src/commands/cargo-yank.md @@ -0,0 +1,163 @@ +# cargo-yank(1) + +## NAME + +cargo-yank --- Remove a pushed crate from the index + +## SYNOPSIS + +`cargo yank` [_options_] _crate_@_version_\ +`cargo yank` [_options_] `--version` _version_ [_crate_] + +## DESCRIPTION + +The yank command removes a previously published crate's version from the +server's index. This command does not delete any data, and the crate will +still be available for download via the registry's download link. + +Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version. + +This command requires you to be authenticated with either the `--token` option +or using [cargo-login(1)](cargo-login.html). + +If the crate name is not specified, it will use the package name from the +current directory. + +## OPTIONS + +### Yank Options + +<dl> + +<dt class="option-term" id="option-cargo-yank---vers"><a class="option-anchor" href="#option-cargo-yank---vers"></a><code>--vers</code> <em>version</em></dt> +<dt class="option-term" id="option-cargo-yank---version"><a class="option-anchor" href="#option-cargo-yank---version"></a><code>--version</code> <em>version</em></dt> +<dd class="option-desc">The version to yank or un-yank.</dd> + + +<dt class="option-term" id="option-cargo-yank---undo"><a class="option-anchor" href="#option-cargo-yank---undo"></a><code>--undo</code></dt> +<dd class="option-desc">Undo a yank, putting a version back into the index.</dd> + + +<dt class="option-term" id="option-cargo-yank---token"><a class="option-anchor" href="#option-cargo-yank---token"></a><code>--token</code> <em>token</em></dt> +<dd class="option-desc">API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by <a href="cargo-login.html">cargo-login(1)</a>).</p> +<p><a href="../reference/config.html">Cargo config</a> environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment +variable. Tokens for other registries may be specified with environment +variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name +of the registry in all capital letters.</dd> + + + +<dt class="option-term" id="option-cargo-yank---index"><a class="option-anchor" href="#option-cargo-yank---index"></a><code>--index</code> <em>index</em></dt> +<dd class="option-desc">The URL of the registry index to use.</dd> + + + +<dt class="option-term" id="option-cargo-yank---registry"><a class="option-anchor" href="#option-cargo-yank---registry"></a><code>--registry</code> <em>registry</em></dt> +<dd class="option-desc">Name of the registry to use. Registry names are defined in <a href="../reference/config.html">Cargo config +files</a>. If not specified, the default registry is used, +which is defined by the <code>registry.default</code> config key which defaults to +<code>crates-io</code>.</dd> + + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo-yank--v"><a class="option-anchor" href="#option-cargo-yank--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo-yank---verbose"><a class="option-anchor" href="#option-cargo-yank---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-yank--q"><a class="option-anchor" href="#option-cargo-yank--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo-yank---quiet"><a class="option-anchor" href="#option-cargo-yank---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo-yank---color"><a class="option-anchor" href="#option-cargo-yank---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-yank-+toolchain"><a class="option-anchor" href="#option-cargo-yank-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo-yank---config"><a class="option-anchor" href="#option-cargo-yank---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo-yank--C"><a class="option-anchor" href="#option-cargo-yank--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo-yank--h"><a class="option-anchor" href="#option-cargo-yank--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo-yank---help"><a class="option-anchor" href="#option-cargo-yank---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo-yank--Z"><a class="option-anchor" href="#option-cargo-yank--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Yank a crate from the index: + + cargo yank foo@1.0.7 + +## SEE ALSO +[cargo(1)](cargo.html), [cargo-login(1)](cargo-login.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md new file mode 100644 index 0000000..716cd65 --- /dev/null +++ b/src/doc/src/commands/cargo.md @@ -0,0 +1,331 @@ +# cargo(1) + +## NAME + +cargo --- The Rust package manager + +## SYNOPSIS + +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ + +## DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at <https://rust-lang.org>. + +## COMMANDS + +### Build Commands + +[cargo-bench(1)](cargo-bench.html)\ + Execute benchmarks of a package. + +[cargo-build(1)](cargo-build.html)\ + Compile a package. + +[cargo-check(1)](cargo-check.html)\ + Check a local package and all of its dependencies for errors. + +[cargo-clean(1)](cargo-clean.html)\ + Remove artifacts that Cargo has generated in the past. + +[cargo-doc(1)](cargo-doc.html)\ + Build a package's documentation. + +[cargo-fetch(1)](cargo-fetch.html)\ + Fetch dependencies of a package from the network. + +[cargo-fix(1)](cargo-fix.html)\ + Automatically fix lint warnings reported by rustc. + +[cargo-run(1)](cargo-run.html)\ + Run a binary or example of the local package. + +[cargo-rustc(1)](cargo-rustc.html)\ + Compile a package, and pass extra options to the compiler. + +[cargo-rustdoc(1)](cargo-rustdoc.html)\ + Build a package's documentation, using specified custom flags. + +[cargo-test(1)](cargo-test.html)\ + Execute unit and integration tests of a package. + +### Manifest Commands + +[cargo-generate-lockfile(1)](cargo-generate-lockfile.html)\ + Generate `Cargo.lock` for a project. + +[cargo-locate-project(1)](cargo-locate-project.html)\ + Print a JSON representation of a `Cargo.toml` file's location. + +[cargo-metadata(1)](cargo-metadata.html)\ + Output the resolved dependencies of a package in machine-readable format. + +[cargo-pkgid(1)](cargo-pkgid.html)\ + Print a fully qualified package specification. + +[cargo-tree(1)](cargo-tree.html)\ + Display a tree visualization of a dependency graph. + +[cargo-update(1)](cargo-update.html)\ + Update dependencies as recorded in the local lock file. + +[cargo-vendor(1)](cargo-vendor.html)\ + Vendor all dependencies locally. + +[cargo-verify-project(1)](cargo-verify-project.html)\ + Check correctness of crate manifest. + +### Package Commands + +[cargo-init(1)](cargo-init.html)\ + Create a new Cargo package in an existing directory. + +[cargo-install(1)](cargo-install.html)\ + Build and install a Rust binary. + +[cargo-new(1)](cargo-new.html)\ + Create a new Cargo package. + +[cargo-search(1)](cargo-search.html)\ + Search packages in crates.io. + +[cargo-uninstall(1)](cargo-uninstall.html)\ + Remove a Rust binary. + +### Publishing Commands + +[cargo-login(1)](cargo-login.html)\ + Save an API token from the registry locally. + +[cargo-owner(1)](cargo-owner.html)\ + Manage the owners of a crate on the registry. + +[cargo-package(1)](cargo-package.html)\ + Assemble the local package into a distributable tarball. + +[cargo-publish(1)](cargo-publish.html)\ + Upload a package to the registry. + +[cargo-yank(1)](cargo-yank.html)\ + Remove a pushed crate from the index. + +### General Commands + +[cargo-help(1)](cargo-help.html)\ + Display help information about Cargo. + +[cargo-version(1)](cargo-version.html)\ + Show version information. + +## OPTIONS + +### Special Options + +<dl> + +<dt class="option-term" id="option-cargo--V"><a class="option-anchor" href="#option-cargo--V"></a><code>-V</code></dt> +<dt class="option-term" id="option-cargo---version"><a class="option-anchor" href="#option-cargo---version"></a><code>--version</code></dt> +<dd class="option-desc">Print version info and exit. If used with <code>--verbose</code>, prints extra +information.</dd> + + +<dt class="option-term" id="option-cargo---list"><a class="option-anchor" href="#option-cargo---list"></a><code>--list</code></dt> +<dd class="option-desc">List all installed Cargo subcommands. If used with <code>--verbose</code>, prints extra +information.</dd> + + +<dt class="option-term" id="option-cargo---explain"><a class="option-anchor" href="#option-cargo---explain"></a><code>--explain</code> <em>code</em></dt> +<dd class="option-desc">Run <code>rustc --explain CODE</code> which will print out a detailed explanation of an +error message (for example, <code>E0004</code>).</dd> + + +</dl> + +### Display Options + +<dl> + +<dt class="option-term" id="option-cargo--v"><a class="option-anchor" href="#option-cargo--v"></a><code>-v</code></dt> +<dt class="option-term" id="option-cargo---verbose"><a class="option-anchor" href="#option-cargo---verbose"></a><code>--verbose</code></dt> +<dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the <code>term.verbose</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo--q"><a class="option-anchor" href="#option-cargo--q"></a><code>-q</code></dt> +<dt class="option-term" id="option-cargo---quiet"><a class="option-anchor" href="#option-cargo---quiet"></a><code>--quiet</code></dt> +<dd class="option-desc">Do not print cargo log messages. +May also be specified with the <code>term.quiet</code> +<a href="../reference/config.html">config value</a>.</dd> + + +<dt class="option-term" id="option-cargo---color"><a class="option-anchor" href="#option-cargo---color"></a><code>--color</code> <em>when</em></dt> +<dd class="option-desc">Control when colored output is used. Valid values:</p> +<ul> +<li><code>auto</code> (default): Automatically detect if color support is available on the +terminal.</li> +<li><code>always</code>: Always display colors.</li> +<li><code>never</code>: Never display colors.</li> +</ul> +<p>May also be specified with the <code>term.color</code> +<a href="../reference/config.html">config value</a>.</dd> + + + +</dl> + +### Manifest Options + +<dl> +<dt class="option-term" id="option-cargo---frozen"><a class="option-anchor" href="#option-cargo---frozen"></a><code>--frozen</code></dt> +<dt class="option-term" id="option-cargo---locked"><a class="option-anchor" href="#option-cargo---locked"></a><code>--locked</code></dt> +<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The <code>--frozen</code> flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.</p> +<p>These may be used in environments where you want to assert that the +<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network +access.</dd> + + +<dt class="option-term" id="option-cargo---offline"><a class="option-anchor" href="#option-cargo---offline"></a><code>--offline</code></dt> +<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.</p> +<p>Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going +offline.</p> +<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> + + +</dl> + +### Common Options + +<dl> + +<dt class="option-term" id="option-cargo-+toolchain"><a class="option-anchor" href="#option-cargo-+toolchain"></a><code>+</code><em>toolchain</em></dt> +<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> +begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such +as <code>+stable</code> or <code>+nightly</code>). +See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> +for more information about how toolchain overrides work.</dd> + + +<dt class="option-term" id="option-cargo---config"><a class="option-anchor" href="#option-cargo---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> +<dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> + + +<dt class="option-term" id="option-cargo--C"><a class="option-anchor" href="#option-cargo--C"></a><code>-C</code> <em>PATH</em></dt> +<dd class="option-desc">Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as +the directories searched for discovering <code>.cargo/config.toml</code>, for example.</p> +<p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly +channel</a> and +requires the <code>-Z unstable-options</code> flag to enable (see +<a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> + + +<dt class="option-term" id="option-cargo--h"><a class="option-anchor" href="#option-cargo--h"></a><code>-h</code></dt> +<dt class="option-term" id="option-cargo---help"><a class="option-anchor" href="#option-cargo---help"></a><code>--help</code></dt> +<dd class="option-desc">Prints help information.</dd> + + +<dt class="option-term" id="option-cargo--Z"><a class="option-anchor" href="#option-cargo--Z"></a><code>-Z</code> <em>flag</em></dt> +<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> + + +</dl> + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## FILES + +`~/.cargo/`\ + Default location for Cargo's "home" directory where it +stores various files. The location can be changed with the `CARGO_HOME` +environment variable. + +`$CARGO_HOME/bin/`\ + Binaries installed by [cargo-install(1)](cargo-install.html) will be located here. If using +[rustup], executables distributed with Rust are also located here. + +`$CARGO_HOME/config.toml`\ + The global configuration file. See [the reference](../reference/config.html) +for more information about configuration files. + +`.cargo/config.toml`\ + Cargo automatically searches for a file named `.cargo/config.toml` in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. + +`$CARGO_HOME/credentials.toml`\ + Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ + This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ + This directory contains cached downloads of git dependencies. + +Please note that the internal structure of the `$CARGO_HOME` directory is not +stable yet and may be subject to change. + +[rustup]: https://rust-lang.github.io/rustup/ + +## EXAMPLES + +1. Build a local package and all of its dependencies: + + cargo build + +2. Build a package with optimizations: + + cargo build --release + +3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +4. Create a new package that builds an executable: + + cargo new foobar + +5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +6. Learn about a command's options and usage: + + cargo help clean + +## BUGS + +See <https://github.com/rust-lang/cargo/issues> for issues. + +## SEE ALSO +[rustc(1)](https://doc.rust-lang.org/rustc/index.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/general-commands.md b/src/doc/src/commands/general-commands.md new file mode 100644 index 0000000..eaad4fb --- /dev/null +++ b/src/doc/src/commands/general-commands.md @@ -0,0 +1,4 @@ +# General Commands +* [cargo](cargo.md) +* [cargo help](cargo-help.md) +* [cargo version](cargo-version.md) diff --git a/src/doc/src/commands/index.md b/src/doc/src/commands/index.md new file mode 100644 index 0000000..362a53e --- /dev/null +++ b/src/doc/src/commands/index.md @@ -0,0 +1,6 @@ +# Cargo Commands +* [General Commands](general-commands.md) +* [Build Commands](build-commands.md) +* [Manifest Commands](manifest-commands.md) +* [Package Commands](package-commands.md) +* [Publishing Commands](publishing-commands.md) diff --git a/src/doc/src/commands/manifest-commands.md b/src/doc/src/commands/manifest-commands.md new file mode 100644 index 0000000..98a82d8 --- /dev/null +++ b/src/doc/src/commands/manifest-commands.md @@ -0,0 +1,11 @@ +# Manifest Commands +* [cargo add](cargo-add.md) +* [cargo generate-lockfile](cargo-generate-lockfile.md) +* [cargo locate-project](cargo-locate-project.md) +* [cargo metadata](cargo-metadata.md) +* [cargo pkgid](cargo-pkgid.md) +* [cargo remove](cargo-remove.md) +* [cargo tree](cargo-tree.md) +* [cargo update](cargo-update.md) +* [cargo vendor](cargo-vendor.md) +* [cargo verify-project](cargo-verify-project.md) diff --git a/src/doc/src/commands/package-commands.md b/src/doc/src/commands/package-commands.md new file mode 100644 index 0000000..783abaf --- /dev/null +++ b/src/doc/src/commands/package-commands.md @@ -0,0 +1,6 @@ +# Package Commands +* [cargo init](cargo-init.md) +* [cargo install](cargo-install.md) +* [cargo new](cargo-new.md) +* [cargo search](cargo-search.md) +* [cargo uninstall](cargo-uninstall.md) diff --git a/src/doc/src/commands/publishing-commands.md b/src/doc/src/commands/publishing-commands.md new file mode 100644 index 0000000..372faad --- /dev/null +++ b/src/doc/src/commands/publishing-commands.md @@ -0,0 +1,6 @@ +# Publishing Commands +* [cargo login](cargo-login.md) +* [cargo owner](cargo-owner.md) +* [cargo package](cargo-package.md) +* [cargo publish](cargo-publish.md) +* [cargo yank](cargo-yank.md) diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md new file mode 100644 index 0000000..8a8840b --- /dev/null +++ b/src/doc/src/faq.md @@ -0,0 +1,261 @@ +## Frequently Asked Questions + +### Is the plan to use GitHub as a package repository? + +No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with +[npmjs.com][1] and [rubygems.org][3]. + +We plan to support git repositories as a source of packages forever, +because they can be used for early development and temporary patches, +even when people use the registry as the primary source of packages. + +### Why build crates.io rather than use GitHub as a registry? + +We think that it’s very important to support multiple ways to download +packages, including downloading from GitHub and copying packages into +your package itself. + +That said, we think that [crates.io] offers a number of important benefits, and +will likely become the primary way that people download packages in Cargo. + +For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a +central registry model as well as a Git-based model, and most packages +are downloaded through the registry in those ecosystems, with an +important minority of packages making use of git-based packages. + +[1]: https://www.npmjs.com +[2]: https://bundler.io +[3]: https://rubygems.org + +Some of the advantages that make a central registry popular in other +languages include: + +* **Discoverability**. A central registry provides an easy place to look + for existing packages. Combined with tagging, this also makes it + possible for a registry to provide ecosystem-wide information, such as a + list of the most popular or most-depended-on packages. +* **Speed**. A central registry makes it possible to easily fetch just + the metadata for packages quickly and efficiently, and then to + efficiently download just the published package, and not other bloat + that happens to exist in the repository. This adds up to a significant + improvement in the speed of dependency resolution and fetching. As + dependency graphs scale up, downloading all of the git repositories bogs + down fast. Also remember that not everybody has a high-speed, + low-latency Internet connection. + +### Will Cargo work with C code (or other languages)? + +Yes! + +Cargo handles compiling Rust code, but we know that many Rust packages +link against C code. We also know that there are decades of tooling +built up around compiling languages other than Rust. + +Our solution: Cargo allows a package to [specify a script](reference/build-scripts.md) +(written in Rust) to run before invoking `rustc`. Rust is leveraged to +implement platform-specific configuration and refactor out common build +functionality among packages. + +### Can Cargo be used inside of `make` (or `ninja`, or ...) + +Indeed. While we intend Cargo to be useful as a standalone way to +compile Rust packages at the top-level, we know that some people will +want to invoke Cargo from other build tools. + +We have designed Cargo to work well in those contexts, paying attention +to things like error codes and machine-readable output modes. We still +have some work to do on those fronts, but using Cargo in the context of +conventional scripts is something we designed for from the beginning and +will continue to prioritize. + +### Does Cargo handle multi-platform packages or cross-compilation? + +Rust itself provides facilities for configuring sections of code based +on the platform. Cargo also supports [platform-specific +dependencies][target-deps], and we plan to support more per-platform +configuration in `Cargo.toml` in the future. + +[target-deps]: reference/specifying-dependencies.md#platform-specific-dependencies + +In the longer-term, we’re looking at ways to conveniently cross-compile +packages using Cargo. + +### Does Cargo support environments, like `production` or `test`? + +We support environments through the use of [profiles] to support: + +[profiles]: reference/profiles.md + +* environment-specific flags (like `-g --opt-level=0` for development + and `--opt-level=3` for production). +* environment-specific dependencies (like `hamcrest` for test assertions). +* environment-specific `#[cfg]` +* a `cargo test` command + +### Does Cargo work on Windows? + +Yes! + +All commits to Cargo are required to pass the local test suite on Windows. +If you encounter an issue while running on Windows, we consider it a bug, so [please file an +issue][3]. + +[3]: https://github.com/rust-lang/cargo/issues + +### Why do binaries have `Cargo.lock` in version control, but not libraries? + +The purpose of a `Cargo.lock` lockfile is to describe the state of the world at +the time of a successful build. Cargo uses the lockfile to provide +deterministic builds on different times and different systems, by ensuring that +the exact same dependencies and versions are used as when the `Cargo.lock` file +was originally generated. + +This property is most desirable from applications and packages which are at the +very end of the dependency chain (binaries). As a result, it is recommended that +all binaries check in their `Cargo.lock`. + +For libraries the situation is somewhat different. A library is not only used by +the library developers, but also any downstream consumers of the library. Users +dependent on the library will not inspect the library’s `Cargo.lock` (even if it +exists). This is precisely because a library should **not** be deterministically +recompiled for all users of the library. + +If a library ends up being used transitively by several dependencies, it’s +likely that just a single copy of the library is desired (based on semver +compatibility). If Cargo used all of the dependencies' `Cargo.lock` files, +then multiple copies of the library could be used, and perhaps even a version +conflict. + +In other words, libraries specify SemVer requirements for their dependencies but +cannot see the full picture. Only end products like binaries have a full +picture to decide what versions of dependencies should be used. + +### Can libraries use `*` as a version for their dependencies? + +**As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries) +with wildcard dependency constraints.** + +While libraries _can_, strictly speaking, they should not. A version requirement +of `*` says “This will work with every version ever”, which is never going +to be true. Libraries should always specify the range that they do work with, +even if it’s something as general as “every 1.x.y version”. + +### Why `Cargo.toml`? + +As one of the most frequent interactions with Cargo, the question of why the +configuration file is named `Cargo.toml` arises from time to time. The leading +capital-`C` was chosen to ensure that the manifest was grouped with other +similar configuration files in directory listings. Sorting files often puts +capital letters before lowercase letters, ensuring files like `Makefile` and +`Cargo.toml` are placed together. The trailing `.toml` was chosen to emphasize +the fact that the file is in the [TOML configuration +format](https://toml.io/). + +Cargo does not allow other names such as `cargo.toml` or `Cargofile` to +emphasize the ease of how a Cargo repository can be identified. An option of +many possible names has historically led to confusion where one case was handled +but others were accidentally forgotten. + +[crates.io]: https://crates.io/ + +### How can Cargo work offline? + +Cargo is often used in situations with limited or no network access such as +airplanes, CI environments, or embedded in large production deployments. Users +are often surprised when Cargo attempts to fetch resources from the network, and +hence the request for Cargo to work offline comes up frequently. + +Cargo, at its heart, will not attempt to access the network unless told to do +so. That is, if no crates come from crates.io, a git repository, or some other +network location, Cargo will never attempt to make a network connection. As a +result, if Cargo attempts to touch the network, then it's because it needs to +fetch a required resource. + +Cargo is also quite aggressive about caching information to minimize the amount +of network activity. It will guarantee, for example, that if `cargo build` (or +an equivalent) is run to completion then the next `cargo build` is guaranteed to +not touch the network so long as `Cargo.toml` has not been modified in the +meantime. This avoidance of the network boils down to a `Cargo.lock` existing +and a populated cache of the crates reflected in the lock file. If either of +these components are missing, then they're required for the build to succeed and +must be fetched remotely. + +As of Rust 1.11.0, Cargo understands a new flag, `--frozen`, which is an +assertion that it shouldn't touch the network. When passed, Cargo will +immediately return an error if it would otherwise attempt a network request. +The error should include contextual information about why the network request is +being made in the first place to help debug as well. Note that this flag *does +not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch +the network as a previous command has been run to ensure that network activity +shouldn't be necessary. + +The `--offline` flag was added in Rust 1.36.0. This flag tells Cargo to not +access the network, and try to proceed with available cached data if possible. +You can use [`cargo fetch`] in one project to download dependencies before +going offline, and then use those same dependencies in another project with +the `--offline` flag (or [configuration value][offline config]). + +For more information about vendoring, see documentation on [source +replacement][replace]. + +[replace]: reference/source-replacement.md +[`cargo fetch`]: commands/cargo-fetch.md +[offline config]: reference/config.md#netoffline + +### Why is Cargo rebuilding my code? + +Cargo is responsible for incrementally compiling crates in your project. This +means that if you type `cargo build` twice the second one shouldn't rebuild your +crates.io dependencies, for example. Nevertheless bugs arise and Cargo can +sometimes rebuild code when you're not expecting it! + +We've long [wanted to provide better diagnostics about +this](https://github.com/rust-lang/cargo/issues/2904) but unfortunately haven't +been able to make progress on that issue in quite some time. In the meantime, +however, you can debug a rebuild at least a little by setting the `CARGO_LOG` +environment variable: + +```sh +$ CARGO_LOG=cargo::core::compiler::fingerprint=info cargo build +``` + +This will cause Cargo to print out a lot of information about diagnostics and +rebuilding. This can often contain clues as to why your project is getting +rebuilt, although you'll often need to connect some dots yourself since this +output isn't super easy to read just yet. Note that the `CARGO_LOG` needs to be +set for the command that rebuilds when you think it should not. Unfortunately +Cargo has no way right now of after-the-fact debugging "why was that rebuilt?" + +Some issues we've seen historically which can cause crates to get rebuilt are: + +* A build script prints `cargo:rerun-if-changed=foo` where `foo` is a file that + doesn't exist and nothing generates it. In this case Cargo will keep running + the build script thinking it will generate the file but nothing ever does. The + fix is to avoid printing `rerun-if-changed` in this scenario. + +* Two successive Cargo builds may differ in the set of features enabled for some + dependencies. For example if the first build command builds the whole + workspace and the second command builds only one crate, this may cause a + dependency on crates.io to have a different set of features enabled, causing + it and everything that depends on it to get rebuilt. There's unfortunately not + really a great fix for this, although if possible it's best to have the set of + features enabled on a crate constant regardless of what you're building in + your workspace. + +* Some filesystems exhibit unusual behavior around timestamps. Cargo primarily + uses timestamps on files to govern whether rebuilding needs to happen, but if + you're using a nonstandard filesystem it may be affecting the timestamps + somehow (e.g. truncating them, causing them to drift, etc). In this scenario, + feel free to open an issue and we can see if we can accommodate the filesystem + somehow. + +* A concurrent build process is either deleting artifacts or modifying files. + Sometimes you might have a background process that either tries to build or + check your project. These background processes might surprisingly delete some + build artifacts or touch files (or maybe just by accident), which can cause + rebuilds to look spurious! The best fix here would be to wrangle the + background process to avoid clashing with your work. + +If after trying to debug your issue, however, you're still running into problems +then feel free to [open an +issue](https://github.com/rust-lang/cargo/issues/new)! diff --git a/src/doc/src/getting-started/first-steps.md b/src/doc/src/getting-started/first-steps.md new file mode 100644 index 0000000..15bb4bd --- /dev/null +++ b/src/doc/src/getting-started/first-steps.md @@ -0,0 +1,82 @@ +## First Steps with Cargo + +This section provides a quick sense for the `cargo` command line tool. We +demonstrate its ability to generate a new [***package***][def-package] for us, +its ability to compile the [***crate***][def-crate] within the package, and +its ability to run the resulting program. + +To start a new package with Cargo, use `cargo new`: + +```console +$ cargo new hello_world +``` + +Cargo defaults to `--bin` to make a binary program. To make a library, we +would pass `--lib`, instead. + +Let’s check out what Cargo has generated for us: + +```console +$ cd hello_world +$ tree . +. +├── Cargo.toml +└── src + └── main.rs + +1 directory, 2 files +``` + +This is all we need to get started. First, let’s check out `Cargo.toml`: + +```toml +[package] +name = "hello_world" +version = "0.1.0" +edition = "2021" + +[dependencies] +``` + +This is called a [***manifest***][def-manifest], and it contains all of the +metadata that Cargo needs to compile your package. + +Here’s what’s in `src/main.rs`: + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Cargo generated a “hello world” program for us, otherwise known as a +[***binary crate***][def-crate]. Let’s compile it: + +```console +$ cargo build + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) +``` + +And then run it: + +```console +$ ./target/debug/hello_world +Hello, world! +``` + +We can also use `cargo run` to compile and then run it, all in one step: + +```console +$ cargo run + Fresh hello_world v0.1.0 (file:///path/to/package/hello_world) + Running `target/hello_world` +Hello, world! +``` + +### Going further + +For more details on using Cargo, check out the [Cargo Guide](../guide/index.md) + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' diff --git a/src/doc/src/getting-started/index.md b/src/doc/src/getting-started/index.md new file mode 100644 index 0000000..710e994 --- /dev/null +++ b/src/doc/src/getting-started/index.md @@ -0,0 +1,9 @@ +## Getting Started + +To get started with Cargo, install Cargo (and Rust) and set up your first +[*crate*][def-crate]. + +* [Installation](installation.md) +* [First steps with Cargo](first-steps.md) + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' diff --git a/src/doc/src/getting-started/installation.md b/src/doc/src/getting-started/installation.md new file mode 100644 index 0000000..7cccf9e --- /dev/null +++ b/src/doc/src/getting-started/installation.md @@ -0,0 +1,38 @@ +## Installation + +### Install Rust and Cargo + +The easiest way to get Cargo is to install the current stable release of [Rust] +by using [rustup]. Installing Rust using `rustup` will also install `cargo`. + +On Linux and macOS systems, this is done as follows: + +```console +curl https://sh.rustup.rs -sSf | sh +``` + +It will download a script, and start the installation. If everything goes well, +you’ll see this appear: + +```console +Rust is installed now. Great! +``` + +On Windows, download and run [rustup-init.exe]. It will start the installation +in a console and present the above message on success. + +After this, you can use the `rustup` command to also install `beta` or `nightly` +channels for Rust and Cargo. + +For other installation options and information, visit the +[install][install-rust] page of the Rust website. + +### Build and Install Cargo from Source + +Alternatively, you can [build Cargo from source][compiling-from-source]. + +[rust]: https://www.rust-lang.org/ +[rustup]: https://rustup.rs/ +[rustup-init.exe]: https://win.rustup.rs/ +[install-rust]: https://www.rust-lang.org/tools/install +[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md new file mode 100644 index 0000000..a79b41d --- /dev/null +++ b/src/doc/src/guide/build-cache.md @@ -0,0 +1,108 @@ +## Build cache + +Cargo stores the output of a build into the "target" directory. By default, +this is the directory named `target` in the root of your +[*workspace*][def-workspace]. To change the location, you can set the +`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config +value, or the `--target-dir` command-line flag. + +The directory layout depends on whether or not you are using the `--target` +flag to build for a specific platform. If `--target` is not specified, Cargo +runs in a mode where it builds for the host architecture. The output goes into +the root of the target directory, with each [profile] stored in a separate +subdirectory: + +Directory | Description +----------|------------ +<code style="white-space: nowrap">target/debug/</code> | Contains output for the `dev` profile. +<code style="white-space: nowrap">target/release/</code> | Contains output for the `release` profile (with the `--release` option). +<code style="white-space: nowrap">target/foo/</code> | Contains build output for the `foo` profile (with the `--profile=foo` option). + +For historical reasons, the `dev` and `test` profiles are stored in the +`debug` directory, and the `release` and `bench` profiles are stored in the +`release` directory. User-defined profiles are stored in a directory with the +same name as the profile. + +When building for another target with `--target`, the output is placed in a +directory with the name of the [target]: + +Directory | Example +----------|-------- +<code style="white-space: nowrap">target/<triple>/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code> +<code style="white-space: nowrap">target/<triple>/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code> + +> **Note**: When not using `--target`, this has a consequence that Cargo will +> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`] +> will be shared with every `rustc` invocation. With the `--target` flag, +> build scripts and proc macros are built separately (for the host +> architecture), and do not share `RUSTFLAGS`. + +Within the profile directory (such as `debug` or `release`), artifacts are +placed into the following directories: + +Directory | Description +----------|------------ +<code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the [binary executables] and [library targets]). +<code style="white-space: nowrap">target/debug/examples/</code> | Contains [example targets]. + +Some commands place their output in dedicated directories in the top level of +the `target` directory: + +Directory | Description +----------|------------ +<code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]). +<code style="white-space: nowrap">target/package/</code> | Contains the output of the [`cargo package`] and [`cargo publish`] commands. + +Cargo also creates several other directories and files needed for the build +process. Their layout is considered internal to Cargo, and is subject to +change. Some of these directories are: + +Directory | Description +----------|------------ +<code style="white-space: nowrap">target/debug/deps/</code> | Dependencies and other artifacts. +<code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds. +<code style="white-space: nowrap">target/debug/build/</code> | Output from [build scripts]. + +### Dep-info files + +Next to each compiled artifact is a file called a "dep info" file with a `.d` +suffix. This file is a Makefile-like syntax that indicates all of the file +dependencies required to rebuild the artifact. These are intended to be used +with external build systems so that they can detect if Cargo needs to be +re-executed. The paths in the file are absolute by default. See the +[`build.dep-info-basedir`] config option to use relative paths. + +```Makefile +# Example dep-info file found in target/debug/foo.d +/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs +``` + +### Shared cache + +A third party tool, [sccache], can be used to share built dependencies across +different workspaces. + +To setup `sccache`, install it with `cargo install sccache` and set +`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If +you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to +`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo +configuration][config]. Refer to sccache documentation for more details. + +[`RUSTFLAGS`]: ../reference/config.md#buildrustflags +[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir +[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper +[`build.target-dir`]: ../reference/config.md#buildtarget-dir +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo publish`]: ../commands/cargo-publish.md +[build scripts]: ../reference/build-scripts.md +[config]: ../reference/config.md +[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' +[target]: ../appendix/glossary.md#target '"target" (glossary entry)' +[environment variable]: ../reference/environment-variables.md +[incremental output]: ../reference/profiles.md#incremental +[sccache]: https://github.com/mozilla/sccache +[profile]: ../reference/profiles.md +[binary executables]: ../reference/cargo-targets.md#binaries +[library targets]: ../reference/cargo-targets.md#library +[example targets]: ../reference/cargo-targets.md#examples diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md new file mode 100644 index 0000000..9e6740f --- /dev/null +++ b/src/doc/src/guide/cargo-home.md @@ -0,0 +1,93 @@ +## Cargo Home + +The "Cargo home" functions as a download and source cache. +When building a [crate][def-crate], Cargo stores downloaded build dependencies in the Cargo home. +You can alter the location of the Cargo home by setting the `CARGO_HOME` [environmental variable][env]. +The [home](https://crates.io/crates/home) crate provides an API for getting this location if you need this information inside your Rust crate. +By default, the Cargo home is located in `$HOME/.cargo/`. + +Please note that the internal structure of the Cargo home is not stabilized and may be subject to change at any time. + +The Cargo home consists of following components: + +## Files: + +* `config.toml` + Cargo's global configuration file, see the [config entry in the reference][config]. + +* `credentials.toml` + Private login credentials from [`cargo login`] in order to log in to a [registry][def-registry]. + +* `.crates.toml`, `.crates2.json` + These hidden files contain [package][def-package] information of crates installed via [`cargo install`]. Do NOT edit by hand! + +## Directories: + +* `bin` +The bin directory contains executables of crates that were installed via [`cargo install`] or [`rustup`](https://rust-lang.github.io/rustup/). +To be able to make these binaries accessible, add the path of the directory to your `$PATH` environment variable. + + * `git` + Git sources are stored here: + + * `git/db` + When a crate depends on a git repository, Cargo clones the repo as a bare repo into this directory and updates it if necessary. + + * `git/checkouts` + 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. + This provides the compiler with the actual files contained in the repo of the commit specified for that dependency. + Multiple checkouts of different commits of the same repo are possible. + +* `registry` + Packages and metadata of crate registries (such as [crates.io](https://crates.io/)) are located here. + + * `registry/index` + The index is a bare git repository which contains the metadata (versions, dependencies etc) of all available crates of a registry. + + * `registry/cache` + Downloaded dependencies are stored in the cache. The crates are compressed gzip archives named with a `.crate` extension. + + * `registry/src` + If a downloaded `.crate` archive is required by a package, it is unpacked into `registry/src` folder where rustc will find the `.rs` files. + + +## Caching the Cargo home in CI + +To avoid redownloading all crate dependencies during continuous integration, you can cache the `$CARGO_HOME` directory. +However, caching the entire directory is often inefficient as it will contain downloaded sources twice. +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`. +That can unnecessarily slow down the build as downloading, extracting, recompressing and reuploading the cache to the CI servers can take some time. + +If you wish to cache binaries installed with [`cargo install`], you need to cache the `bin/` folder and the `.crates.toml` and `.crates2.json` files. + +It should be sufficient to cache the following files and directories across builds: + +* `.crates.toml` +* `.crates2.json` +* `bin/` +* `registry/index/` +* `registry/cache/` +* `git/db/` + + + +## Vendoring all dependencies of a project + +See the [`cargo vendor`] subcommand. + + + +## Clearing the cache + +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. + +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. + +[`cargo install`]: ../commands/cargo-install.md +[`cargo login`]: ../commands/cargo-login.md +[`cargo vendor`]: ../commands/cargo-vendor.md +[config]: ../reference/config.md +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' +[env]: ../reference/environment-variables.md diff --git a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md new file mode 100644 index 0000000..9b04266 --- /dev/null +++ b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md @@ -0,0 +1,107 @@ +## Cargo.toml vs Cargo.lock + +`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk +about them, here’s a summary: + +* `Cargo.toml` is about describing your dependencies in a broad sense, and is + written by you. +* `Cargo.lock` contains exact information about your dependencies. It is + maintained by Cargo and should not be manually edited. + +If you’re building a non-end product, such as a rust library that other rust +[packages][def-package] will depend on, put `Cargo.lock` in your +`.gitignore`. If you’re building an end product, which are executable like +command-line tool or an application, or a system library with crate-type of +`staticlib` or `cdylib`, check `Cargo.lock` into `git`. If you're curious +about why that is, see +["Why do binaries have `Cargo.lock` in version control, but not libraries?" in the +FAQ](../faq.md#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). + +Let’s dig in a little bit more. + +`Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a +bunch of different metadata about our package. For example, we can say that we +depend on another package: + +```toml +[package] +name = "hello_world" +version = "0.1.0" + +[dependencies] +regex = { git = "https://github.com/rust-lang/regex.git" } +``` + +This package has a single dependency, on the `regex` library. We’ve stated in +this case that we’re relying on a particular Git repository that lives on +GitHub. Since we haven’t specified any other information, Cargo assumes that +we intend to use the latest commit on the `master` branch to build our package. + +Sound good? Well, there’s one problem: If you build this package today, and +then you send a copy to me, and I build this package tomorrow, something bad +could happen. There could be more commits to `regex` in the meantime, and my +build would include new commits while yours would not. Therefore, we would +get different builds. This would be bad because we want reproducible builds. + +We could fix this problem by defining a specific `rev` value in our `Cargo.toml`, +so Cargo could know exactly which revision to use when building the package: + +```toml +[dependencies] +regex = { git = "https://github.com/rust-lang/regex.git", rev = "9f9f693" } +``` + +Now our builds will be the same. But there’s a big drawback: now we have to +manually think about SHA-1s every time we want to update our library. This is +both tedious and error prone. + +Enter the `Cargo.lock`. Because of its existence, we don’t need to manually +keep track of the exact revisions: Cargo will do it for us. When we have a +manifest like this: + +```toml +[package] +name = "hello_world" +version = "0.1.0" + +[dependencies] +regex = { git = "https://github.com/rust-lang/regex.git" } +``` + +Cargo will take the latest commit and write that information out into our +`Cargo.lock` when we build for the first time. That file will look like this: + +```toml +[[package]] +name = "hello_world" +version = "0.1.0" +dependencies = [ + "regex 1.5.0 (git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831)", +] + +[[package]] +name = "regex" +version = "1.5.0" +source = "git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831" +``` + +You can see that there’s a lot more information here, including the exact +revision we used to build. Now when you give your package to someone else, +they’ll use the exact same SHA, even though we didn’t specify it in our +`Cargo.toml`. + +When we’re ready to opt in to a new version of the library, Cargo can +re-calculate the dependencies and update things for us: + +```console +$ cargo update # updates all dependencies +$ cargo update -p regex # updates just “regex” +``` + +This will write out a new `Cargo.lock` with the new version information. Note +that the argument to `cargo update` is actually a +[Package ID Specification](../reference/pkgid-spec.md) and `regex` is just a +short specification. + +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' diff --git a/src/doc/src/guide/continuous-integration.md b/src/doc/src/guide/continuous-integration.md new file mode 100644 index 0000000..38d8ae2 --- /dev/null +++ b/src/doc/src/guide/continuous-integration.md @@ -0,0 +1,125 @@ +## Continuous Integration + +### Travis CI + +To test your [package][def-package] on Travis CI, here is a sample +`.travis.yml` file: + +```yaml +language: rust +rust: + - stable + - beta + - nightly +matrix: + allow_failures: + - rust: nightly +``` + +This will test all three release channels, but any breakage in nightly +will not fail your overall build. Please see the [Travis CI Rust +documentation](https://docs.travis-ci.com/user/languages/rust/) for more +information. + +### GitHub Actions + +To test your package on GitHub Actions, here is a sample `.github/workflows/ci.yml` file: + +```yaml +name: Cargo Build & Test + +on: + push: + pull_request: + +env: + CARGO_TERM_COLOR: always + +jobs: + build_and_test: + name: Rust project - latest + runs-on: ubuntu-latest + strategy: + matrix: + toolchain: + - stable + - beta + - nightly + steps: + - uses: actions/checkout@v3 + - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }} + - run: cargo build --verbose + - run: cargo test --verbose + +``` + +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. + +### GitLab CI + +To test your package on GitLab CI, here is a sample `.gitlab-ci.yml` file: + +```yaml +stages: + - build + +rust-latest: + stage: build + image: rust:latest + script: + - cargo build --verbose + - cargo test --verbose + +rust-nightly: + stage: build + image: rustlang/rust:nightly + script: + - cargo build --verbose + - cargo test --verbose + allow_failure: true +``` + +This will test on the stable channel and nightly channel, but any +breakage in nightly will not fail your overall build. Please see the +[GitLab CI documentation](https://docs.gitlab.com/ce/ci/yaml/index.html) for more +information. + +### builds.sr.ht + +To test your package on sr.ht, here is a sample `.build.yml` file. +Be sure to change `<your repo>` and `<your project>` to the repo to clone and +the directory where it was cloned. + +```yaml +image: archlinux +packages: + - rustup +sources: + - <your repo> +tasks: + - setup: | + rustup toolchain install nightly stable + cd <your project>/ + rustup run stable cargo fetch + - stable: | + rustup default stable + cd <your project>/ + cargo build --verbose + cargo test --verbose + - nightly: | + rustup default nightly + cd <your project>/ + cargo build --verbose ||: + cargo test --verbose ||: + - docs: | + cd <your project>/ + rustup run stable cargo doc --no-deps + rustup run nightly cargo doc --no-deps ||: +``` + +This will test and build documentation on the stable channel and nightly +channel, but any breakage in nightly will not fail your overall build. Please +see the [builds.sr.ht documentation](https://man.sr.ht/builds.sr.ht/) for more +information. + +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' diff --git a/src/doc/src/guide/creating-a-new-project.md b/src/doc/src/guide/creating-a-new-project.md new file mode 100644 index 0000000..e0daefc --- /dev/null +++ b/src/doc/src/guide/creating-a-new-project.md @@ -0,0 +1,97 @@ +## Creating a New Package + +To start a new [package][def-package] with Cargo, use `cargo new`: + +```console +$ cargo new hello_world --bin +``` + +We’re passing `--bin` because we’re making a binary program: if we +were making a library, we’d pass `--lib`. This also initializes a new `git` +repository by default. If you don't want it to do that, pass `--vcs none`. + +Let’s check out what Cargo has generated for us: + +```console +$ cd hello_world +$ tree . +. +├── Cargo.toml +└── src + └── main.rs + +1 directory, 2 files +``` + +Let’s take a closer look at `Cargo.toml`: + +```toml +[package] +name = "hello_world" +version = "0.1.0" +edition = "2021" + +[dependencies] + +``` + +This is called a [***manifest***][def-manifest], and it contains all of the +metadata that Cargo needs to compile your package. This file is written in the +[TOML] format (pronounced /tɑməl/). + +Here’s what’s in `src/main.rs`: + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Cargo generated a “hello world” program for us, otherwise known as a +[*binary crate*][def-crate]. Let’s compile it: + +```console +$ cargo build + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) +``` + +And then run it: + +```console +$ ./target/debug/hello_world +Hello, world! +``` + +We can also use `cargo run` to compile and then run it, all in one step (You +won't see the `Compiling` line if you have not made any changes since you last +compiled): + +```console +$ cargo run + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) + Running `target/debug/hello_world` +Hello, world! +``` + +You’ll now notice a new file, `Cargo.lock`. It contains information about our +dependencies. Since we don’t have any yet, it’s not very interesting. + +Once you’re ready for release, you can use `cargo build --release` to compile +your files with optimizations turned on: + +```console +$ cargo build --release + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) +``` + +`cargo build --release` puts the resulting binary in `target/release` instead of +`target/debug`. + +Compiling in debug mode is the default for development. Compilation time is +shorter since the compiler doesn't do optimizations, but the code will run +slower. Release mode takes longer to compile, but the code will run faster. + +[TOML]: https://toml.io/ +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md new file mode 100644 index 0000000..94419f1 --- /dev/null +++ b/src/doc/src/guide/dependencies.md @@ -0,0 +1,93 @@ +## Dependencies + +[crates.io] is the Rust community's central [*package registry*][def-package-registry] +that serves as a location to discover and download +[packages][def-package]. `cargo` is configured to use it by default to find +requested packages. + +To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. + +[crates.io]: https://crates.io/ + +### Adding a dependency + +If your `Cargo.toml` doesn't already have a `[dependencies]` section, add +that, then list the [crate][def-crate] name and version that you would like to +use. This example adds a dependency of the `time` crate: + +```toml +[dependencies] +time = "0.1.12" +``` + +The version string is a [SemVer] version requirement. The [specifying +dependencies](../reference/specifying-dependencies.md) docs have more information about +the options you have here. + +[SemVer]: https://semver.org + +If we also wanted to add a dependency on the `regex` crate, we would not need +to add `[dependencies]` for each crate listed. Here's what your whole +`Cargo.toml` file would look like with dependencies on the `time` and `regex` +crates: + +```toml +[package] +name = "hello_world" +version = "0.1.0" +edition = "2021" + +[dependencies] +time = "0.1.12" +regex = "0.1.41" +``` + +Re-run `cargo build`, and Cargo will fetch the new dependencies and all of +their dependencies, compile them all, and update the `Cargo.lock`: + +```console +$ cargo build + Updating crates.io index + Downloading memchr v0.1.5 + Downloading libc v0.1.10 + Downloading regex-syntax v0.2.1 + Downloading memchr v0.1.5 + Downloading aho-corasick v0.3.0 + Downloading regex v0.1.41 + Compiling memchr v0.1.5 + Compiling libc v0.1.10 + Compiling regex-syntax v0.2.1 + Compiling memchr v0.1.5 + Compiling aho-corasick v0.3.0 + Compiling regex v0.1.41 + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) +``` + +Our `Cargo.lock` contains the exact information about which revision of all of +these dependencies we used. + +Now, if `regex` gets updated, we will still build with the same revision until +we choose to `cargo update`. + +You can now use the `regex` library in `main.rs`. + +```rust,ignore +use regex::Regex; + +fn main() { + let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap(); + println!("Did our date match? {}", re.is_match("2014-01-01")); +} +``` + +Running it will show: + +```console +$ cargo run + Running `target/hello_world` +Did our date match? true +``` + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-package-registry]: ../appendix/glossary.md#package-registry '"package-registry" (glossary entry)' diff --git a/src/doc/src/guide/index.md b/src/doc/src/guide/index.md new file mode 100644 index 0000000..fe6d86a --- /dev/null +++ b/src/doc/src/guide/index.md @@ -0,0 +1,15 @@ +## Cargo Guide + +This guide will give you all that you need to know about how to use Cargo to +develop Rust packages. + +* [Why Cargo Exists](why-cargo-exists.md) +* [Creating a New Package](creating-a-new-project.md) +* [Working on an Existing Cargo Package](working-on-an-existing-project.md) +* [Dependencies](dependencies.md) +* [Package Layout](project-layout.md) +* [Cargo.toml vs Cargo.lock](cargo-toml-vs-cargo-lock.md) +* [Tests](tests.md) +* [Continuous Integration](continuous-integration.md) +* [Cargo Home](cargo-home.md) +* [Build Cache](build-cache.md) diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md new file mode 100644 index 0000000..a3ce3f8 --- /dev/null +++ b/src/doc/src/guide/project-layout.md @@ -0,0 +1,61 @@ +## Package Layout + +Cargo uses conventions for file placement to make it easy to dive into a new +Cargo [package][def-package]: + +```text +. +├── Cargo.lock +├── Cargo.toml +├── src/ +│ ├── lib.rs +│ ├── main.rs +│ └── bin/ +│ ├── named-executable.rs +│ ├── another-executable.rs +│ └── multi-file-executable/ +│ ├── main.rs +│ └── some_module.rs +├── benches/ +│ ├── large-input.rs +│ └── multi-file-bench/ +│ ├── main.rs +│ └── bench_module.rs +├── examples/ +│ ├── simple.rs +│ └── multi-file-example/ +│ ├── main.rs +│ └── ex_module.rs +└── tests/ + ├── some-integration-tests.rs + └── multi-file-test/ + ├── main.rs + └── test_module.rs +``` + +* `Cargo.toml` and `Cargo.lock` are stored in the root of your package (*package + root*). +* Source code goes in the `src` directory. +* The default library file is `src/lib.rs`. +* The default executable file is `src/main.rs`. + * Other executables can be placed in `src/bin/`. +* Benchmarks go in the `benches` directory. +* Examples go in the `examples` directory. +* Integration tests go in the `tests` directory. + +If a binary, example, bench, or integration test consists of multiple source +files, place a `main.rs` file along with the extra [*modules*][def-module] +within a subdirectory of the `src/bin`, `examples`, `benches`, or `tests` +directory. The name of the executable will be the directory name. + +You can learn more about Rust's module system in [the book][book-modules]. + +See [Configuring a target] for more details on manually configuring targets. +See [Target auto-discovery] for more information on controlling how Cargo +automatically infers target names. + +[book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html +[Configuring a target]: ../reference/cargo-targets.md#configuring-a-target +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-module]: ../appendix/glossary.md#module '"module" (glossary entry)' +[Target auto-discovery]: ../reference/cargo-targets.md#target-auto-discovery diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md new file mode 100644 index 0000000..402e8e3 --- /dev/null +++ b/src/doc/src/guide/tests.md @@ -0,0 +1,44 @@ +## Tests + +Cargo can run your tests with the `cargo test` command. Cargo looks for tests +to run in two places: in each of your `src` files and any tests in `tests/`. +Tests in your `src` files should be unit tests and [documentation tests]. +Tests in `tests/` should be integration-style tests. As such, you’ll need to +import your crates into the files in `tests`. + +Here's an example of running `cargo test` in our [package][def-package], which +currently has no tests: + +```console +$ cargo test + Compiling regex v1.5.0 (https://github.com/rust-lang/regex.git#9f9f693) + Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) + Running target/test/hello_world-9c2b65bbb79eabce + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out +``` + +If our package had tests, we would see more output with the correct number of +tests. + +You can also run a specific test by passing a filter: + +```console +$ cargo test foo +``` + +This will run any test with `foo` in its name. + +`cargo test` runs additional checks as well. It will compile any examples +you’ve included to ensure they still compile. It also runs documentation +tests to ensure your code samples from documentation comments compile. +Please see the [testing guide][testing] in the Rust documentation for a general +view of writing and organizing tests. See [Cargo Targets: Tests] to learn more +about different styles of tests in Cargo. + +[documentation tests]: ../../rustdoc/write-documentation/documentation-tests.html +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[testing]: ../../book/ch11-00-testing.html +[Cargo Targets: Tests]: ../reference/cargo-targets.html#tests diff --git a/src/doc/src/guide/why-cargo-exists.md b/src/doc/src/guide/why-cargo-exists.md new file mode 100644 index 0000000..02b222f --- /dev/null +++ b/src/doc/src/guide/why-cargo-exists.md @@ -0,0 +1,65 @@ +## Why Cargo Exists + +### Preliminaries + +In Rust, as you may know, a library or executable program is called a +[*crate*][def-crate]. Crates are compiled using the Rust compiler, +`rustc`. When starting with Rust, the first source code most people encounter +is that of the venerable “hello world” program, which they compile by invoking +`rustc` directly: + +```console +$ rustc hello.rs +$ ./hello +Hello, world! +``` + +Note that the above command required that we specify the file name +explicitly. If we were to directly use `rustc` to compile a different program, +a different command line invocation would be required. If we needed to specify +any specific compiler flags or include external dependencies, then the +needed command would be even more specific (and elaborate). + +Furthermore, most non-trivial programs will likely have dependencies on +external libraries, and will therefore also depend transitively on *their* +dependencies. Obtaining the correct versions of all the necessary dependencies +and keeping them up to date would be laborious and error-prone if done by +hand. + +Rather than work only with crates and `rustc`, we can avoid the manual tedium +involved with performing the above tasks by introducing a higher-level +["*package*"][def-package] abstraction and by using a +[*package manager*][def-package-manager]. + +### Enter: Cargo + +*Cargo* is the Rust package manager. It is a tool that allows Rust +[*packages*][def-package] to declare their various dependencies and ensure +that you’ll always get a repeatable build. + +To accomplish this goal, Cargo does four things: + +* Introduces two metadata files with various bits of package information. +* Fetches and builds your package’s dependencies. +* Invokes `rustc` or another build tool with the correct parameters to build + your package. +* Introduces conventions to make working with Rust packages easier. + +To a large extent, Cargo normalizes the commands needed to build a given +program or library; this is one aspect to the above mentioned conventions. As +we show later, the same command can be used to build different +[*artifacts*][def-artifact], regardless of their names. Rather than invoke +`rustc` directly, we can instead invoke something generic such as `cargo +build` and let cargo worry about constructing the correct `rustc` +invocation. Furthermore, Cargo will automatically fetch from a +[*registry*][def-registry] any dependencies we have defined for our artifact, +and arrange for them to be incorporated into our build as needed. + +It is only a slight exaggeration to say that once you know how to build one +Cargo-based project, you know how to build *all* of them. + +[def-artifact]: ../appendix/glossary.md#artifact '"artifact" (glossary entry)' +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-package-manager]: ../appendix/glossary.md#package-manager '"package manager" (glossary entry)' +[def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' diff --git a/src/doc/src/guide/working-on-an-existing-project.md b/src/doc/src/guide/working-on-an-existing-project.md new file mode 100644 index 0000000..f9c26cd --- /dev/null +++ b/src/doc/src/guide/working-on-an-existing-project.md @@ -0,0 +1,24 @@ +## Working on an Existing Cargo Package + +If you download an existing [package][def-package] that uses Cargo, it’s +really easy to get going. + +First, get the package from somewhere. In this example, we’ll use `regex` +cloned from its repository on GitHub: + +```console +$ git clone https://github.com/rust-lang/regex.git +$ cd regex +``` + +To build, use `cargo build`: + +```console +$ cargo build + Compiling regex v1.5.0 (file:///path/to/package/regex) +``` + +This will fetch all of the dependencies and then build them, along with the +package. + +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' diff --git a/src/doc/src/images/Cargo-Logo-Small.png b/src/doc/src/images/Cargo-Logo-Small.png Binary files differnew file mode 100644 index 0000000..e3a9920 --- /dev/null +++ b/src/doc/src/images/Cargo-Logo-Small.png diff --git a/src/doc/src/images/auth-level-acl.png b/src/doc/src/images/auth-level-acl.png Binary files differnew file mode 100644 index 0000000..e7bc251 --- /dev/null +++ b/src/doc/src/images/auth-level-acl.png diff --git a/src/doc/src/images/org-level-acl.png b/src/doc/src/images/org-level-acl.png Binary files differnew file mode 100644 index 0000000..ed5aa88 --- /dev/null +++ b/src/doc/src/images/org-level-acl.png diff --git a/src/doc/src/images/winapi-features.svg b/src/doc/src/images/winapi-features.svg new file mode 100644 index 0000000..32327ad --- /dev/null +++ b/src/doc/src/images/winapi-features.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="501px" height="151px" viewBox="-0.5 -0.5 501 151"><defs/><g><rect x="170" y="30" width="90" height="30" rx="4.5" ry="4.5" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 45px; margin-left: 171px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><font style="font-size: 16px"><b>foo</b></font></div></div></div></foreignObject><text x="215" y="49" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">foo</text></switch></g><rect x="170" y="90" width="90" height="30" rx="4.5" ry="4.5" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 105px; margin-left: 171px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><font style="font-size: 16px"><b>bar</b></font></div></div></div></foreignObject><text x="215" y="109" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">bar</text></switch></g><rect x="400" y="10" width="90" height="130" rx="13.5" ry="13.5" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 75px; margin-left: 401px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-size: 16px" align="center"><b>winapi</b></div><div align="left"><br /></div><div align="left">features:</div><div align="left">• fileapi<br />• handleapi<br />• std<div>• winnt<br /></div></div></div></div></div></foreignObject><text x="445" y="79" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">winapi...</text></switch></g><path d="M 260 45 L 360 45 Q 370 45 377.07 52.07 L 395.5 70.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 399.21 74.21 L 391.78 71.73 L 395.5 70.5 L 396.73 66.78 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 46px; margin-left: 319px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">fileapi, handleapi</div></div></div></foreignObject><text x="319" y="49" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">fileapi, handleapi</text></switch></g><path d="M 260 105 L 360 105 Q 370 105 377.07 97.93 L 395.5 79.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 399.21 75.79 L 396.73 83.22 L 395.5 79.5 L 391.78 78.27 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 106px; margin-left: 319px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">std, winnt</div></div></div></foreignObject><text x="319" y="109" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">std, winnt</text></switch></g><rect x="10" y="55" width="110" height="35" rx="5.25" ry="5.25" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 73px; margin-left: 11px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-size: 16px"><b>my-package</b></div></div></div></div></foreignObject><text x="65" y="76" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">my-package</text></switch></g><path d="M 120 72.5 L 134.12 53.09 Q 140 45 150 45 L 163.63 45" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 168.88 45 L 161.88 48.5 L 163.63 45 L 161.88 41.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 120 72.5 L 134.76 96.48 Q 140 105 150 105 L 163.63 105" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 168.88 105 L 161.88 108.5 L 163.63 105 L 161.88 101.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/src/doc/src/index.md b/src/doc/src/index.md new file mode 100644 index 0000000..223600c --- /dev/null +++ b/src/doc/src/index.md @@ -0,0 +1,49 @@ +# The Cargo Book + + + +Cargo is the [Rust] [*package manager*][def-package-manager]. Cargo downloads your Rust [package][def-package]'s +dependencies, compiles your packages, makes distributable packages, and uploads them to +[crates.io], the Rust community’s [*package registry*][def-package-registry]. You can contribute +to this book on [GitHub]. + + +### Sections + +**[Getting Started](getting-started/index.md)** + +To get started with Cargo, install Cargo (and Rust) and set up your first +[*crate*][def-crate]. + +**[Cargo Guide](guide/index.md)** + +The guide will give you all you need to know about how to use Cargo to develop +Rust packages. + +**[Cargo Reference](reference/index.md)** + +The reference covers the details of various areas of Cargo. + +**[Cargo Commands](commands/index.md)** + +The commands will let you interact with Cargo using its command-line interface. + +**[Frequently Asked Questions](faq.md)** + +**Appendices:** +* [Glossary](appendix/glossary.md) +* [Git Authentication](appendix/git-authentication.md) + +**Other Documentation:** +* [Changelog](https://github.com/rust-lang/cargo/blob/master/CHANGELOG.md) + --- Detailed notes about changes in Cargo in each release. +* [Rust documentation website](https://doc.rust-lang.org/) --- Links to official + Rust documentation and tools. + +[def-crate]: ./appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ./appendix/glossary.md#package '"package" (glossary entry)' +[def-package-manager]: ./appendix/glossary.md#package-manager '"package manager" (glossary entry)' +[def-package-registry]: ./appendix/glossary.md#package-registry '"package registry" (glossary entry)' +[rust]: https://www.rust-lang.org/ +[crates.io]: https://crates.io/ +[GitHub]: https://github.com/rust-lang/cargo/tree/master/src/doc diff --git a/src/doc/src/reference/build-script-examples.md b/src/doc/src/reference/build-script-examples.md new file mode 100644 index 0000000..5e8fae5 --- /dev/null +++ b/src/doc/src/reference/build-script-examples.md @@ -0,0 +1,506 @@ +## Build Script Examples + +The following sections illustrate some examples of writing build scripts. + +Some common build script functionality can be found via crates on [crates.io]. +Check out the [`build-dependencies` +keyword](https://crates.io/keywords/build-dependencies) to see what is +available. The following is a sample of some popular crates[^†]: + +* [`bindgen`](https://crates.io/crates/bindgen) --- Automatically generate Rust + FFI bindings to C libraries. +* [`cc`](https://crates.io/crates/cc) --- Compiles C/C++/assembly. +* [`pkg-config`](https://crates.io/crates/pkg-config) --- Detect system + libraries using the `pkg-config` utility. +* [`cmake`](https://crates.io/crates/cmake) --- Runs the `cmake` build tool to build a native library. +* [`autocfg`](https://crates.io/crates/autocfg), + [`rustc_version`](https://crates.io/crates/rustc_version), + [`version_check`](https://crates.io/crates/version_check) --- These crates + provide ways to implement conditional compilation based on the current + `rustc` such as the version of the compiler. + +[^†]: This list is not an endorsement. Evaluate your dependencies to see which +is right for your project. + +### Code generation + +Some Cargo packages need to have code generated just before they are compiled +for various reasons. Here we’ll walk through a simple example which generates a +library call as part of the build script. + +First, let’s take a look at the directory structure of this package: + +```text +. +├── Cargo.toml +├── build.rs +└── src + └── main.rs + +1 directory, 3 files +``` + +Here we can see that we have a `build.rs` build script and our binary in +`main.rs`. This package has a basic manifest: + +```toml +# Cargo.toml + +[package] +name = "hello-from-generated-code" +version = "0.1.0" +edition = "2021" +``` + +Let’s see what’s inside the build script: + +```rust,no_run +// build.rs + +use std::env; +use std::fs; +use std::path::Path; + +fn main() { + let out_dir = env::var_os("OUT_DIR").unwrap(); + let dest_path = Path::new(&out_dir).join("hello.rs"); + fs::write( + &dest_path, + "pub fn message() -> &'static str { + \"Hello, World!\" + } + " + ).unwrap(); + println!("cargo:rerun-if-changed=build.rs"); +} +``` + +There’s a couple of points of note here: + +* The script uses the `OUT_DIR` environment variable to discover where the + output files should be located. It can use the process’ current working + directory to find where the input files should be located, but in this case we + don’t have any input files. +* In general, build scripts should not modify any files outside of `OUT_DIR`. + It may seem fine on the first blush, but it does cause problems when you use + such crate as a dependency, because there's an *implicit* invariant that + sources in `.cargo/registry` should be immutable. `cargo` won't allow such + scripts when packaging. +* This script is relatively simple as it just writes out a small generated file. + One could imagine that other more fanciful operations could take place such as + generating a Rust module from a C header file or another language definition, + for example. +* The [`rerun-if-changed` instruction](build-scripts.md#rerun-if-changed) + tells Cargo that the build script only needs to re-run if the build script + itself changes. Without this line, Cargo will automatically run the build + script if any file in the package changes. If your code generation uses some + input files, this is where you would print a list of each of those files. + +Next, let’s peek at the library itself: + +```rust,ignore +// src/main.rs + +include!(concat!(env!("OUT_DIR"), "/hello.rs")); + +fn main() { + println!("{}", message()); +} +``` + +This is where the real magic happens. The library is using the rustc-defined +[`include!` macro][include-macro] in combination with the +[`concat!`][concat-macro] and [`env!`][env-macro] macros to include the +generated file (`hello.rs`) into the crate’s compilation. + +Using the structure shown here, crates can include any number of generated files +from the build script itself. + +[include-macro]: ../../std/macro.include.html +[concat-macro]: ../../std/macro.concat.html +[env-macro]: ../../std/macro.env.html + +### Building a native library + +Sometimes it’s necessary to build some native C or C++ code as part of a +package. This is another excellent use case of leveraging the build script to +build a native library before the Rust crate itself. As an example, we’ll create +a Rust library which calls into C to print “Hello, World!”. + +Like above, let’s first take a look at the package layout: + +```text +. +├── Cargo.toml +├── build.rs +└── src + ├── hello.c + └── main.rs + +1 directory, 4 files +``` + +Pretty similar to before! Next, the manifest: + +```toml +# Cargo.toml + +[package] +name = "hello-world-from-c" +version = "0.1.0" +edition = "2021" +``` + +For now we’re not going to use any build dependencies, so let’s take a look at +the build script now: + +```rust,no_run +// build.rs + +use std::process::Command; +use std::env; +use std::path::Path; + +fn main() { + let out_dir = env::var("OUT_DIR").unwrap(); + + // Note that there are a number of downsides to this approach, the comments + // below detail how to improve the portability of these commands. + Command::new("gcc").args(&["src/hello.c", "-c", "-fPIC", "-o"]) + .arg(&format!("{}/hello.o", out_dir)) + .status().unwrap(); + Command::new("ar").args(&["crus", "libhello.a", "hello.o"]) + .current_dir(&Path::new(&out_dir)) + .status().unwrap(); + + println!("cargo:rustc-link-search=native={}", out_dir); + println!("cargo:rustc-link-lib=static=hello"); + println!("cargo:rerun-if-changed=src/hello.c"); +} +``` + +This build script starts out by compiling our C file into an object file (by +invoking `gcc`) and then converting this object file into a static library (by +invoking `ar`). The final step is feedback to Cargo itself to say that our +output was in `out_dir` and the compiler should link the crate to `libhello.a` +statically via the `-l static=hello` flag. + +Note that there are a number of drawbacks to this hard-coded approach: + +* The `gcc` command itself is not portable across platforms. For example it’s + unlikely that Windows platforms have `gcc`, and not even all Unix platforms + may have `gcc`. The `ar` command is also in a similar situation. +* These commands do not take cross-compilation into account. If we’re cross + compiling for a platform such as Android it’s unlikely that `gcc` will produce + an ARM executable. + +Not to fear, though, this is where a `build-dependencies` entry would help! +The Cargo ecosystem has a number of packages to make this sort of task much +easier, portable, and standardized. Let's try the [`cc` +crate](https://crates.io/crates/cc) from [crates.io]. First, add it to the +`build-dependencies` in `Cargo.toml`: + +```toml +[build-dependencies] +cc = "1.0" +``` + +And rewrite the build script to use this crate: + +```rust,ignore +// build.rs + +fn main() { + cc::Build::new() + .file("src/hello.c") + .compile("hello"); + println!("cargo:rerun-if-changed=src/hello.c"); +} +``` + +The [`cc` crate] abstracts a range of build script requirements for C code: + +* It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc` + for Unix platforms, etc.). +* It takes the `TARGET` variable into account by passing appropriate flags to + the compiler being used. +* Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all + handled automatically. +* The stdout output and `OUT_DIR` locations are also handled by the `cc` + library. + +Here we can start to see some of the major benefits of farming as much +functionality as possible out to common build dependencies rather than +duplicating logic across all build scripts! + +Back to the case study though, let’s take a quick look at the contents of the +`src` directory: + +```c +// src/hello.c + +#include <stdio.h> + +void hello() { + printf("Hello, World!\n"); +} +``` + +```rust,ignore +// src/main.rs + +// Note the lack of the `#[link]` attribute. We’re delegating the responsibility +// of selecting what to link over to the build script rather than hard-coding +// it in the source file. +extern { fn hello(); } + +fn main() { + unsafe { hello(); } +} +``` + +And there we go! This should complete our example of building some C code from a +Cargo package using the build script itself. This also shows why using a build +dependency can be crucial in many situations and even much more concise! + +We’ve also seen a brief example of how a build script can use a crate as a +dependency purely for the build process and not for the crate itself at runtime. + +[`cc` crate]: https://crates.io/crates/cc + +### Linking to system libraries + +This example demonstrates how to link a system library and how the build +script is used to support this use case. + +Quite frequently a Rust crate wants to link to a native library provided on +the system to bind its functionality or just use it as part of an +implementation detail. This is quite a nuanced problem when it comes to +performing this in a platform-agnostic fashion. It is best, if possible, to +farm out as much of this as possible to make this as easy as possible for +consumers. + +For this example, we will be creating a binding to the system's zlib library. +This is a library that is commonly found on most Unix-like systems that +provides data compression. This is already wrapped up in the [`libz-sys` +crate], but for this example, we'll do an extremely simplified version. Check +out [the source code][libz-source] for the full example. + +To make it easy to find the location of the library, we will use the +[`pkg-config` crate]. This crate uses the system's `pkg-config` utility to +discover information about a library. It will automatically tell Cargo what is +needed to link the library. This will likely only work on Unix-like systems +with `pkg-config` installed. Let's start by setting up the manifest: + +```toml +# Cargo.toml + +[package] +name = "libz-sys" +version = "0.1.0" +edition = "2021" +links = "z" + +[build-dependencies] +pkg-config = "0.3.16" +``` + +Take note that we included the `links` key in the `package` table. This tells +Cargo that we are linking to the `libz` library. See ["Using another sys +crate"](#using-another-sys-crate) for an example that will leverage this. + +The build script is fairly simple: + +```rust,ignore +// build.rs + +fn main() { + pkg_config::Config::new().probe("zlib").unwrap(); + println!("cargo:rerun-if-changed=build.rs"); +} +``` + +Let's round out the example with a basic FFI binding: + +```rust,ignore +// src/lib.rs + +use std::os::raw::{c_uint, c_ulong}; + +extern "C" { + pub fn crc32(crc: c_ulong, buf: *const u8, len: c_uint) -> c_ulong; +} + +#[test] +fn test_crc32() { + let s = "hello"; + unsafe { + assert_eq!(crc32(0, s.as_ptr(), s.len() as c_uint), 0x3610a686); + } +} +``` + +Run `cargo build -vv` to see the output from the build script. On a system +with `libz` already installed, it may look something like this: + +```text +[libz-sys 0.1.0] cargo:rustc-link-search=native=/usr/lib +[libz-sys 0.1.0] cargo:rustc-link-lib=z +[libz-sys 0.1.0] cargo:rerun-if-changed=build.rs +``` + +Nice! `pkg-config` did all the work of finding the library and telling Cargo +where it is. + +It is not unusual for packages to include the source for the library, and +build it statically if it is not found on the system, or if a feature or +environment variable is set. For example, the real [`libz-sys` crate] checks the +environment variable `LIBZ_SYS_STATIC` or the `static` feature to build it +from source instead of using the system library. Check out [the +source][libz-source] for a more complete example. + +[`libz-sys` crate]: https://crates.io/crates/libz-sys +[`pkg-config` crate]: https://crates.io/crates/pkg-config +[libz-source]: https://github.com/rust-lang/libz-sys + +### Using another `sys` crate + +When using the `links` key, crates may set metadata that can be read by other +crates that depend on it. This provides a mechanism to communicate information +between crates. In this example, we'll be creating a C library that makes use +of zlib from the real [`libz-sys` crate]. + +If you have a C library that depends on zlib, you can leverage the [`libz-sys` +crate] to automatically find it or build it. This is great for cross-platform +support, such as Windows where zlib is not usually installed. `libz-sys` [sets +the `include` +metadata](https://github.com/rust-lang/libz-sys/blob/3c594e677c79584500da673f918c4d2101ac97a1/build.rs#L156) +to tell other packages where to find the header files for zlib. Our build +script can read that metadata with the `DEP_Z_INCLUDE` environment variable. +Here's an example: + +```toml +# Cargo.toml + +[package] +name = "zuser" +version = "0.1.0" +edition = "2021" + +[dependencies] +libz-sys = "1.0.25" + +[build-dependencies] +cc = "1.0.46" +``` + +Here we have included `libz-sys` which will ensure that there is only one +`libz` used in the final library, and give us access to it from our build +script: + +```rust,ignore +// build.rs + +fn main() { + let mut cfg = cc::Build::new(); + cfg.file("src/zuser.c"); + if let Some(include) = std::env::var_os("DEP_Z_INCLUDE") { + cfg.include(include); + } + cfg.compile("zuser"); + println!("cargo:rerun-if-changed=src/zuser.c"); +} +``` + +With `libz-sys` doing all the heavy lifting, the C source code may now include +the zlib header, and it should find the header, even on systems where it isn't +already installed. + +```c +// src/zuser.c + +#include "zlib.h" + +// … rest of code that makes use of zlib. +``` + +### Conditional compilation + +A build script may emit [`rustc-cfg` instructions] which can enable conditions +that can be checked at compile time. In this example, we'll take a look at how +the [`openssl` crate] uses this to support multiple versions of the OpenSSL +library. + +The [`openssl-sys` crate] implements building and linking the OpenSSL library. +It supports multiple different implementations (like LibreSSL) and multiple +versions. It makes use of the `links` key so that it may pass information to +other build scripts. One of the things it passes is the `version_number` key, +which is the version of OpenSSL that was detected. The code in the build +script looks something [like +this](https://github.com/sfackler/rust-openssl/blob/dc72a8e2c429e46c275e528b61a733a66e7877fc/openssl-sys/build/main.rs#L216): + +```rust,ignore +println!("cargo:version_number={:x}", openssl_version); +``` + +This instruction causes the `DEP_OPENSSL_VERSION_NUMBER` environment variable +to be set in any crates that directly depend on `openssl-sys`. + +The `openssl` crate, which provides the higher-level interface, specifies +`openssl-sys` as a dependency. The `openssl` build script can read the +version information generated by the `openssl-sys` build script with the +`DEP_OPENSSL_VERSION_NUMBER` environment variable. It uses this to generate +some [`cfg` +values](https://github.com/sfackler/rust-openssl/blob/dc72a8e2c429e46c275e528b61a733a66e7877fc/openssl/build.rs#L18-L36): + +```rust,ignore +// (portion of build.rs) + +if let Ok(version) = env::var("DEP_OPENSSL_VERSION_NUMBER") { + let version = u64::from_str_radix(&version, 16).unwrap(); + + if version >= 0x1_00_01_00_0 { + println!("cargo:rustc-cfg=ossl101"); + } + if version >= 0x1_00_02_00_0 { + println!("cargo:rustc-cfg=ossl102"); + } + if version >= 0x1_01_00_00_0 { + println!("cargo:rustc-cfg=ossl110"); + } + if version >= 0x1_01_00_07_0 { + println!("cargo:rustc-cfg=ossl110g"); + } + if version >= 0x1_01_01_00_0 { + println!("cargo:rustc-cfg=ossl111"); + } +} +``` + +These `cfg` values can then be used with the [`cfg` attribute] or the [`cfg` +macro] to conditionally include code. For example, SHA3 support was added in +OpenSSL 1.1.1, so it is [conditionally +excluded](https://github.com/sfackler/rust-openssl/blob/dc72a8e2c429e46c275e528b61a733a66e7877fc/openssl/src/hash.rs#L67-L85) +for older versions: + +```rust,ignore +// (portion of openssl crate) + +#[cfg(ossl111)] +pub fn sha3_224() -> MessageDigest { + unsafe { MessageDigest(ffi::EVP_sha3_224()) } +} +``` + +Of course, one should be careful when using this, since it makes the resulting +binary even more dependent on the build environment. In this example, if the +binary is distributed to another system, it may not have the exact same shared +libraries, which could cause problems. + +[`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute +[`cfg` macro]: ../../std/macro.cfg.html +[`rustc-cfg` instructions]: build-scripts.md#rustc-cfg +[`openssl` crate]: https://crates.io/crates/openssl +[`openssl-sys` crate]: https://crates.io/crates/openssl-sys + +[crates.io]: https://crates.io/ diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md new file mode 100644 index 0000000..00023b6 --- /dev/null +++ b/src/doc/src/reference/build-scripts.md @@ -0,0 +1,485 @@ +## Build Scripts + +Some packages need to compile third-party non-Rust code, for example C +libraries. Other packages need to link to C libraries which can either be +located on the system or possibly need to be built from source. Others still +need facilities for functionality such as code generation before building (think +parser generators). + +Cargo does not aim to replace other tools that are well-optimized for these +tasks, but it does integrate with them with custom build scripts. Placing a +file named `build.rs` in the root of a package will cause Cargo to compile +that script and execute it just before building the package. + +```rust,ignore +// Example custom build script. +fn main() { + // Tell Cargo that if the given file changes, to rerun this build script. + println!("cargo:rerun-if-changed=src/hello.c"); + // Use the `cc` crate to build a C file and statically link it. + cc::Build::new() + .file("src/hello.c") + .compile("hello"); +} +``` + +Some example use cases of build scripts are: + +* Building a bundled C library. +* Finding a C library on the host system. +* Generating a Rust module from a specification. +* Performing any platform-specific configuration needed for the crate. + +The sections below describe how build scripts work, and the [examples +chapter](build-script-examples.md) shows a variety of examples on how to write +scripts. + +> Note: The [`package.build` manifest key](manifest.md#package-build) can be +> used to change the name of the build script, or disable it entirely. + +### Life Cycle of a Build Script + +Just before a package is built, Cargo will compile a build script into an +executable (if it has not already been built). It will then run the script, +which may perform any number of tasks. The script may communicate with Cargo +by printing specially formatted commands prefixed with `cargo:` to stdout. + +The build script will be rebuilt if any of its source files or dependencies +change. + +By default, Cargo will re-run the build script if any of the files in the +package changes. Typically it is best to use the `rerun-if` commands, +described in the [change detection](#change-detection) section below, to +narrow the focus of what triggers a build script to run again. + +Once the build script successfully finishes executing, the rest of the package +will be compiled. Scripts should exit with a non-zero exit code to halt the +build if there is an error, in which case the build script's output will be +displayed on the terminal. + +### Inputs to the Build Script + +When the build script is run, there are a number of inputs to the build script, +all passed in the form of [environment variables][build-env]. + +In addition to environment variables, the build script’s current directory is +the source directory of the build script’s package. + +[build-env]: environment-variables.md#environment-variables-cargo-sets-for-build-scripts + +### Outputs of the Build Script + +Build scripts may save any output files or intermediate artifacts in the +directory specified in the [`OUT_DIR` environment variable][build-env]. Scripts +should not modify any files outside of that directory. + +Build scripts communicate with Cargo by printing to stdout. Cargo will +interpret each line that starts with `cargo:` as an instruction that will +influence compilation of the package. All other lines are ignored. + +> Note: The order of `cargo:` instructions printed by the build script *may* +> affect the order of arguments that `cargo` passes to `rustc`. In turn, the +> order of arguments passed to `rustc` may affect the order of arguments passed +> to the linker. Therefore, you will want to pay attention to the order of the +> build script's instructions. For example, if object `foo` needs to link against +> library `bar`, you may want to make sure that library `bar`'s +> [`cargo:rustc-link-lib`](#rustc-link-lib) instruction appears *after* +> instructions to link object `foo`. + +The output of the script is hidden from the terminal during normal +compilation. If you would like to see the output directly in your terminal, +invoke Cargo as "very verbose" with the `-vv` flag. This only happens when the +build script is run. If Cargo determines nothing has changed, it will not +re-run the script, see [change detection](#change-detection) below for more. + +All the lines printed to stdout by a build script are written to a file like +`target/debug/build/<pkg>/output` (the precise location may depend on your +configuration). The stderr output is also saved in that same directory. + +The following is a summary of the instructions that Cargo recognizes, with each +one detailed below. + +* [`cargo:rerun-if-changed=PATH`](#rerun-if-changed) --- Tells Cargo when to + re-run the script. +* [`cargo:rerun-if-env-changed=VAR`](#rerun-if-env-changed) --- Tells Cargo when + to re-run the script. +* [`cargo:rustc-link-arg=FLAG`](#rustc-link-arg) --- Passes custom flags to a + linker for benchmarks, binaries, `cdylib` crates, examples, and tests. +* [`cargo:rustc-link-arg-bin=BIN=FLAG`](#rustc-link-arg-bin) --- Passes custom + flags to a linker for the binary `BIN`. +* [`cargo:rustc-link-arg-bins=FLAG`](#rustc-link-arg-bins) --- Passes custom + flags to a linker for binaries. +* [`cargo:rustc-link-arg-tests=FLAG`](#rustc-link-arg-tests) --- Passes custom + flags to a linker for tests. +* [`cargo:rustc-link-arg-examples=FLAG`](#rustc-link-arg-examples) --- Passes custom + flags to a linker for examples. +* [`cargo:rustc-link-arg-benches=FLAG`](#rustc-link-arg-benches) --- Passes custom + flags to a linker for benchmarks. +* [`cargo:rustc-link-lib=LIB`](#rustc-link-lib) --- Adds a library to + link. +* [`cargo:rustc-link-search=[KIND=]PATH`](#rustc-link-search) --- Adds to the + library search path. +* [`cargo:rustc-flags=FLAGS`](#rustc-flags) --- Passes certain flags to the + compiler. +* [`cargo:rustc-cfg=KEY[="VALUE"]`](#rustc-cfg) --- Enables compile-time `cfg` + settings. +* [`cargo:rustc-env=VAR=VALUE`](#rustc-env) --- Sets an environment variable. +* [`cargo:rustc-cdylib-link-arg=FLAG`](#rustc-cdylib-link-arg) --- Passes custom + flags to a linker for cdylib crates. +* [`cargo:warning=MESSAGE`](#cargo-warning) --- Displays a warning on the + terminal. +* [`cargo:KEY=VALUE`](#the-links-manifest-key) --- Metadata, used by `links` + scripts. + + +<a id="rustc-link-arg"></a> +#### `cargo:rustc-link-arg=FLAG` + +The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG` +option][link-arg] to the compiler, but only when building supported targets +(benchmarks, binaries, `cdylib` crates, examples, and tests). Its usage is +highly platform specific. It is useful to set the shared library version or +linker script. + +[link-arg]: ../../rustc/codegen-options/index.md#link-arg + +<a id="rustc-link-arg-bin"></a> +#### `cargo:rustc-link-arg-bin=BIN=FLAG` + +The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building +the binary target with name `BIN`. Its usage is highly platform specific. It is useful +to set a linker script or other linker options. + + +<a id="rustc-link-arg-bins"></a> +#### `cargo:rustc-link-arg-bins=FLAG` + +The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building a +binary target. Its usage is highly platform specific. It is useful +to set a linker script or other linker options. + + +<a id="rustc-link-lib"></a> +#### `cargo:rustc-link-lib=LIB` + +The `rustc-link-lib` instruction tells Cargo to link the given library using +the compiler's [`-l` flag][option-link]. This is typically used to link a +native library using [FFI]. + +The `LIB` string is passed directly to rustc, so it supports any syntax that +`-l` does. \ +Currently the full supported syntax for `LIB` is `[KIND[:MODIFIERS]=]NAME[:RENAME]`. + +The `-l` flag is only passed to the library target of the package, unless +there is no library target, in which case it is passed to all targets. This is +done because all other targets have an implicit dependency on the library +target, and the given library to link should only be included once. This means +that if a package has both a library and a binary target, the *library* has +access to the symbols from the given lib, and the binary should access them +through the library target's public API. + +The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the +[rustc book][option-link] for more detail. + +[option-link]: ../../rustc/command-line-arguments.md#option-l-link-lib +[FFI]: ../../nomicon/ffi.md + + +<a id="rustc-link-arg-tests"></a> +#### `cargo:rustc-link-arg-tests=FLAG` + +The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building a +tests target. + + +<a id="rustc-link-arg-examples"></a> +#### `cargo:rustc-link-arg-examples=FLAG` + +The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples +target. + +<a id="rustc-link-arg-benches"></a> +#### `cargo:rustc-link-arg-benches=FLAG` + +The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building an benchmark +target. + +<a id="rustc-link-search"></a> +#### `cargo:rustc-link-search=[KIND=]PATH` + +The `rustc-link-search` instruction tells Cargo to pass the [`-L` +flag][option-search] to the compiler to add a directory to the library search +path. + +The optional `KIND` may be one of `dependency`, `crate`, `native`, +`framework`, or `all`. See the [rustc book][option-search] for more detail. + +These paths are also added to the [dynamic library search path environment +variable](environment-variables.md#dynamic-library-paths) if they are within +the `OUT_DIR`. Depending on this behavior is discouraged since this makes it +difficult to use the resulting binary. In general, it is best to avoid +creating dynamic libraries in a build script (using existing system libraries +is fine). + +[option-search]: ../../rustc/command-line-arguments.md#option-l-search-path + +<a id="rustc-flags"></a> +#### `cargo:rustc-flags=FLAGS` + +The `rustc-flags` instruction tells Cargo to pass the given space-separated +flags to the compiler. This only allows the `-l` and `-L` flags, and is +equivalent to using [`rustc-link-lib`](#rustc-link-lib) and +[`rustc-link-search`](#rustc-link-search). + +<a id="rustc-cfg"></a> +#### `cargo:rustc-cfg=KEY[="VALUE"]` + +The `rustc-cfg` instruction tells Cargo to pass the given value to the +[`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time +detection of features to enable [conditional compilation]. + +Note that this does *not* affect Cargo's dependency resolution. This cannot be +used to enable an optional dependency, or enable other Cargo features. + +Be aware that [Cargo features] use the form `feature="foo"`. `cfg` values +passed with this flag are not restricted to that form, and may provide just a +single identifier, or any arbitrary key/value pair. For example, emitting +`cargo:rustc-cfg=abc` will then allow code to use `#[cfg(abc)]` (note the lack +of `feature=`). Or an arbitrary key/value pair may be used with an `=` symbol +like `cargo:rustc-cfg=my_component="foo"`. The key should be a Rust +identifier, the value should be a string. + +[cargo features]: features.md +[conditional compilation]: ../../reference/conditional-compilation.md +[option-cfg]: ../../rustc/command-line-arguments.md#option-cfg + +<a id="rustc-env"></a> +#### `cargo:rustc-env=VAR=VALUE` + +The `rustc-env` instruction tells Cargo to set the given environment variable +when compiling the package. The value can be then retrieved by the [`env!` +macro][env-macro] in the compiled crate. This is useful for embedding +additional metadata in crate's code, such as the hash of git HEAD or the +unique identifier of a continuous integration server. + +See also the [environment variables automatically included by +Cargo][env-cargo]. + +> **Note**: These environment variables are also set when running an +> executable with `cargo run` or `cargo test`. However, this usage is +> discouraged since it ties the executable to Cargo's execution environment. +> Normally, these environment variables should only be checked at compile-time +> with the `env!` macro. + +[env-macro]: ../../std/macro.env.html +[env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates + +<a id="rustc-cdylib-link-arg"></a> +#### `cargo:rustc-cdylib-link-arg=FLAG` + +The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C +link-arg=FLAG` option][link-arg] to the compiler, but only when building a +`cdylib` library target. Its usage is highly platform specific. It is useful +to set the shared library version or the runtime-path. + + +<a id="cargo-warning"></a> +#### `cargo:warning=MESSAGE` + +The `warning` instruction tells Cargo to display a warning after the build +script has finished running. Warnings are only shown for `path` dependencies +(that is, those you're working on locally), so for example warnings printed +out in [crates.io] crates are not emitted by default. The `-vv` "very verbose" +flag may be used to have Cargo display warnings for all crates. + +### Build Dependencies + +Build scripts are also allowed to have dependencies on other Cargo-based crates. +Dependencies are declared through the `build-dependencies` section of the +manifest. + +```toml +[build-dependencies] +cc = "1.0.46" +``` + +The build script **does not** have access to the dependencies listed in the +`dependencies` or `dev-dependencies` section (they’re not built yet!). Also, +build dependencies are not available to the package itself unless also +explicitly added in the `[dependencies]` table. + +It is recommended to carefully consider each dependency you add, weighing +against the impact on compile time, licensing, maintenance, etc. Cargo will +attempt to reuse a dependency if it is shared between build dependencies and +normal dependencies. However, this is not always possible, for example when +cross-compiling, so keep that in consideration of the impact on compile time. + +### Change Detection + +When rebuilding a package, Cargo does not necessarily know if the build script +needs to be run again. By default, it takes a conservative approach of always +re-running the build script if any file within the package is changed (or the +list of files controlled by the [`exclude` and `include` fields]). For most +cases, this is not a good choice, so it is recommended that every build script +emit at least one of the `rerun-if` instructions (described below). If these +are emitted, then Cargo will only re-run the script if the given value has +changed. If Cargo is re-running the build scripts of your own crate or a +dependency and you don't know why, see ["Why is Cargo rebuilding my code?" in the +FAQ](../faq.md#why-is-cargo-rebuilding-my-code). + +[`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields + +<a id="rerun-if-changed"></a> +#### `cargo:rerun-if-changed=PATH` + +The `rerun-if-changed` instruction tells Cargo to re-run the build script if +the file at the given path has changed. Currently, Cargo only uses the +filesystem last-modified "mtime" timestamp to determine if the file has +changed. It compares against an internal cached timestamp of when the build +script last ran. + +If the path points to a directory, it will scan the entire directory for +any modifications. + +If the build script inherently does not need to re-run under any circumstance, +then emitting `cargo:rerun-if-changed=build.rs` is a simple way to prevent it +from being re-run (otherwise, the default if no `rerun-if` instructions are +emitted is to scan the entire package directory for changes). Cargo +automatically handles whether or not the script itself needs to be recompiled, +and of course the script will be re-run after it has been recompiled. +Otherwise, specifying `build.rs` is redundant and unnecessary. + +<a id="rerun-if-env-changed"></a> +#### `cargo:rerun-if-env-changed=NAME` + +The `rerun-if-env-changed` instruction tells Cargo to re-run the build script +if the value of an environment variable of the given name has changed. + +Note that the environment variables here are intended for global environment +variables like `CC` and such, it is not necessary to use this for environment +variables like `TARGET` that Cargo sets. + + +### The `links` Manifest Key + +The `package.links` key may be set in the `Cargo.toml` manifest to declare +that the package links with the given native library. The purpose of this +manifest key is to give Cargo an understanding about the set of native +dependencies that a package has, as well as providing a principled system of +passing metadata between package build scripts. + +```toml +[package] +# ... +links = "foo" +``` + +This manifest states that the package links to the `libfoo` native library. +When using the `links` key, the package must have a build script, and the +build script should use the [`rustc-link-lib` instruction](#rustc-link-lib) to +link the library. + +Primarily, Cargo requires that there is at most one package per `links` value. +In other words, it is forbidden to have two packages link to the same native +library. This helps prevent duplicate symbols between crates. Note, however, +that there are [conventions in place](#-sys-packages) to alleviate this. + +As mentioned above in the output format, each build script can generate an +arbitrary set of metadata in the form of key-value pairs. This metadata is +passed to the build scripts of **dependent** packages. For example, if the +package `bar` depends on `foo`, then if `foo` generates `key=value` as part of +its build script metadata, then the build script of `bar` will have the +environment variables `DEP_FOO_KEY=value`. See the ["Using another `sys` +crate"][using-another-sys] for an example of +how this can be used. + +Note that metadata is only passed to immediate dependents, not transitive +dependents. + +[using-another-sys]: build-script-examples.md#using-another-sys-crate + +### `*-sys` Packages + +Some Cargo packages that link to system libraries have a naming convention of +having a `-sys` suffix. Any package named `foo-sys` should provide two major +pieces of functionality: + +* The library crate should link to the native library `libfoo`. This will often + probe the current system for `libfoo` before resorting to building from + source. +* The library crate should provide **declarations** for types and functions in + `libfoo`, but **not** higher-level abstractions. + +The set of `*-sys` packages provides a common set of dependencies for linking +to native libraries. There are a number of benefits earned from having this +convention of native-library-related packages: + +* Common dependencies on `foo-sys` alleviates the rule about one package per + value of `links`. +* Other `-sys` packages can take advantage of the `DEP_NAME_KEY=value` + environment variables to better integrate with other packages. See the + ["Using another `sys` crate"][using-another-sys] example. +* A common dependency allows centralizing logic on discovering `libfoo` itself + (or building it from source). +* These dependencies are easily [overridable](#overriding-build-scripts). + +It is common to have a companion package without the `-sys` suffix that +provides a safe, high-level abstractions on top of the sys package. For +example, the [`git2` crate] provides a high-level interface to the +[`libgit2-sys` crate]. + +[`git2` crate]: https://crates.io/crates/git2 +[`libgit2-sys` crate]: https://crates.io/crates/libgit2-sys + +### Overriding Build Scripts + +If a manifest contains a `links` key, then Cargo supports overriding the build +script specified with a custom library. The purpose of this functionality is to +prevent running the build script in question altogether and instead supply the +metadata ahead of time. + +To override a build script, place the following configuration in any acceptable [`config.toml`](config.md) file. + +```toml +[target.x86_64-unknown-linux-gnu.foo] +rustc-link-lib = ["foo"] +rustc-link-search = ["/path/to/foo"] +rustc-flags = "-L /some/path" +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" +``` + +With this configuration, if a package declares that it links to `foo` then the +build script will **not** be compiled or run, and the metadata specified will +be used instead. + +The `warning`, `rerun-if-changed`, and `rerun-if-env-changed` keys should not +be used and will be ignored. + +### Jobserver + +Cargo and `rustc` use the [jobserver protocol], developed for GNU make, to +coordinate concurrency across processes. It is essentially a semaphore that +controls the number of jobs running concurrently. The concurrency may be set +with the `--jobs` flag, which defaults to the number of logical CPUs. + +Each build script inherits one job slot from Cargo, and should endeavor to +only use one CPU while it runs. If the script wants to use more CPUs in +parallel, it should use the [`jobserver` crate] to coordinate with Cargo. + +As an example, the [`cc` crate] may enable the optional `parallel` feature +which will use the jobserver protocol to attempt to build multiple C files +at the same time. + +[`cc` crate]: https://crates.io/crates/cc +[`jobserver` crate]: https://crates.io/crates/jobserver +[jobserver protocol]: http://make.mad-scientist.net/papers/jobserver-implementation/ +[crates.io]: https://crates.io/ diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md new file mode 100644 index 0000000..7aea151 --- /dev/null +++ b/src/doc/src/reference/cargo-targets.md @@ -0,0 +1,389 @@ +## Cargo Targets + +Cargo packages consist of *targets* which correspond to source files which can +be compiled into a crate. Packages can have [library](#library), +[binary](#binaries), [example](#examples), [test](#tests), and +[benchmark](#benchmarks) targets. The list of targets can be configured in the +`Cargo.toml` manifest, often [inferred automatically](#target-auto-discovery) +by the [directory layout][package layout] of the source files. + +See [Configuring a target](#configuring-a-target) below for details on +configuring the settings for a target. + +### Library + +The library target defines a "library" that can be used and linked by other +libraries and executables. The filename defaults to `src/lib.rs`, and the name +of the library defaults to the name of the package. A package can have only +one library. The settings for the library can be [customized] in the `[lib]` +table in `Cargo.toml`. + +```toml +# Example of customizing the library in Cargo.toml. +[lib] +crate-type = ["cdylib"] +bench = false +``` + +### Binaries + +Binary targets are executable programs that can be run after being compiled. +The default binary filename is `src/main.rs`, which defaults to the name of +the package. Additional binaries are stored in the [`src/bin/` +directory][package layout]. The settings for each binary can be [customized] +in the `[[bin]]` tables in `Cargo.toml`. + +Binaries can use the public API of the package's library. They are also linked +with the [`[dependencies]`][dependencies] defined in `Cargo.toml`. + +You can run individual binaries with the [`cargo run`] command with the `--bin +<bin-name>` option. [`cargo install`] can be used to copy the executable to a +common location. + +```toml +# Example of customizing binaries in Cargo.toml. +[[bin]] +name = "cool-tool" +test = false +bench = false + +[[bin]] +name = "frobnicator" +required-features = ["frobnicate"] +``` + +### Examples + +Files located under the [`examples` directory][package layout] are example +uses of the functionality provided by the library. When compiled, they are +placed in the [`target/debug/examples` directory][build cache]. + +Examples can use the public API of the package's library. They are also linked +with the [`[dependencies]`][dependencies] and +[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`. + +By default, examples are executable binaries (with a `main()` function). You +can specify the [`crate-type` field](#the-crate-type-field) to make an example +be compiled as a library: + +```toml +[[example]] +name = "foo" +crate-type = ["staticlib"] +``` + +You can run individual executable examples with the [`cargo run`] command with +the `--example <example-name>` option. Library examples can be built with +[`cargo build`] with the `--example <example-name>` option. [`cargo install`] +with the `--example <example-name>` option can be used to copy executable +binaries to a common location. Examples are compiled by [`cargo test`] by +default to protect them from bit-rotting. Set [the `test` +field](#the-test-field) to `true` if you have `#[test]` functions in the +example that you want to run with [`cargo test`]. + +### Tests + +There are two styles of tests within a Cargo project: + +* *Unit tests* which are functions marked with the [`#[test]` + attribute][test-attribute] located within your library or binaries (or any + target enabled with [the `test` field](#the-test-field)). These tests have + access to private APIs located within the target they are defined in. +* *Integration tests* which is a separate executable binary, also containing + `#[test]` functions, which is linked with the project's library and has + access to its *public* API. + +Tests are run with the [`cargo test`] command. By default, Cargo and `rustc` +use the [libtest harness] which is responsible for collecting functions +annotated with the [`#[test]` attribute][test-attribute] and executing them in +parallel, reporting the success and failure of each test. See [the `harness` +field](#the-harness-field) if you want to use a different harness or test +strategy. + +> **Note**: There is another special style of test in Cargo: +> [documentation tests][documentation examples]. +> They are handled by `rustdoc` and have a slightly different execution model. +> For more information, please see [`cargo test`][cargo-test-documentation-tests]. + +[libtest harness]: ../../rustc/tests/index.html +[cargo-test-documentation-tests]: ../commands/cargo-test.md#documentation-tests + +#### Integration tests + +Files located under the [`tests` directory][package layout] are integration +tests. When you run [`cargo test`], Cargo will compile each of these files as +a separate crate, and execute them. + +Integration tests can use the public API of the package's library. They are +also linked with the [`[dependencies]`][dependencies] and +[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`. + +If you want to share code among multiple integration tests, you can place it +in a separate module such as `tests/common/mod.rs` and then put `mod common;` +in each test to import it. + +Each integration test results in a separate executable binary, and [`cargo +test`] will run them serially. In some cases this can be inefficient, as it +can take longer to compile, and may not make full use of multiple CPUs when +running the tests. If you have a lot of integration tests, you may want to +consider creating a single integration test, and split the tests into multiple +modules. The libtest harness will automatically find all of the `#[test]` +annotated functions and run them in parallel. You can pass module names to +[`cargo test`] to only run the tests within that module. + +Binary targets are automatically built if there is an integration test. This +allows an integration test to execute the binary to exercise and test its +behavior. The `CARGO_BIN_EXE_<name>` [environment variable] is set when the +integration test is built so that it can use the [`env` macro] to locate the +executable. + +[environment variable]: environment-variables.md#environment-variables-cargo-sets-for-crates +[`env` macro]: ../../std/macro.env.html + +### Benchmarks + +Benchmarks provide a way to test the performance of your code using the +[`cargo bench`] command. They follow the same structure as [tests](#tests), +with each benchmark function annotated with the `#[bench]` attribute. +Similarly to tests: + +* Benchmarks are placed in the [`benches` directory][package layout]. +* Benchmark functions defined in libraries and binaries have access to the + *private* API within the target they are defined in. Benchmarks in the + `benches` directory may use the *public* API. +* [The `bench` field](#the-bench-field) can be used to define which targets + are benchmarked by default. +* [The `harness` field](#the-harness-field) can be used to disable the + built-in harness. + +> **Note**: The [`#[bench]` +> attribute](../../unstable-book/library-features/test.html) is currently +> unstable and only available on the [nightly channel]. There are some +> packages available on [crates.io](https://crates.io/keywords/benchmark) that +> may help with running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +### Configuring a target + +All of the `[lib]`, `[[bin]]`, `[[example]]`, `[[test]]`, and `[[bench]]` +sections in `Cargo.toml` support similar configuration for specifying how a +target should be built. The double-bracket sections like `[[bin]]` are +[array-of-table of TOML](https://toml.io/en/v1.0.0-rc.3#array-of-tables), +which means you can write more than one `[[bin]]` section to make several +executables in your crate. You can only specify one library, so `[lib]` is a +normal TOML table. + +The following is an overview of the TOML settings for each target, with each +field described in detail below. + +```toml +[lib] +name = "foo" # The name of the target. +path = "src/lib.rs" # The source file of the target. +test = true # Is tested by default. +doctest = true # Documentation examples are tested by default. +bench = true # Is benchmarked by default. +doc = true # Is documented by default. +plugin = false # Used as a compiler plugin (deprecated). +proc-macro = false # Set to `true` for a proc-macro library. +harness = true # Use libtest harness. +edition = "2015" # The edition of the target. +crate-type = ["lib"] # The crate types to generate. +required-features = [] # Features required to build this target (N/A for lib). +``` + +#### The `name` field + +The `name` field specifies the name of the target, which corresponds to the +filename of the artifact that will be generated. For a library, this is the +crate name that dependencies will use to reference it. + +For the `[lib]` and the default binary (`src/main.rs`), this defaults to the +name of the package, with any dashes replaced with underscores. For other +[auto discovered](#target-auto-discovery) targets, it defaults to the +directory or file name. + +This is required for all targets except `[lib]`. + +#### The `path` field + +The `path` field specifies where the source for the crate is located, relative +to the `Cargo.toml` file. + +If not specified, the [inferred path](#target-auto-discovery) is used based on +the target name. + +#### The `test` field + +The `test` field indicates whether or not the target is tested by default by +[`cargo test`]. The default is `true` for lib, bins, and tests. + +> **Note**: Examples are built by [`cargo test`] by default to ensure they +> continue to compile, but they are not *tested* by default. Setting `test = +> true` for an example will also build it as a test and run any +> [`#[test]`][test-attribute] functions defined in the example. + +#### The `doctest` field + +The `doctest` field indicates whether or not [documentation examples] are +tested by default by [`cargo test`]. This is only relevant for libraries, it +has no effect on other sections. The default is `true` for the library. + +#### The `bench` field + +The `bench` field indicates whether or not the target is benchmarked by +default by [`cargo bench`]. The default is `true` for lib, bins, and +benchmarks. + +#### The `doc` field + +The `doc` field indicates whether or not the target is included in the +documentation generated by [`cargo doc`] by default. The default is `true` for +libraries and binaries. + +> **Note**: The binary will be skipped if its name is the same as the lib +> target. + +#### The `plugin` field + +This field is used for `rustc` plugins, which are being deprecated. + +#### The `proc-macro` field + +The `proc-macro` field indicates that the library is a [procedural macro] +([reference][proc-macro-reference]). This is only valid for the `[lib]` +target. + +#### The `harness` field + +The `harness` field indicates that the [`--test` flag] will be passed to +`rustc` which will automatically include the libtest library which is the +driver for collecting and running tests marked with the [`#[test]` +attribute][test-attribute] or benchmarks with the `#[bench]` attribute. The +default is `true` for all targets. + +If set to `false`, then you are responsible for defining a `main()` function +to run tests and benchmarks. + +Tests have the [`cfg(test)` conditional expression][cfg-test] enabled whether +or not the harness is enabled. + +#### The `edition` field + +The `edition` field defines the [Rust edition] the target will use. If not +specified, it defaults to the [`edition` field][package-edition] for the +`[package]`. This field should usually not be set, and is only intended for +advanced scenarios such as incrementally transitioning a large package to a +new edition. + +#### The `crate-type` field + +The `crate-type` field defines the [crate types] that will be generated by the +target. It is an array of strings, allowing you to specify multiple crate +types for a single target. This can only be specified for libraries and +examples. Binaries, tests, and benchmarks are always the "bin" crate type. The +defaults are: + +Target | Crate Type +-------|----------- +Normal library | `"lib"` +Proc-macro library | `"proc-macro"` +Example | `"bin"` + +The available options are `bin`, `lib`, `rlib`, `dylib`, `cdylib`, +`staticlib`, and `proc-macro`. You can read more about the different crate +types in the [Rust Reference Manual][crate types]. + +#### The `required-features` field + +The `required-features` field specifies which [features] the target needs in +order to be built. If any of the required features are not enabled, the +target will be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, +`[[test]]`, and `[[example]]` sections, it has no effect on `[lib]`. + +```toml +[features] +# ... +postgres = [] +sqlite = [] +tools = [] + +[[bin]] +name = "my-pg-tool" +required-features = ["postgres", "tools"] +``` + + +### Target auto-discovery + +By default, Cargo automatically determines the targets to build based on the +[layout of the files][package layout] on the filesystem. The target +configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or +`[[example]]`, can be used to add additional targets that don't follow the +standard directory layout. + +The automatic target discovery can be disabled so that only manually +configured targets will be built. Setting the keys `autobins`, `autoexamples`, +`autotests`, or `autobenches` to `false` in the `[package]` section will +disable auto-discovery of the corresponding target type. + +```toml +[package] +# ... +autobins = false +autoexamples = false +autotests = false +autobenches = false +``` + +Disabling automatic discovery should only be needed for specialized +situations. For example, if you have a library where you want a *module* named +`bin`, this would present a problem because Cargo would usually attempt to +compile anything in the `bin` directory as an executable. Here is a sample +layout of this scenario: + +```text +├── Cargo.toml +└── src + ├── lib.rs + └── bin + └── mod.rs +``` + +To prevent Cargo from inferring `src/bin/mod.rs` as an executable, set +`autobins = false` in `Cargo.toml` to disable auto-discovery: + +```toml +[package] +# … +autobins = false +``` + +> **Note**: For packages with the 2015 edition, the default for auto-discovery +> is `false` if at least one target is manually defined in `Cargo.toml`. +> Beginning with the 2018 edition, the default is always `true`. + + +[Build cache]: ../guide/build-cache.md +[Rust Edition]: ../../edition-guide/index.html +[`--test` flag]: ../../rustc/command-line-arguments.html#option-test +[`cargo bench`]: ../commands/cargo-bench.md +[`cargo build`]: ../commands/cargo-build.md +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo test`]: ../commands/cargo-test.md +[cfg-test]: ../../reference/conditional-compilation.html#test +[crate types]: ../../reference/linkage.html +[crates.io]: https://crates.io/ +[customized]: #configuring-a-target +[dependencies]: specifying-dependencies.md +[dev-dependencies]: specifying-dependencies.md#development-dependencies +[documentation examples]: ../../rustdoc/documentation-tests.html +[features]: features.md +[nightly channel]: ../../book/appendix-07-nightly-rust.html +[package layout]: ../guide/project-layout.md +[package-edition]: manifest.md#the-edition-field +[proc-macro-reference]: ../../reference/procedural-macros.html +[procedural macro]: ../../book/ch19-06-macros.html +[test-attribute]: ../../reference/attributes/testing.html#the-test-attribute diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md new file mode 100644 index 0000000..b826beb --- /dev/null +++ b/src/doc/src/reference/config.md @@ -0,0 +1,1218 @@ +## Configuration + +This document explains how Cargo’s configuration system works, as well as +available keys or configuration. For configuration of a package through its +manifest, see the [manifest format](manifest.md). + +### Hierarchical structure + +Cargo allows local configuration for a particular package as well as global +configuration. It looks for configuration files in the current directory and +all parent directories. If, for example, Cargo were invoked in +`/projects/foo/bar/baz`, then the following configuration files would be +probed for and unified in this order: + +* `/projects/foo/bar/baz/.cargo/config.toml` +* `/projects/foo/bar/.cargo/config.toml` +* `/projects/foo/.cargo/config.toml` +* `/projects/.cargo/config.toml` +* `/.cargo/config.toml` +* `$CARGO_HOME/config.toml` which defaults to: + * Windows: `%USERPROFILE%\.cargo\config.toml` + * Unix: `$HOME/.cargo/config.toml` + +With this structure, you can specify configuration per-package, and even +possibly check it into version control. You can also specify personal defaults +with a configuration file in your home directory. + +If a key is specified in multiple config files, the values will get merged +together. Numbers, strings, and booleans will use the value in the deeper +config directory taking precedence over ancestor directories, where the +home directory is the lowest priority. Arrays will be joined together. + +At present, when being invoked from a workspace, Cargo does not read config +files from crates within the workspace. i.e. if a workspace has two crates in +it, named `/projects/foo/bar/baz/mylib` and `/projects/foo/bar/baz/mybin`, and +there are Cargo configs at `/projects/foo/bar/baz/mylib/.cargo/config.toml` +and `/projects/foo/bar/baz/mybin/.cargo/config.toml`, Cargo does not read +those configuration files if it is invoked from the workspace root +(`/projects/foo/bar/baz/`). + +> **Note:** Cargo also reads config files without the `.toml` extension, such as +> `.cargo/config`. Support for the `.toml` extension was added in version 1.39 +> and is the preferred form. If both files exist, Cargo will use the file +> without the extension. + +### Configuration format + +Configuration files are written in the [TOML format][toml] (like the +manifest), with simple key-value pairs inside of sections (tables). The +following is a quick overview of all settings, with detailed descriptions +found below. + +```toml +paths = ["/path/to/override"] # path dependency overrides + +[alias] # command aliases +b = "build" +c = "check" +t = "test" +r = "run" +rr = "run --release" +recursive_example = "rr --example recursions" +space_example = ["run", "--release", "--", "\"command list\""] + +[build] +jobs = 1 # number of parallel jobs, defaults to # of CPUs +rustc = "rustc" # the rust compiler tool +rustc-wrapper = "…" # run this wrapper instead of `rustc` +rustc-workspace-wrapper = "…" # run this wrapper instead of `rustc` for workspace members +rustdoc = "rustdoc" # the doc generator tool +target = "triple" # build for the target triple (ignored by `cargo install`) +target-dir = "target" # path of where to place all generated artifacts +rustflags = ["…", "…"] # custom flags to pass to all compiler invocations +rustdocflags = ["…", "…"] # custom flags to pass to rustdoc +incremental = true # whether or not to enable incremental compilation +dep-info-basedir = "…" # path for the base directory for targets in depfiles + +[doc] +browser = "chromium" # browser to use with `cargo doc --open`, + # overrides the `BROWSER` environment variable + +[env] +# Set ENV_VAR_NAME=value for any process run by Cargo +ENV_VAR_NAME = "value" +# Set even if already present in environment +ENV_VAR_NAME_2 = { value = "value", force = true } +# Value is relative to .cargo directory containing `config.toml`, make absolute +ENV_VAR_NAME_3 = { value = "relative/path", relative = true } + +[future-incompat-report] +frequency = 'always' # when to display a notification about a future incompat report + +[cargo-new] +vcs = "none" # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none') + +[http] +debug = false # HTTP debugging +proxy = "host:port" # HTTP proxy in libcurl format +ssl-version = "tlsv1.3" # TLS version to use +ssl-version.max = "tlsv1.3" # maximum TLS version +ssl-version.min = "tlsv1.1" # minimum TLS version +timeout = 30 # timeout for each HTTP request, in seconds +low-speed-limit = 10 # network timeout threshold (bytes/sec) +cainfo = "cert.pem" # path to Certificate Authority (CA) bundle +check-revoke = true # check for SSL certificate revocation +multiplexing = true # HTTP/2 multiplexing +user-agent = "…" # the user-agent header + +[install] +root = "/some/path" # `cargo install` destination directory + +[net] +retry = 2 # network retries +git-fetch-with-cli = true # use the `git` executable for git operations +offline = true # do not access the network + +[net.ssh] +known-hosts = ["..."] # known SSH host keys + +[patch.<registry>] +# Same keys as for [patch] in Cargo.toml + +[profile.<name>] # Modify profile settings via config. +inherits = "dev" # Inherits settings from [profile.dev]. +opt-level = 0 # Optimization level. +debug = true # Include debug info. +split-debuginfo = '...' # Debug info splitting behavior. +debug-assertions = true # Enables debug assertions. +overflow-checks = true # Enables runtime integer overflow checks. +lto = false # Sets link-time optimization. +panic = 'unwind' # The panic strategy. +incremental = true # Incremental compilation. +codegen-units = 16 # Number of code generation units. +rpath = false # Sets the rpath linking option. +[profile.<name>.build-override] # Overrides build-script settings. +# Same keys for a normal profile. +[profile.<name>.package.<name>] # Override profile for a package. +# Same keys for a normal profile (minus `panic`, `lto`, and `rpath`). + +[registries.<name>] # registries other than crates.io +index = "…" # URL of the registry index +token = "…" # authentication token for the registry + +[registry] +default = "…" # name of the default registry +token = "…" # authentication token for crates.io + +[source.<name>] # source definition and replacement +replace-with = "…" # replace this source with the given named source +directory = "…" # path to a directory source +registry = "…" # URL to a registry source +local-registry = "…" # path to a local registry source +git = "…" # URL of a git repository source +branch = "…" # branch name for the git repository +tag = "…" # tag name for the git repository +rev = "…" # revision for the git repository + +[target.<triple>] +linker = "…" # linker to use +runner = "…" # wrapper to run executables +rustflags = ["…", "…"] # custom flags for `rustc` + +[target.<cfg>] +runner = "…" # wrapper to run executables +rustflags = ["…", "…"] # custom flags for `rustc` + +[target.<triple>.<links>] # `links` build script override +rustc-link-lib = ["foo"] +rustc-link-search = ["/path/to/foo"] +rustc-flags = ["-L", "/some/path"] +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" + +[term] +quiet = false # whether cargo output is quiet +verbose = false # whether cargo provides verbose output +color = 'auto' # whether cargo colorizes output +progress.when = 'auto' # whether cargo shows progress bar +progress.width = 80 # width of progress bar +``` + +### Environment variables + +Cargo can also be configured through environment variables in addition to the +TOML configuration files. For each configuration key of the form `foo.bar` the +environment variable `CARGO_FOO_BAR` can also be used to define the value. +Keys are converted to uppercase, dots and dashes are converted to underscores. +For example the `target.x86_64-unknown-linux-gnu.runner` key can also be +defined by the `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER` environment +variable. + +Environment variables will take precedence over TOML configuration files. +Currently only integer, boolean, string and some array values are supported to +be defined by environment variables. [Descriptions below](#configuration-keys) +indicate which keys support environment variables and otherwise they are not +supported due to [technicial issues](https://github.com/rust-lang/cargo/issues/5416). + +In addition to the system above, Cargo recognizes a few other specific +[environment variables][env]. + +### Command-line overrides + +Cargo also accepts arbitrary configuration overrides through the +`--config` command-line option. The argument should be in TOML syntax of +`KEY=VALUE`: + +```console +cargo --config net.git-fetch-with-cli=true fetch +``` + +The `--config` option may be specified multiple times, in which case the +values are merged in left-to-right order, using the same merging logic +that is used when multiple configuration files apply. Configuration +values specified this way take precedence over environment variables, +which take precedence over configuration files. + +Some examples of what it looks like using Bourne shell syntax: + +```console +# Most shells will require escaping. +cargo --config http.proxy=\"http://example.com\" … + +# Spaces may be used. +cargo --config "net.git-fetch-with-cli = true" … + +# TOML array example. Single quotes make it easier to read and write. +cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' … + +# Example of a complex TOML key. +cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" … + +# Example of overriding a profile setting. +cargo --config profile.dev.package.image.opt-level=3 … +``` + +The `--config` option can also be used to pass paths to extra +configuration files that Cargo should use for a specific invocation. +Options from configuration files loaded this way follow the same +precedence rules as other options specified directly with `--config`. + +### Config-relative paths + +Paths in config files may be absolute, relative, or a bare name without any path separators. +Paths for executables without a path separator will use the `PATH` environment variable to search for the executable. +Paths for non-executables will be relative to where the config value is defined. + +In particular, rules are: + +* For environment variables, paths are relative to the current working directory. +* For config values loaded directly from the [`--config KEY=VALUE`](#command-line-overrides) option, + paths are relative to the current working directory. +* For config files, paths are relative to the parent directory of the directory where the config files were defined, + no matter those files are from either the [hierarchical probing](#hierarchical-structure) + or the [`--config <path>`](#command-line-overrides) option. + +> **Note:** To maintain consistency with existing `.cargo/config.toml` probing behavior, +> it is by design that a path in a config file passed via `--config <path>` +> is also relative to two levels up from the config file itself. +> +> To avoid unexpected results, the rule of thumb is putting your extra config files +> at the same level of discovered `.cargo/config.toml` in your project. +> For instance, given a project `/my/project`, +> it is recommended to put config files under `/my/project/.cargo` +> or a new directory at the same level, such as `/my/project/.config`. + +```toml +# Relative path examples. + +[target.x86_64-unknown-linux-gnu] +runner = "foo" # Searches `PATH` for `foo`. + +[source.vendored-sources] +# Directory is relative to the parent where `.cargo/config.toml` is located. +# For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`. +directory = "vendor" +``` + +### Executable paths with arguments + +Some Cargo commands invoke external programs, which can be configured as a path +and some number of arguments. + +The value may be an array of strings like `['/path/to/program', 'somearg']` or +a space-separated string like `'/path/to/program somearg'`. If the path to the +executable contains a space, the list form must be used. + +If Cargo is passing other arguments to the program such as a path to open or +run, they will be passed after the last specified argument in the value of an +option of this format. If the specified program does not have path separators, +Cargo will search `PATH` for its executable. + +### Credentials + +Configuration values with sensitive information are stored in the +`$CARGO_HOME/credentials.toml` file. This file is automatically created and updated +by [`cargo login`]. It follows the same format as Cargo config files. + +```toml +[registry] +token = "…" # Access token for crates.io + +[registries.<name>] +token = "…" # Access token for the named registry +``` + +Tokens are used by some Cargo commands such as [`cargo publish`] for +authenticating with remote registries. Care should be taken to protect the +tokens and to keep them secret. + +As with most other config values, tokens may be specified with environment +variables. The token for [crates.io] may be specified with the +`CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may +be specified with environment variables of the form +`CARGO_REGISTRIES_<name>_TOKEN` where `<name>` is the name of the registry in +all capital letters. + +### Configuration keys + +This section documents all configuration keys. The description for keys with +variable parts are annotated with angled brackets like `target.<triple>` where +the `<triple>` part can be any [target triple] like +`target.x86_64-pc-windows-msvc`. + +#### `paths` +* Type: array of strings (paths) +* Default: none +* Environment: not supported + +An array of paths to local packages which are to be used as overrides for +dependencies. For more information see the [Overriding Dependencies +guide](overriding-dependencies.md#paths-overrides). + +#### `[alias]` +* Type: string or array of strings +* Default: see below +* Environment: `CARGO_ALIAS_<name>` + +The `[alias]` table defines CLI command aliases. For example, running `cargo +b` is an alias for running `cargo build`. Each key in the table is the +subcommand, and the value is the actual command to run. The value may be an +array of strings, where the first element is the command and the following are +arguments. It may also be a string, which will be split on spaces into +subcommand and arguments. The following aliases are built-in to Cargo: + +```toml +[alias] +b = "build" +c = "check" +d = "doc" +t = "test" +r = "run" +rm = "remove" +``` + +Aliases are not allowed to redefine existing built-in commands. + +Aliases are recursive: + +```toml +[alias] +rr = "run --release" +recursive_example = "rr --example recursions" +``` + +#### `[build]` + +The `[build]` table controls build-time operations and compiler settings. + +##### `build.jobs` +* Type: integer +* Default: number of logical CPUs +* Environment: `CARGO_BUILD_JOBS` + +Sets the maximum number of compiler processes to run in parallel. If negative, +it sets the maximum number of compiler processes to the number of logical CPUs +plus provided value. Should not be 0. + +Can be overridden with the `--jobs` CLI option. + +##### `build.rustc` +* Type: string (program path) +* Default: "rustc" +* Environment: `CARGO_BUILD_RUSTC` or `RUSTC` + +Sets the executable to use for `rustc`. + +##### `build.rustc-wrapper` +* Type: string (program path) +* Default: none +* Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER` + +Sets a wrapper to execute instead of `rustc`. The first argument passed to the +wrapper is the path to the actual executable to use +(i.e., `build.rustc`, if that is set, or `"rustc"` otherwise). + +##### `build.rustc-workspace-wrapper` +* Type: string (program path) +* Default: none +* Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER` + +Sets a wrapper to execute instead of `rustc`, for workspace members only. +The first argument passed to the wrapper is the path to the actual +executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise). +It affects the filename hash so that artifacts produced by the wrapper are cached separately. + +##### `build.rustdoc` +* Type: string (program path) +* Default: "rustdoc" +* Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC` + +Sets the executable to use for `rustdoc`. + +##### `build.target` +* Type: string or array of strings +* Default: host platform +* Environment: `CARGO_BUILD_TARGET` + +The default [target platform triples][target triple] to compile to. + +This allows passing either a string or an array of strings. Each string value +is a target platform triple. The selected build targets will be built for each +of the selected architectures. + +The string value may also be a relative path to a `.json` target spec file. + +Can be overridden with the `--target` CLI option. + +```toml +[build] +target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"] +``` + +##### `build.target-dir` +* Type: string (path) +* Default: "target" +* Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR` + +The path to where all compiler output is placed. The default if not specified +is a directory named `target` located at the root of the workspace. + +Can be overridden with the `--target-dir` CLI option. + +##### `build.rustflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS` + +Extra command-line flags to pass to `rustc`. The value may be an array of +strings or a space-separated string. + +There are four mutually exclusive sources of extra flags. They are checked in +order, with the first one being used: + +1. `CARGO_ENCODED_RUSTFLAGS` environment variable. +2. `RUSTFLAGS` environment variable. +3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags` + config entries joined together. +4. `build.rustflags` config value. + +Additional flags may also be passed with the [`cargo rustc`] command. + +If the `--target` flag (or [`build.target`](#buildtarget)) is used, then the +flags will only be passed to the compiler for the target. Things being built +for the host, such as build scripts or proc macros, will not receive the args. +Without `--target`, the flags will be passed to all compiler invocations +(including build scripts and proc macros) because dependencies are shared. If +you have args that you do not want to pass to build scripts or proc macros and +are building for the host, pass `--target` with the [host triple][target triple]. + +It is not recommended to pass in flags that Cargo itself usually manages. For +example, the flags driven by [profiles](profiles.md) are best handled by setting the +appropriate profile setting. + +> **Caution**: Due to the low-level nature of passing flags directly to the +> compiler, this may cause a conflict with future versions of Cargo which may +> issue the same or similar flags on its own which may interfere with the +> flags you specify. This is an area where Cargo may not always be backwards +> compatible. + +##### `build.rustdocflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS` + +Extra command-line flags to pass to `rustdoc`. The value may be an array of +strings or a space-separated string. + +There are three mutually exclusive sources of extra flags. They are checked in +order, with the first one being used: + +1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable. +2. `RUSTDOCFLAGS` environment variable. +3. `build.rustdocflags` config value. + +Additional flags may also be passed with the [`cargo rustdoc`] command. + +##### `build.incremental` +* Type: bool +* Default: from profile +* Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL` + +Whether or not to perform [incremental compilation]. The default if not set is +to use the value from the [profile](profiles.md#incremental). Otherwise this overrides the setting of +all profiles. + +The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable +incremental compilation for all profiles, or `0` to disable it. This env var +overrides the config setting. + +##### `build.dep-info-basedir` +* Type: string (path) +* Default: none +* Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` + +Strips the given path prefix from [dep +info](../guide/build-cache.md#dep-info-files) file paths. This config setting +is intended to convert absolute paths to relative paths for tools that require +relative paths. + +The setting itself is a config-relative path. So, for example, a value of +`"."` would strip all paths starting with the parent directory of the `.cargo` +directory. + +##### `build.pipelining` + +This option is deprecated and unused. Cargo always has pipelining enabled. + +#### `[doc]` + +The `[doc]` table defines options for the [`cargo doc`] command. + +##### `doc.browser` + +* Type: string or array of strings ([program path with args]) +* Default: `BROWSER` environment variable, or, if that is missing, + opening the link in a system specific way + +This option sets the browser to be used by [`cargo doc`], overriding the +`BROWSER` environment variable when opening documentation with the `--open` +option. + +#### `[cargo-new]` + +The `[cargo-new]` table defines defaults for the [`cargo new`] command. + +##### `cargo-new.name` + +This option is deprecated and unused. + +##### `cargo-new.email` + +This option is deprecated and unused. + +##### `cargo-new.vcs` +* Type: string +* Default: "git" or "none" +* Environment: `CARGO_CARGO_NEW_VCS` + +Specifies the source control system to use for initializing a new repository. +Valid values are `git`, `hg` (for Mercurial), `pijul`, `fossil` or `none` to +disable this behavior. Defaults to `git`, or `none` if already inside a VCS +repository. Can be overridden with the `--vcs` CLI option. + +### `[env]` + +The `[env]` section allows you to set additional environment variables for +build scripts, rustc invocations, `cargo run` and `cargo build`. + +```toml +[env] +OPENSSL_DIR = "/opt/openssl" +``` + +By default, the variables specified will not override values that already exist +in the environment. This behavior can be changed by setting the `force` flag. + +Setting the `relative` flag evaluates the value as a config-relative path that +is relative to the parent directory of the `.cargo` directory that contains the +`config.toml` file. The value of the environment variable will be the full +absolute path. + +```toml +[env] +TMPDIR = { value = "/home/tmp", force = true } +OPENSSL_DIR = { value = "vendor/openssl", relative = true } +``` + +### `[future-incompat-report]` + +The `[future-incompat-report]` table controls setting for [future incompat reporting](future-incompat-report.md) + +#### `future-incompat-report.frequency` +* Type: string +* Default: "always" +* Environment: `CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY` + +Controls how often we display a notification to the terminal when a future incompat report is available. Possible values: + +* `always` (default): Always display a notification when a command (e.g. `cargo build`) produces a future incompat report +* `never`: Never display a notification + +#### `[http]` + +The `[http]` table defines settings for HTTP behavior. This includes fetching +crate dependencies and accessing remote git repositories. + +##### `http.debug` +* Type: boolean +* Default: false +* Environment: `CARGO_HTTP_DEBUG` + +If `true`, enables debugging of HTTP requests. The debug information can be +seen by setting the `CARGO_LOG=cargo::ops::registry=debug` environment +variable (or use `trace` for even more information). + +Be wary when posting logs from this output in a public location. The output +may include headers with authentication tokens which you don't want to leak! +Be sure to review logs before posting them. + +##### `http.proxy` +* Type: string +* Default: none +* Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy` + +Sets an HTTP and HTTPS proxy to use. The format is in [libcurl format] as in +`[protocol://]host[:port]`. If not set, Cargo will also check the `http.proxy` +setting in your global git configuration. If none of those are set, the +`HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS +requests, and `http_proxy` sets it for HTTP requests. + +##### `http.timeout` +* Type: integer +* Default: 30 +* Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT` + +Sets the timeout for each HTTP request, in seconds. + +##### `http.cainfo` +* Type: string (path) +* Default: none +* Environment: `CARGO_HTTP_CAINFO` + +Path to a Certificate Authority (CA) bundle file, used to verify TLS +certificates. If not specified, Cargo attempts to use the system certificates. + +##### `http.check-revoke` +* Type: boolean +* Default: true (Windows) false (all others) +* Environment: `CARGO_HTTP_CHECK_REVOKE` + +This determines whether or not TLS certificate revocation checks should be +performed. This only works on Windows. + +##### `http.ssl-version` +* Type: string or min/max table +* Default: none +* Environment: `CARGO_HTTP_SSL_VERSION` + +This sets the minimum TLS version to use. It takes a string, with one of the +possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or +"tlsv1.3". + +This may alternatively take a table with two keys, `min` and `max`, which each +take a string value of the same kind that specifies the minimum and maximum +range of TLS versions to use. + +The default is a minimum version of "tlsv1.0" and a max of the newest version +supported on your platform, typically "tlsv1.3". + +##### `http.low-speed-limit` +* Type: integer +* Default: 10 +* Environment: `CARGO_HTTP_LOW_SPEED_LIMIT` + +This setting controls timeout behavior for slow connections. If the average +transfer speed in bytes per second is below the given value for +[`http.timeout`](#httptimeout) seconds (default 30 seconds), then the +connection is considered too slow and Cargo will abort and retry. + +##### `http.multiplexing` +* Type: boolean +* Default: true +* Environment: `CARGO_HTTP_MULTIPLEXING` + +When `true`, Cargo will attempt to use the HTTP2 protocol with multiplexing. +This allows multiple requests to use the same connection, usually improving +performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1 +without pipelining. + +##### `http.user-agent` +* Type: string +* Default: Cargo's version +* Environment: `CARGO_HTTP_USER_AGENT` + +Specifies a custom user-agent header to use. The default if not specified is a +string that includes Cargo's version. + +#### `[install]` + +The `[install]` table defines defaults for the [`cargo install`] command. + +##### `install.root` +* Type: string (path) +* Default: Cargo's home directory +* Environment: `CARGO_INSTALL_ROOT` + +Sets the path to the root directory for installing executables for [`cargo +install`]. Executables go into a `bin` directory underneath the root. + +To track information of installed executables, some extra files, such as +`.crates.toml` and `.crates2.json`, are also created under this root. + +The default if not specified is Cargo's home directory (default `.cargo` in +your home directory). + +Can be overridden with the `--root` command-line option. + +#### `[net]` + +The `[net]` table controls networking configuration. + +##### `net.retry` +* Type: integer +* Default: 2 +* Environment: `CARGO_NET_RETRY` + +Number of times to retry possibly spurious network errors. + +##### `net.git-fetch-with-cli` +* Type: boolean +* Default: false +* Environment: `CARGO_NET_GIT_FETCH_WITH_CLI` + +If this is `true`, then Cargo will use the `git` executable to fetch registry +indexes and git dependencies. If `false`, then it uses a built-in `git` +library. + +Setting this to `true` can be helpful if you have special authentication +requirements that Cargo does not support. See [Git +Authentication](../appendix/git-authentication.md) for more information about +setting up git authentication. + +##### `net.offline` +* Type: boolean +* Default: false +* Environment: `CARGO_NET_OFFLINE` + +If this is `true`, then Cargo will avoid accessing the network, and attempt to +proceed with locally cached data. If `false`, Cargo will access the network as +needed, and generate an error if it encounters a network error. + +Can be overridden with the `--offline` command-line option. + +##### `net.ssh` + +The `[net.ssh]` table contains settings for SSH connections. + +##### `net.ssh.known-hosts` +* Type: array of strings +* Default: see description +* Environment: not supported + +The `known-hosts` array contains a list of SSH host keys that should be +accepted as valid when connecting to an SSH server (such as for SSH git +dependencies). Each entry should be a string in a format similar to OpenSSH +`known_hosts` files. Each string should start with one or more hostnames +separated by commas, a space, the key type name, a space, and the +base64-encoded key. For example: + +```toml +[net.ssh] +known-hosts = [ + "example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFO4Q5T0UV0SQevair9PFwoxY9dl4pQl3u5phoqJH3cF" +] +``` + +Cargo will attempt to load known hosts keys from common locations supported in +OpenSSH, and will join those with any listed in a Cargo configuration file. +If any matching entry has the correct key, the connection will be allowed. + +Cargo comes with the host keys for [github.com][github-keys] built-in. If +those ever change, you can add the new keys to the config or known_hosts file. + +See [Git Authentication](../appendix/git-authentication.md#ssh-known-hosts) +for more details. + +[github-keys]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints + +#### `[patch]` + +Just as you can override dependencies using [`[patch]` in +`Cargo.toml`](overriding-dependencies.md#the-patch-section), you can +override them in the cargo configuration file to apply those patches to +any affected build. The format is identical to the one used in +`Cargo.toml`. + +Since `.cargo/config.toml` files are not usually checked into source +control, you should prefer patching using `Cargo.toml` where possible to +ensure that other developers can compile your crate in their own +environments. Patching through cargo configuration files is generally +only appropriate when the patch section is automatically generated by an +external build tool. + +If a given dependency is patched both in a cargo configuration file and +a `Cargo.toml` file, the patch in the configuration file is used. If +multiple configuration files patch the same dependency, standard cargo +configuration merging is used, which prefers the value defined closest +to the current directory, with `$HOME/.cargo/config.toml` taking the +lowest precedence. + +Relative `path` dependencies in such a `[patch]` section are resolved +relative to the configuration file they appear in. + +#### `[profile]` + +The `[profile]` table can be used to globally change profile settings, and +override settings specified in `Cargo.toml`. It has the same syntax and +options as profiles specified in `Cargo.toml`. See the [Profiles chapter] for +details about the options. + +[Profiles chapter]: profiles.md + +##### `[profile.<name>.build-override]` +* Environment: `CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>` + +The build-override table overrides settings for build scripts, proc macros, +and their dependencies. It has the same keys as a normal profile. See the +[overrides section](profiles.md#overrides) for more details. + +##### `[profile.<name>.package.<name>]` +* Environment: not supported + +The package table overrides settings for specific packages. It has the same +keys as a normal profile, minus the `panic`, `lto`, and `rpath` settings. See +the [overrides section](profiles.md#overrides) for more details. + +##### `profile.<name>.codegen-units` +* Type: integer +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_CODEGEN_UNITS` + +See [codegen-units](profiles.md#codegen-units). + +##### `profile.<name>.debug` +* Type: integer or boolean +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_DEBUG` + +See [debug](profiles.md#debug). + +##### `profile.<name>.split-debuginfo` +* Type: string +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_SPLIT_DEBUGINFO` + +See [split-debuginfo](profiles.md#split-debuginfo). + +##### `profile.<name>.debug-assertions` +* Type: boolean +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_DEBUG_ASSERTIONS` + +See [debug-assertions](profiles.md#debug-assertions). + +##### `profile.<name>.incremental` +* Type: boolean +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_INCREMENTAL` + +See [incremental](profiles.md#incremental). + +##### `profile.<name>.lto` +* Type: string or boolean +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_LTO` + +See [lto](profiles.md#lto). + +##### `profile.<name>.overflow-checks` +* Type: boolean +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_OVERFLOW_CHECKS` + +See [overflow-checks](profiles.md#overflow-checks). + +##### `profile.<name>.opt-level` +* Type: integer or string +* Default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_OPT_LEVEL` + +See [opt-level](profiles.md#opt-level). + +##### `profile.<name>.panic` +* Type: string +* default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_PANIC` + +See [panic](profiles.md#panic). + +##### `profile.<name>.rpath` +* Type: boolean +* default: See profile docs. +* Environment: `CARGO_PROFILE_<name>_RPATH` + +See [rpath](profiles.md#rpath). + + +#### `[registries]` + +The `[registries]` table is used for specifying additional [registries]. It +consists of a sub-table for each named registry. + +##### `registries.<name>.index` +* Type: string (url) +* Default: none +* Environment: `CARGO_REGISTRIES_<name>_INDEX` + +Specifies the URL of the git index for the registry. + +##### `registries.<name>.token` +* Type: string +* Default: none +* Environment: `CARGO_REGISTRIES_<name>_TOKEN` + +Specifies the authentication token for the given registry. This value should +only appear in the [credentials](#credentials) file. This is used for registry +commands like [`cargo publish`] that require authentication. + +Can be overridden with the `--token` command-line option. + +##### `registries.crates-io.protocol` +* Type: string +* Default: `git` +* Environment: `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` + +Specifies the protocol used to access crates.io. Allowed values are `git` or `sparse`. + +`git` causes Cargo to clone the entire index of all packages ever published to [crates.io] from <https://github.com/rust-lang/crates.io-index/>. +This can have performance implications due to the size of the index. +`sparse` is a newer protocol which uses HTTPS to download only what is necessary from <https://index.crates.io/>. +This can result in a significant performance improvement for resolving new dependencies in most situations. + +More information about registry protocols may be found in the [Registries chapter](registries.md). + +#### `[registry]` + +The `[registry]` table controls the default registry used when one is not +specified. + +##### `registry.index` + +This value is no longer accepted and should not be used. + +##### `registry.default` +* Type: string +* Default: `"crates-io"` +* Environment: `CARGO_REGISTRY_DEFAULT` + +The name of the registry (from the [`registries` table](#registries)) to use +by default for registry commands like [`cargo publish`]. + +Can be overridden with the `--registry` command-line option. + +##### `registry.token` +* Type: string +* Default: none +* Environment: `CARGO_REGISTRY_TOKEN` + +Specifies the authentication token for [crates.io]. This value should only +appear in the [credentials](#credentials) file. This is used for registry +commands like [`cargo publish`] that require authentication. + +Can be overridden with the `--token` command-line option. + +#### `[source]` + +The `[source]` table defines the registry sources available. See [Source +Replacement] for more information. It consists of a sub-table for each named +source. A source should only define one kind (directory, registry, +local-registry, or git). + +##### `source.<name>.replace-with` +* Type: string +* Default: none +* Environment: not supported + +If set, replace this source with the given named source or named registry. + +##### `source.<name>.directory` +* Type: string (path) +* Default: none +* Environment: not supported + +Sets the path to a directory to use as a directory source. + +##### `source.<name>.registry` +* Type: string (url) +* Default: none +* Environment: not supported + +Sets the URL to use for a registry source. + +##### `source.<name>.local-registry` +* Type: string (path) +* Default: none +* Environment: not supported + +Sets the path to a directory to use as a local registry source. + +##### `source.<name>.git` +* Type: string (url) +* Default: none +* Environment: not supported + +Sets the URL to use for a git repository source. + +##### `source.<name>.branch` +* Type: string +* Default: none +* Environment: not supported + +Sets the branch name to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + +##### `source.<name>.tag` +* Type: string +* Default: none +* Environment: not supported + +Sets the tag name to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + +##### `source.<name>.rev` +* Type: string +* Default: none +* Environment: not supported + +Sets the [revision] to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + + +#### `[target]` + +The `[target]` table is used for specifying settings for specific platform +targets. It consists of a sub-table which is either a [platform triple][target triple] +or a [`cfg()` expression]. The given values will be used if the target platform +matches either the `<triple>` value or the `<cfg>` expression. + +```toml +[target.thumbv7m-none-eabi] +linker = "arm-none-eabi-gcc" +runner = "my-emulator" +rustflags = ["…", "…"] + +[target.'cfg(all(target_arch = "arm", target_os = "none"))'] +runner = "my-arm-wrapper" +rustflags = ["…", "…"] +``` + +`cfg` values come from those built-in to the compiler (run `rustc --print=cfg` +to view), values set by [build scripts], and extra `--cfg` flags passed to +`rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on +`debug_assertions` or Cargo features like `feature="foo"`. + +If using a target spec JSON file, the [`<triple>`] value is the filename stem. +For example `--target foo/bar.json` would match `[target.bar]`. + +##### `target.<triple>.ar` + +This option is deprecated and unused. + +##### `target.<triple>.linker` +* Type: string (program path) +* Default: none +* Environment: `CARGO_TARGET_<triple>_LINKER` + +Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the +[`<triple>`] is being compiled for. By default, the linker is not overridden. + +##### `target.<triple>.runner` +* Type: string or array of strings ([program path with args]) +* Default: none +* Environment: `CARGO_TARGET_<triple>_RUNNER` + +If a runner is provided, executables for the target [`<triple>`] will be +executed by invoking the specified runner with the actual executable passed as +an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] +commands. By default, compiled executables are executed directly. + +##### `target.<cfg>.runner` + +This is similar to the [target runner](#targettriplerunner), but using +a [`cfg()` expression]. If both a [`<triple>`] and `<cfg>` runner match, +the `<triple>` will take precedence. It is an error if more than one +`<cfg>` runner matches the current target. + +##### `target.<triple>.rustflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_TARGET_<triple>_RUSTFLAGS` + +Passes a set of custom flags to the compiler for this [`<triple>`]. +The value may be an array of strings or a space-separated string. + +See [`build.rustflags`](#buildrustflags) for more details on the different +ways to specific extra flags. + +##### `target.<cfg>.rustflags` + +This is similar to the [target rustflags](#targettriplerustflags), but +using a [`cfg()` expression]. If several `<cfg>` and [`<triple>`] entries +match the current target, the flags are joined together. + +##### `target.<triple>.<links>` + +The links sub-table provides a way to [override a build script]. When +specified, the build script for the given `links` library will not be +run, and the given values will be used instead. + +```toml +[target.x86_64-unknown-linux-gnu.foo] +rustc-link-lib = ["foo"] +rustc-link-search = ["/path/to/foo"] +rustc-flags = "-L /some/path" +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" +``` + +#### `[term]` + +The `[term]` table controls terminal output and interaction. + +##### `term.quiet` +* Type: boolean +* Default: false +* Environment: `CARGO_TERM_QUIET` + +Controls whether or not log messages are displayed by Cargo. + +Specifying the `--quiet` flag will override and force quiet output. +Specifying the `--verbose` flag will override and disable quiet output. + +##### `term.verbose` +* Type: boolean +* Default: false +* Environment: `CARGO_TERM_VERBOSE` + +Controls whether or not extra detailed messages are displayed by Cargo. + +Specifying the `--quiet` flag will override and disable verbose output. +Specifying the `--verbose` flag will override and force verbose output. + +##### `term.color` +* Type: string +* Default: "auto" +* Environment: `CARGO_TERM_COLOR` + +Controls whether or not colored output is used in the terminal. Possible values: + +* `auto` (default): Automatically detect if color support is available on the + terminal. +* `always`: Always display colors. +* `never`: Never display colors. + +Can be overridden with the `--color` command-line option. + +##### `term.progress.when` +* Type: string +* Default: "auto" +* Environment: `CARGO_TERM_PROGRESS_WHEN` + +Controls whether or not progress bar is shown in the terminal. Possible values: + +* `auto` (default): Intelligently guess whether to show progress bar. +* `always`: Always show progress bar. +* `never`: Never show progress bar. + +##### `term.progress.width` +* Type: integer +* Default: none +* Environment: `CARGO_TERM_PROGRESS_WIDTH` + +Sets the width for progress bar. + +[`cargo bench`]: ../commands/cargo-bench.md +[`cargo login`]: ../commands/cargo-login.md +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo new`]: ../commands/cargo-new.md +[`cargo publish`]: ../commands/cargo-publish.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo rustc`]: ../commands/cargo-rustc.md +[`cargo test`]: ../commands/cargo-test.md +[`cargo rustdoc`]: ../commands/cargo-rustdoc.md +[`cargo install`]: ../commands/cargo-install.md +[env]: environment-variables.md +[`cfg()` expression]: ../../reference/conditional-compilation.html +[build scripts]: build-scripts.md +[`-C linker`]: ../../rustc/codegen-options/index.md#linker +[override a build script]: build-scripts.md#overriding-build-scripts +[toml]: https://toml.io/ +[incremental compilation]: profiles.md#incremental +[program path with args]: #executable-paths-with-arguments +[libcurl format]: https://everything.curl.dev/libcurl/proxies#proxy-types +[source replacement]: source-replacement.md +[revision]: https://git-scm.com/docs/gitrevisions +[registries]: registries.md +[crates.io]: https://crates.io/ +[target triple]: ../appendix/glossary.md#target '"target" (glossary)' +[`<triple>`]: ../appendix/glossary.md#target '"target" (glossary)' diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md new file mode 100644 index 0000000..2ed986f --- /dev/null +++ b/src/doc/src/reference/environment-variables.md @@ -0,0 +1,417 @@ +## Environment Variables + +Cargo sets and reads a number of environment variables which your code can detect +or override. Here is a list of the variables Cargo sets, organized by when it interacts +with them: + +### Environment variables Cargo reads + +You can override these environment variables to change Cargo's behavior on your +system: + +* `CARGO_LOG` --- Cargo uses the [`env_logger`] crate to display debug log messages. + The `CARGO_LOG` environment variable can be set to enable debug logging, + with a value such as `trace`, `debug`, or `warn`. + Usually it is only used during debugging. For more details refer to the + [Debug logging]. +* `CARGO_HOME` --- Cargo maintains a local cache of the registry index and of + git checkouts of crates. By default these are stored under `$HOME/.cargo` + (`%USERPROFILE%\.cargo` on Windows), but this variable overrides the + location of this directory. Once a crate is cached it is not removed by the + clean command. + For more details refer to the [guide](../guide/cargo-home.md). +* `CARGO_TARGET_DIR` --- Location of where to place all generated artifacts, + relative to the current working directory. See [`build.target-dir`] to set + via config. +* `CARGO` --- If set, Cargo will forward this value instead of setting it + to its own auto-detected path when it builds crates and when it + executes build scripts and external subcommands. This value is not + directly executed by Cargo, and should always point at a command that + behaves exactly like `cargo`, as that's what users of the variable + will be expecting. +* `RUSTC` --- Instead of running `rustc`, Cargo will execute this specified + compiler instead. See [`build.rustc`] to set via config. +* `RUSTC_WRAPPER` --- Instead of simply running `rustc`, Cargo will execute this + specified wrapper, passing as its command-line arguments the rustc + invocation, with the first argument being the path to the actual rustc. + Useful to set up a build cache tool such as `sccache`. See + [`build.rustc-wrapper`] to set via config. Setting this to the empty string + overwrites the config and resets cargo to not use a wrapper. +* `RUSTC_WORKSPACE_WRAPPER` --- Instead of simply running `rustc`, for workspace + members Cargo will execute this specified wrapper, passing + as its command-line arguments the rustc invocation, with the first argument + being the path to the actual rustc. It affects the filename hash + so that artifacts produced by the wrapper are cached separately. + See [`build.rustc-workspace-wrapper`] to set via config. Setting this to the empty string + overwrites the config and resets cargo to not use a wrapper for workspace members. +* `RUSTDOC` --- Instead of running `rustdoc`, Cargo will execute this specified + `rustdoc` instance instead. See [`build.rustdoc`] to set via config. +* `RUSTDOCFLAGS` --- A space-separated list of custom flags to pass to all `rustdoc` + invocations that Cargo performs. In contrast with [`cargo rustdoc`], this is + useful for passing a flag to *all* `rustdoc` instances. See + [`build.rustdocflags`] for some more ways to set flags. This string is + split by whitespace; for a more robust encoding of multiple arguments, + see `CARGO_ENCODED_RUSTDOCFLAGS`. +* `CARGO_ENCODED_RUSTDOCFLAGS` --- A list of custom flags separated by `0x1f` + (ASCII Unit Separator) to pass to all `rustdoc` invocations that Cargo performs. +* `RUSTFLAGS` --- A space-separated list of custom flags to pass to all compiler + invocations that Cargo performs. In contrast with [`cargo rustc`], this is + useful for passing a flag to *all* compiler instances. See + [`build.rustflags`] for some more ways to set flags. This string is + split by whitespace; for a more robust encoding of multiple arguments, + see `CARGO_ENCODED_RUSTFLAGS`. +* `CARGO_ENCODED_RUSTFLAGS` --- A list of custom flags separated by `0x1f` + (ASCII Unit Separator) to pass to all compiler invocations that Cargo performs. +* `CARGO_INCREMENTAL` --- If this is set to 1 then Cargo will force [incremental + compilation] to be enabled for the current compilation, and when set to 0 it + will force disabling it. If this env var isn't present then cargo's defaults + will otherwise be used. See also [`build.incremental`] config value. +* `CARGO_CACHE_RUSTC_INFO` --- If this is set to 0 then Cargo will not try to cache + compiler version information. +* `HTTPS_PROXY` or `https_proxy` or `http_proxy` --- The HTTP proxy to use, see + [`http.proxy`] for more detail. +* `HTTP_TIMEOUT` --- The HTTP timeout in seconds, see [`http.timeout`] for more + detail. +* `TERM` --- If this is set to `dumb`, it disables the progress bar. +* `BROWSER` --- The web browser to execute to open documentation with [`cargo + doc`]'s' `--open` flag, see [`doc.browser`] for more details. +* `RUSTFMT` --- Instead of running `rustfmt`, + [`cargo fmt`](https://github.com/rust-lang/rustfmt) will execute this specified + `rustfmt` instance instead. + +#### Configuration environment variables + +Cargo reads environment variables for some configuration values. +See the [configuration chapter][config-env] for more details. +In summary, the supported environment variables are: + +* `CARGO_ALIAS_<name>` --- Command aliases, see [`alias`]. +* `CARGO_BUILD_JOBS` --- Number of parallel jobs, see [`build.jobs`]. +* `CARGO_BUILD_RUSTC` --- The `rustc` executable, see [`build.rustc`]. +* `CARGO_BUILD_RUSTC_WRAPPER` --- The `rustc` wrapper, see [`build.rustc-wrapper`]. +* `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` --- The `rustc` wrapper for workspace members only, see [`build.rustc-workspace-wrapper`]. +* `CARGO_BUILD_RUSTDOC` --- The `rustdoc` executable, see [`build.rustdoc`]. +* `CARGO_BUILD_TARGET` --- The default target platform, see [`build.target`]. +* `CARGO_BUILD_TARGET_DIR` --- The default output directory, see [`build.target-dir`]. +* `CARGO_BUILD_RUSTFLAGS` --- Extra `rustc` flags, see [`build.rustflags`]. +* `CARGO_BUILD_RUSTDOCFLAGS` --- Extra `rustdoc` flags, see [`build.rustdocflags`]. +* `CARGO_BUILD_INCREMENTAL` --- Incremental compilation, see [`build.incremental`]. +* `CARGO_BUILD_DEP_INFO_BASEDIR` --- Dep-info relative directory, see [`build.dep-info-basedir`]. +* `CARGO_CARGO_NEW_VCS` --- The default source control system with [`cargo new`], see [`cargo-new.vcs`]. +* `CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY` --- How often we should generate a future incompat report notification, see [`future-incompat-report.frequency`]. +* `CARGO_HTTP_DEBUG` --- Enables HTTP debugging, see [`http.debug`]. +* `CARGO_HTTP_PROXY` --- Enables HTTP proxy, see [`http.proxy`]. +* `CARGO_HTTP_TIMEOUT` --- The HTTP timeout, see [`http.timeout`]. +* `CARGO_HTTP_CAINFO` --- The TLS certificate Certificate Authority file, see [`http.cainfo`]. +* `CARGO_HTTP_CHECK_REVOKE` --- Disables TLS certificate revocation checks, see [`http.check-revoke`]. +* `CARGO_HTTP_SSL_VERSION` --- The TLS version to use, see [`http.ssl-version`]. +* `CARGO_HTTP_LOW_SPEED_LIMIT` --- The HTTP low-speed limit, see [`http.low-speed-limit`]. +* `CARGO_HTTP_MULTIPLEXING` --- Whether HTTP/2 multiplexing is used, see [`http.multiplexing`]. +* `CARGO_HTTP_USER_AGENT` --- The HTTP user-agent header, see [`http.user-agent`]. +* `CARGO_INSTALL_ROOT` --- The default directory for [`cargo install`], see [`install.root`]. +* `CARGO_NET_RETRY` --- Number of times to retry network errors, see [`net.retry`]. +* `CARGO_NET_GIT_FETCH_WITH_CLI` --- Enables the use of the `git` executable to fetch, see [`net.git-fetch-with-cli`]. +* `CARGO_NET_OFFLINE` --- Offline mode, see [`net.offline`]. +* `CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>` --- Override build script profile, see [`profile.<name>.build-override`]. +* `CARGO_PROFILE_<name>_CODEGEN_UNITS` --- Set code generation units, see [`profile.<name>.codegen-units`]. +* `CARGO_PROFILE_<name>_DEBUG` --- What kind of debug info to include, see [`profile.<name>.debug`]. +* `CARGO_PROFILE_<name>_DEBUG_ASSERTIONS` --- Enable/disable debug assertions, see [`profile.<name>.debug-assertions`]. +* `CARGO_PROFILE_<name>_INCREMENTAL` --- Enable/disable incremental compilation, see [`profile.<name>.incremental`]. +* `CARGO_PROFILE_<name>_LTO` --- Link-time optimization, see [`profile.<name>.lto`]. +* `CARGO_PROFILE_<name>_OVERFLOW_CHECKS` --- Enable/disable overflow checks, see [`profile.<name>.overflow-checks`]. +* `CARGO_PROFILE_<name>_OPT_LEVEL` --- Set the optimization level, see [`profile.<name>.opt-level`]. +* `CARGO_PROFILE_<name>_PANIC` --- The panic strategy to use, see [`profile.<name>.panic`]. +* `CARGO_PROFILE_<name>_RPATH` --- The rpath linking option, see [`profile.<name>.rpath`]. +* `CARGO_PROFILE_<name>_SPLIT_DEBUGINFO` --- Controls debug file output behavior, see [`profile.<name>.split-debuginfo`]. +* `CARGO_REGISTRIES_<name>_INDEX` --- URL of a registry index, see [`registries.<name>.index`]. +* `CARGO_REGISTRIES_<name>_TOKEN` --- Authentication token of a registry, see [`registries.<name>.token`]. +* `CARGO_REGISTRY_DEFAULT` --- Default registry for the `--registry` flag, see [`registry.default`]. +* `CARGO_REGISTRY_TOKEN` --- Authentication token for [crates.io], see [`registry.token`]. +* `CARGO_TARGET_<triple>_LINKER` --- The linker to use, see [`target.<triple>.linker`]. The triple must be [converted to uppercase and underscores](config.md#environment-variables). +* `CARGO_TARGET_<triple>_RUNNER` --- The executable runner, see [`target.<triple>.runner`]. +* `CARGO_TARGET_<triple>_RUSTFLAGS` --- Extra `rustc` flags for a target, see [`target.<triple>.rustflags`]. +* `CARGO_TERM_QUIET` --- Quiet mode, see [`term.quiet`]. +* `CARGO_TERM_VERBOSE` --- The default terminal verbosity, see [`term.verbose`]. +* `CARGO_TERM_COLOR` --- The default color mode, see [`term.color`]. +* `CARGO_TERM_PROGRESS_WHEN` --- The default progress bar showing mode, see [`term.progress.when`]. +* `CARGO_TERM_PROGRESS_WIDTH` --- The default progress bar width, see [`term.progress.width`]. + +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo new`]: ../commands/cargo-new.md +[`cargo rustc`]: ../commands/cargo-rustc.md +[`cargo rustdoc`]: ../commands/cargo-rustdoc.md +[config-env]: config.md#environment-variables +[crates.io]: https://crates.io/ +[incremental compilation]: profiles.md#incremental +[`alias`]: config.md#alias +[`build.jobs`]: config.md#buildjobs +[`build.rustc`]: config.md#buildrustc +[`build.rustc-wrapper`]: config.md#buildrustc-wrapper +[`build.rustc-workspace-wrapper`]: config.md#buildrustc-workspace-wrapper +[`build.rustdoc`]: config.md#buildrustdoc +[`build.target`]: config.md#buildtarget +[`build.target-dir`]: config.md#buildtarget-dir +[`build.rustflags`]: config.md#buildrustflags +[`build.rustdocflags`]: config.md#buildrustdocflags +[`build.incremental`]: config.md#buildincremental +[`build.dep-info-basedir`]: config.md#builddep-info-basedir +[`doc.browser`]: config.md#docbrowser +[`cargo-new.name`]: config.md#cargo-newname +[`cargo-new.email`]: config.md#cargo-newemail +[`cargo-new.vcs`]: config.md#cargo-newvcs +[`future-incompat-report.frequency`]: config.md#future-incompat-reportfrequency +[`http.debug`]: config.md#httpdebug +[`http.proxy`]: config.md#httpproxy +[`http.timeout`]: config.md#httptimeout +[`http.cainfo`]: config.md#httpcainfo +[`http.check-revoke`]: config.md#httpcheck-revoke +[`http.ssl-version`]: config.md#httpssl-version +[`http.low-speed-limit`]: config.md#httplow-speed-limit +[`http.multiplexing`]: config.md#httpmultiplexing +[`http.user-agent`]: config.md#httpuser-agent +[`install.root`]: config.md#installroot +[`net.retry`]: config.md#netretry +[`net.git-fetch-with-cli`]: config.md#netgit-fetch-with-cli +[`net.offline`]: config.md#netoffline +[`profile.<name>.build-override`]: config.md#profilenamebuild-override +[`profile.<name>.codegen-units`]: config.md#profilenamecodegen-units +[`profile.<name>.debug`]: config.md#profilenamedebug +[`profile.<name>.debug-assertions`]: config.md#profilenamedebug-assertions +[`profile.<name>.incremental`]: config.md#profilenameincremental +[`profile.<name>.lto`]: config.md#profilenamelto +[`profile.<name>.overflow-checks`]: config.md#profilenameoverflow-checks +[`profile.<name>.opt-level`]: config.md#profilenameopt-level +[`profile.<name>.panic`]: config.md#profilenamepanic +[`profile.<name>.rpath`]: config.md#profilenamerpath +[`profile.<name>.split-debuginfo`]: config.md#profilenamesplit-debuginfo +[`registries.<name>.index`]: config.md#registriesnameindex +[`registries.<name>.token`]: config.md#registriesnametoken +[`registry.default`]: config.md#registrydefault +[`registry.token`]: config.md#registrytoken +[`target.<triple>.linker`]: config.md#targettriplelinker +[`target.<triple>.runner`]: config.md#targettriplerunner +[`target.<triple>.rustflags`]: config.md#targettriplerustflags +[`term.quiet`]: config.md#termquiet +[`term.verbose`]: config.md#termverbose +[`term.color`]: config.md#termcolor +[`term.progress.when`]: config.md#termprogresswhen +[`term.progress.width`]: config.md#termprogresswidth + +### Environment variables Cargo sets for crates + +Cargo exposes these environment variables to your crate when it is compiled. +Note that this applies for running binaries with `cargo run` and `cargo test` +as well. To get the value of any of these variables in a Rust program, do +this: + +```rust,ignore +let version = env!("CARGO_PKG_VERSION"); +``` + +`version` will now contain the value of `CARGO_PKG_VERSION`. + +Note that if one of these values is not provided in the manifest, the +corresponding environment variable is set to the empty string, `""`. + +* `CARGO` --- Path to the `cargo` binary performing the build. +* `CARGO_MANIFEST_DIR` --- The directory containing the manifest of your package. +* `CARGO_PKG_VERSION` --- The full version of your package. +* `CARGO_PKG_VERSION_MAJOR` --- The major version of your package. +* `CARGO_PKG_VERSION_MINOR` --- The minor version of your package. +* `CARGO_PKG_VERSION_PATCH` --- The patch version of your package. +* `CARGO_PKG_VERSION_PRE` --- The pre-release version of your package. +* `CARGO_PKG_AUTHORS` --- Colon separated list of authors from the manifest of your package. +* `CARGO_PKG_NAME` --- The name of your package. +* `CARGO_PKG_DESCRIPTION` --- The description from the manifest of your package. +* `CARGO_PKG_HOMEPAGE` --- The home page from the manifest of your package. +* `CARGO_PKG_REPOSITORY` --- The repository from the manifest of your package. +* `CARGO_PKG_LICENSE` --- The license from the manifest of your package. +* `CARGO_PKG_LICENSE_FILE` --- The license file from the manifest of your package. +* `CARGO_PKG_RUST_VERSION` --- The Rust version from the manifest of your package. + Note that this is the minimum Rust version supported by the package, not the + current Rust version. +* `CARGO_CRATE_NAME` --- The name of the crate that is currently being compiled. It is the name of the [Cargo target] with `-` converted to `_`, such as the name of the library, binary, example, integration test, or benchmark. +* `CARGO_BIN_NAME` --- The name of the binary that is currently being compiled. + Only set for [binaries] or binary [examples]. This name does not include any + file extension, such as `.exe`. +* `OUT_DIR` --- If the package has a build script, this is set to the folder where the build + script should place its output. See below for more information. + (Only set during compilation.) +* `CARGO_BIN_EXE_<name>` --- The absolute path to a binary target's executable. + This is only set when building an [integration test] or benchmark. This may + be used with the [`env` macro] to find the executable to run for testing + purposes. The `<name>` is the name of the binary target, exactly as-is. For + example, `CARGO_BIN_EXE_my-program` for a binary named `my-program`. + Binaries are automatically built when the test is built, unless the binary + has required features that are not enabled. +* `CARGO_PRIMARY_PACKAGE` --- This environment variable will be set if the + package being built is primary. Primary packages are the ones the user + selected on the command-line, either with `-p` flags or the defaults based + on the current directory and the default workspace members. This environment + variable will not be set when building dependencies. This is only set when + compiling the package (not when running binaries or tests). +* `CARGO_TARGET_TMPDIR` --- Only set when building [integration test] or benchmark code. + This is a path to a directory inside the target directory + where integration tests or benchmarks are free to put any data needed by + the tests/benches. Cargo initially creates this directory but doesn't + manage its content in any way, this is the responsibility of the test code. + +[Cargo target]: cargo-targets.md +[binaries]: cargo-targets.md#binaries +[examples]: cargo-targets.md#examples +[integration test]: cargo-targets.md#integration-tests +[`env` macro]: ../../std/macro.env.html + +#### Dynamic library paths + +Cargo also sets the dynamic library path when compiling and running binaries +with commands like `cargo run` and `cargo test`. This helps with locating +shared libraries that are part of the build process. The variable name depends +on the platform: + +* Windows: `PATH` +* macOS: `DYLD_FALLBACK_LIBRARY_PATH` +* Unix: `LD_LIBRARY_PATH` + +The value is extended from the existing value when Cargo starts. macOS has +special consideration where if `DYLD_FALLBACK_LIBRARY_PATH` is not already +set, it will add the default `$HOME/lib:/usr/local/lib:/usr/lib`. + +Cargo includes the following paths: + +* Search paths included from any build script with the [`rustc-link-search` + instruction](build-scripts.md#rustc-link-search). Paths outside of the + `target` directory are removed. It is the responsibility of the user running + Cargo to properly set the environment if additional libraries on the system + are needed in the search path. +* The base output directory, such as `target/debug`, and the "deps" directory. + This is mostly for legacy support of `rustc` compiler plugins. +* The rustc sysroot library path. This generally is not important to most + users. + +### Environment variables Cargo sets for build scripts + +Cargo sets several environment variables when build scripts are run. Because these variables +are not yet set when the build script is compiled, the above example using `env!` won't work +and instead you'll need to retrieve the values when the build script is run: + +```rust,ignore +use std::env; +let out_dir = env::var("OUT_DIR").unwrap(); +``` + +`out_dir` will now contain the value of `OUT_DIR`. + +* `CARGO` --- Path to the `cargo` binary performing the build. +* `CARGO_MANIFEST_DIR` --- The directory containing the manifest for the package + being built (the package containing the build + script). Also note that this is the value of the + current working directory of the build script when it + starts. +* `CARGO_MANIFEST_LINKS` --- the manifest `links` value. +* `CARGO_MAKEFLAGS` --- Contains parameters needed for Cargo's [jobserver] + implementation to parallelize subprocesses. + Rustc or cargo invocations from build.rs can already + read `CARGO_MAKEFLAGS`, but GNU Make requires the + flags to be specified either directly as arguments, + or through the `MAKEFLAGS` environment variable. + Currently Cargo doesn't set the `MAKEFLAGS` variable, + but it's free for build scripts invoking GNU Make + to set it to the contents of `CARGO_MAKEFLAGS`. +* `CARGO_FEATURE_<name>` --- For each activated feature of the package being + built, this environment variable will be present + where `<name>` is the name of the feature uppercased + and having `-` translated to `_`. +* `CARGO_CFG_<cfg>` --- For each [configuration option][configuration] of the + package being built, this environment variable will contain the value of the + configuration, where `<cfg>` is the name of the configuration uppercased and + having `-` translated to `_`. Boolean configurations are present if they are + set, and not present otherwise. Configurations with multiple values are + joined to a single variable with the values delimited by `,`. This includes + values built-in to the compiler (which can be seen with `rustc --print=cfg`) + and values set by build scripts and extra flags passed to `rustc` (such as + those defined in `RUSTFLAGS`). Some examples of what these variables are: + * `CARGO_CFG_UNIX` --- Set on [unix-like platforms]. + * `CARGO_CFG_WINDOWS` --- Set on [windows-like platforms]. + * `CARGO_CFG_TARGET_FAMILY=unix` --- The [target family]. + * `CARGO_CFG_TARGET_OS=macos` --- The [target operating system]. + * `CARGO_CFG_TARGET_ARCH=x86_64` --- The CPU [target architecture]. + * `CARGO_CFG_TARGET_VENDOR=apple` --- The [target vendor]. + * `CARGO_CFG_TARGET_ENV=gnu` --- The [target environment] ABI. + * `CARGO_CFG_TARGET_POINTER_WIDTH=64` --- The CPU [pointer width]. + * `CARGO_CFG_TARGET_ENDIAN=little` --- The CPU [target endianness]. + * `CARGO_CFG_TARGET_FEATURE=mmx,sse` --- List of CPU [target features] enabled. +* `OUT_DIR` --- the folder in which all output and intermediate artifacts should + be placed. This folder is inside the build directory for the + package being built, and it is unique for the package in question. +* `TARGET` --- the target triple that is being compiled for. Native code should be + compiled for this triple. See the [Target Triple] description + for more information. +* `HOST` --- the host triple of the Rust compiler. +* `NUM_JOBS` --- the parallelism specified as the top-level parallelism. This can + be useful to pass a `-j` parameter to a system like `make`. Note + that care should be taken when interpreting this environment + variable. For historical purposes this is still provided but + recent versions of Cargo, for example, do not need to run `make + -j`, and instead can set the `MAKEFLAGS` env var to the content + of `CARGO_MAKEFLAGS` to activate the use of Cargo's GNU Make + compatible [jobserver] for sub-make invocations. +* `OPT_LEVEL`, `DEBUG` --- values of the corresponding variables for the + profile currently being built. +* `PROFILE` --- `release` for release builds, `debug` for other builds. This is + determined based on if the [profile] inherits from the [`dev`] or + [`release`] profile. Using this environment variable is not recommended. + Using other environment variables like `OPT_LEVEL` provide a more correct + view of the actual settings being used. +* `DEP_<name>_<key>` --- For more information about this set of environment + variables, see build script documentation about [`links`][links]. +* `RUSTC`, `RUSTDOC` --- the compiler and documentation generator that Cargo has + resolved to use, passed to the build script so it might + use it as well. +* `RUSTC_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is using. + See [`build.rustc-wrapper`]. +* `RUSTC_WORKSPACE_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is + using for workspace members. See + [`build.rustc-workspace-wrapper`]. +* `RUSTC_LINKER` --- The path to the linker binary that Cargo has resolved to use + for the current target, if specified. The linker can be + changed by editing `.cargo/config.toml`; see the documentation + about [cargo configuration][cargo-config] for more + information. +* `CARGO_ENCODED_RUSTFLAGS` --- extra flags that Cargo invokes `rustc` with, + separated by a `0x1f` character (ASCII Unit Separator). See + [`build.rustflags`]. Note that since Rust 1.55, `RUSTFLAGS` is removed from + the environment; scripts should use `CARGO_ENCODED_RUSTFLAGS` instead. +* `CARGO_PKG_<var>` --- The package information variables, with the same names and values as are [provided during crate building][variables set for crates]. + +[`env_logger`]: https://docs.rs/env_logger +[debug logging]: https://doc.crates.io/contrib/architecture/console.html#debug-logging +[unix-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows +[windows-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows +[target family]: ../../reference/conditional-compilation.html#target_family +[target operating system]: ../../reference/conditional-compilation.html#target_os +[target architecture]: ../../reference/conditional-compilation.html#target_arch +[target vendor]: ../../reference/conditional-compilation.html#target_vendor +[target environment]: ../../reference/conditional-compilation.html#target_env +[pointer width]: ../../reference/conditional-compilation.html#target_pointer_width +[target endianness]: ../../reference/conditional-compilation.html#target_endian +[target features]: ../../reference/conditional-compilation.html#target_feature +[links]: build-scripts.md#the-links-manifest-key +[configuration]: ../../reference/conditional-compilation.html +[jobserver]: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html +[cargo-config]: config.md +[Target Triple]: ../appendix/glossary.md#target +[variables set for crates]: #environment-variables-cargo-sets-for-crates +[profile]: profiles.md +[`dev`]: profiles.md#dev +[`release`]: profiles.md#release + +### Environment variables Cargo sets for 3rd party subcommands + +Cargo exposes this environment variable to 3rd party subcommands +(ie. programs named `cargo-foobar` placed in `$PATH`): + +* `CARGO` --- Path to the `cargo` binary performing the build. + +For extended information about your environment you may run `cargo metadata`. diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md new file mode 100644 index 0000000..58f4787 --- /dev/null +++ b/src/doc/src/reference/external-tools.md @@ -0,0 +1,284 @@ +## External tools + +One of the goals of Cargo is simple integration with third-party tools, like +IDEs and other build systems. To make integration easier, Cargo has several +facilities: + +* a [`cargo metadata`] command, which outputs package structure and dependencies + information in JSON, + +* a `--message-format` flag, which outputs information about a particular build, + and + +* support for custom subcommands. + + +### Information about package structure + +You can use [`cargo metadata`] command to get information about package +structure and dependencies. See the [`cargo metadata`] documentation +for details on the format of the output. + +The format is stable and versioned. When calling `cargo metadata`, you should +pass `--format-version` flag explicitly to avoid forward incompatibility +hazard. + +If you are using Rust, the [cargo_metadata] crate can be used to parse the +output. + +[cargo_metadata]: https://crates.io/crates/cargo_metadata +[`cargo metadata`]: ../commands/cargo-metadata.md + +### JSON messages + +When passing `--message-format=json`, Cargo will output the following +information during the build: + +* compiler errors and warnings, + +* produced artifacts, + +* results of the build scripts (for example, native dependencies). + +The output goes to stdout in the JSON object per line format. The `reason` field +distinguishes different kinds of messages. + +The `--message-format` option can also take additional formatting values which +alter the way the JSON messages are computed and rendered. See the description +of the `--message-format` option in the [build command documentation] for more +details. + +If you are using Rust, the [cargo_metadata] crate can be used to parse these +messages. + +[build command documentation]: ../commands/cargo-build.md +[cargo_metadata]: https://crates.io/crates/cargo_metadata + +#### Compiler messages + +The "compiler-message" message includes output from the compiler, such as +warnings and errors. See the [rustc JSON chapter](../../rustc/json.md) for +details on `rustc`'s message format, which is embedded in the following +structure: + +```javascript +{ + /* The "reason" indicates the kind of message. */ + "reason": "compiler-message", + /* The Package ID, a unique identifier for referring to the package. */ + "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* Absolute path to the package manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* The Cargo target (lib, bin, example, etc.) that generated the message. */ + "target": { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "lib" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "lib" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/lib.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": true + }, + /* The message emitted by the compiler. + + See https://doc.rust-lang.org/rustc/json.html for details. + */ + "message": { + /* ... */ + } +} +``` + +#### Artifact messages + +For every compilation step, a "compiler-artifact" message is emitted with the +following structure: + +```javascript +{ + /* The "reason" indicates the kind of message. */ + "reason": "compiler-artifact", + /* The Package ID, a unique identifier for referring to the package. */ + "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* Absolute path to the package manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* The Cargo target (lib, bin, example, etc.) that generated the artifacts. + See the definition above for `compiler-message` for details. + */ + "target": { + "kind": [ + "lib" + ], + "crate_types": [ + "lib" + ], + "name": "my-package", + "src_path": "/path/to/my-package/src/lib.rs", + "edition": "2018", + "doctest": true, + "test": true + }, + /* The profile indicates which compiler settings were used. */ + "profile": { + /* The optimization level. */ + "opt_level": "0", + /* The debug level, an integer of 0, 1, or 2. If `null`, it implies + rustc's default of 0. + */ + "debuginfo": 2, + /* Whether or not debug assertions are enabled. */ + "debug_assertions": true, + /* Whether or not overflow checks are enabled. */ + "overflow_checks": true, + /* Whether or not the `--test` flag is used. */ + "test": false + }, + /* Array of features enabled. */ + "features": ["feat1", "feat2"], + /* Array of files generated by this step. */ + "filenames": [ + "/path/to/my-package/target/debug/libmy_package.rlib", + "/path/to/my-package/target/debug/deps/libmy_package-be9f3faac0a26ef0.rmeta" + ], + /* A string of the path to the executable that was created, or null if + this step did not generate an executable. + */ + "executable": null, + /* Whether or not this step was actually executed. + When `true`, this means that the pre-existing artifacts were + up-to-date, and `rustc` was not executed. When `false`, this means that + `rustc` was run to generate the artifacts. + */ + "fresh": true +} + +``` + +#### Build script output + +The "build-script-executed" message includes the parsed output of a build +script. Note that this is emitted even if the build script is not run; it will +display the previously cached value. More details about build script output +may be found in [the chapter on build scripts](build-scripts.md). + +```javascript +{ + /* The "reason" indicates the kind of message. */ + "reason": "build-script-executed", + /* The Package ID, a unique identifier for referring to the package. */ + "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* Array of libraries to link, as indicated by the `cargo:rustc-link-lib` + instruction. Note that this may include a "KIND=" prefix in the string + where KIND is the library kind. + */ + "linked_libs": ["foo", "static=bar"], + /* Array of paths to include in the library search path, as indicated by + the `cargo:rustc-link-search` instruction. Note that this may include a + "KIND=" prefix in the string where KIND is the library kind. + */ + "linked_paths": ["/some/path", "native=/another/path"], + /* Array of cfg values to enable, as indicated by the `cargo:rustc-cfg` + instruction. + */ + "cfgs": ["cfg1", "cfg2=\"string\""], + /* Array of [KEY, VALUE] arrays of environment variables to set, as + indicated by the `cargo:rustc-env` instruction. + */ + "env": [ + ["SOME_KEY", "some value"], + ["ANOTHER_KEY", "another value"] + ], + /* An absolute path which is used as a value of `OUT_DIR` environmental + variable when compiling current package. + */ + "out_dir": "/some/path/in/target/dir" +} +``` + +#### Build finished + +The "build-finished" message is emitted at the end of the build. + +```javascript +{ + /* The "reason" indicates the kind of message. */ + "reason": "build-finished", + /* Whether or not the build finished successfully. */ + "success": true, +} +```` + +This message can be helpful for tools to know when to stop reading JSON +messages. Commands such as `cargo test` or `cargo run` can produce additional +output after the build has finished. This message lets a tool know that Cargo +will not produce additional JSON messages, but there may be additional output +that may be generated afterwards (such as the output generated by the program +executed by `cargo run`). + +> Note: There is experimental nightly-only support for JSON output for tests, +> so additional test-specific JSON messages may begin arriving after the +> "build-finished" message if that is enabled. + +### Custom subcommands + +Cargo is designed to be extensible with new subcommands without having to modify +Cargo itself. This is achieved by translating a cargo invocation of the form +cargo `(?<command>[^ ]+)` into an invocation of an external tool +`cargo-${command}`. The external tool must be present in one of the user's +`$PATH` directories. + +When Cargo invokes a custom subcommand, the first argument to the subcommand +will be the filename of the custom subcommand, as usual. The second argument +will be the subcommand name itself. For example, the second argument would be +`${command}` when invoking `cargo-${command}`. Any additional arguments on the +command line will be forwarded unchanged. + +Cargo can also display the help output of a custom subcommand with `cargo help +${command}`. Cargo assumes that the subcommand will print a help message if its +third argument is `--help`. So, `cargo help ${command}` would invoke +`cargo-${command} ${command} --help`. + +Custom subcommands may use the `CARGO` environment variable to call back to +Cargo. Alternatively, it can link to `cargo` crate as a library, but this +approach has drawbacks: + +* Cargo as a library is unstable: the API may change without deprecation +* versions of the linked Cargo library may be different from the Cargo binary + +Instead, it is encouraged to use the CLI interface to drive Cargo. The [`cargo +metadata`] command can be used to obtain information about the current project +(the [`cargo_metadata`] crate provides a Rust interface to this command). + +[`cargo metadata`]: ../commands/cargo-metadata.md +[`cargo_metadata`]: https://crates.io/crates/cargo_metadata diff --git a/src/doc/src/reference/features-examples.md b/src/doc/src/reference/features-examples.md new file mode 100644 index 0000000..ac9636f --- /dev/null +++ b/src/doc/src/reference/features-examples.md @@ -0,0 +1,187 @@ +## Features Examples + +The following illustrates some real-world examples of features in action. + +### Minimizing build times and file sizes + +Some packages use features so that if the features are not enabled, it reduces +the size of the crate and reduces compile time. Some examples are: + +* [`syn`] is a popular crate for parsing Rust code. Since it is so popular, it + is helpful to reduce compile times since it affects so many projects. It has + a [clearly documented list][syn-features] of features which can be used to + minimize the amount of code it contains. +* [`regex`] has a [several features][regex-features] that are [well + documented][regex-docs]. Cutting out Unicode support can reduce the + resulting file size as it can remove some large tables. +* [`winapi`] has [a large number][winapi-features] of features that + limit which Windows API bindings it supports. +* [`web-sys`] is another example similar to `winapi` that provides a [huge + surface area][web-sys-features] of API bindings that are limited by using + features. + +[`winapi`]: https://crates.io/crates/winapi +[winapi-features]: https://github.com/retep998/winapi-rs/blob/0.3.9/Cargo.toml#L25-L431 +[`regex`]: https://crates.io/crates/regex +[`syn`]: https://crates.io/crates/syn +[syn-features]: https://docs.rs/syn/1.0.54/syn/#optional-features +[regex-features]: https://github.com/rust-lang/regex/blob/1.4.2/Cargo.toml#L33-L101 +[regex-docs]: https://docs.rs/regex/1.4.2/regex/#crate-features +[`web-sys`]: https://crates.io/crates/web-sys +[web-sys-features]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/crates/web-sys/Cargo.toml#L32-L1395 + +### Extending behavior + +The [`serde_json`] package has a [`preserve_order` feature][serde_json-preserve_order] +which [changes the behavior][serde_json-code] of JSON maps to preserve the +order that keys are inserted. Notice that it enables an optional dependency +[`indexmap`] to implement the new behavior. + +When changing behavior like this, be careful to make sure the changes are +[SemVer compatible]. That is, enabling the feature should not break code that +usually builds with the feature off. + +[`serde_json`]: https://crates.io/crates/serde_json +[serde_json-preserve_order]: https://github.com/serde-rs/json/blob/v1.0.60/Cargo.toml#L53-L56 +[SemVer compatible]: features.md#semver-compatibility +[serde_json-code]: https://github.com/serde-rs/json/blob/v1.0.60/src/map.rs#L23-L26 +[`indexmap`]: https://crates.io/crates/indexmap + +### `no_std` support + +Some packages want to support both [`no_std`] and `std` environments. This is +useful for supporting embedded and resource-constrained platforms, but still +allowing extended capabilities for platforms that support the full standard +library. + +The [`wasm-bindgen`] package defines a [`std` feature][wasm-bindgen-std] that +is [enabled by default][wasm-bindgen-default]. At the top of the library, it +[unconditionally enables the `no_std` attribute][wasm-bindgen-no_std]. This +ensures that `std` and the [`std` prelude] are not automatically in scope. +Then, in various places in the code ([example1][wasm-bindgen-cfg1], +[example2][wasm-bindgen-cfg2]), it uses `#[cfg(feature = "std")]` attributes +to conditionally enable extra functionality that requires `std`. + +[`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute +[`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen +[`std` prelude]: ../../std/prelude/index.html +[wasm-bindgen-std]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/Cargo.toml#L25 +[wasm-bindgen-default]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/Cargo.toml#L23 +[wasm-bindgen-no_std]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L8 +[wasm-bindgen-cfg1]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L270-L273 +[wasm-bindgen-cfg2]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L67-L75 + +### Re-exporting dependency features + +It can be convenient to re-export the features from a dependency. This allows +the user depending on the crate to control those features without needing to +specify those dependencies directly. For example, [`regex`] [re-exports the +features][regex-re-export] from the [`regex_syntax`][regex_syntax-features] +package. Users of `regex` don't need to know about the `regex_syntax` package, +but they can still access the features it contains. + +[regex-re-export]: https://github.com/rust-lang/regex/blob/1.4.2/Cargo.toml#L65-L89 +[regex_syntax-features]: https://github.com/rust-lang/regex/blob/1.4.2/regex-syntax/Cargo.toml#L17-L32 + +### Vendoring of C libraries + +Some packages provide bindings to common C libraries (sometimes referred to as +["sys" crates][sys]). Sometimes these packages give you the choice to use the +C library installed on the system, or to build it from source. For example, +the [`openssl`] package has a [`vendored` feature][openssl-vendored] which +enables the corresponding `vendored` feature of [`openssl-sys`]. The +`openssl-sys` build script has some [conditional logic][openssl-sys-cfg] which +causes it to build from a local copy of the OpenSSL source code instead of +using the version from the system. + +The [`curl-sys`] package is another example where the [`static-curl` +feature][curl-sys-static] causes it to build libcurl from source. Notice that +it also has a [`force-system-lib-on-osx`][curl-sys-macos] feature which forces +it [to use the system libcurl][curl-sys-macos-code], overriding the +static-curl setting. + +[`openssl`]: https://crates.io/crates/openssl +[`openssl-sys`]: https://crates.io/crates/openssl-sys +[sys]: build-scripts.md#-sys-packages +[openssl-vendored]: https://github.com/sfackler/rust-openssl/blob/openssl-v0.10.31/openssl/Cargo.toml#L19 +[build script]: build-scripts.md +[openssl-sys-cfg]: https://github.com/sfackler/rust-openssl/blob/openssl-v0.10.31/openssl-sys/build/main.rs#L47-L54 +[`curl-sys`]: https://crates.io/crates/curl-sys +[curl-sys-static]: https://github.com/alexcrichton/curl-rust/blob/0.4.34/curl-sys/Cargo.toml#L49 +[curl-sys-macos]: https://github.com/alexcrichton/curl-rust/blob/0.4.34/curl-sys/Cargo.toml#L52 +[curl-sys-macos-code]: https://github.com/alexcrichton/curl-rust/blob/0.4.34/curl-sys/build.rs#L15-L20 + +### Feature precedence + +Some packages may have mutually-exclusive features. One option to handle this +is to prefer one feature over another. The [`log`] package is an example. It +has [several features][log-features] for choosing the maximum logging level at +compile-time described [here][log-docs]. It uses [`cfg-if`] to [choose a +precedence][log-cfg-if]. If multiple features are enabled, the higher "max" +levels will be preferred over the lower levels. + +[`log`]: https://crates.io/crates/log +[log-features]: https://github.com/rust-lang/log/blob/0.4.11/Cargo.toml#L29-L42 +[log-docs]: https://docs.rs/log/0.4.11/log/#compile-time-filters +[log-cfg-if]: https://github.com/rust-lang/log/blob/0.4.11/src/lib.rs#L1422-L1448 +[`cfg-if`]: https://crates.io/crates/cfg-if + +### Proc-macro companion package + +Some packages have a proc-macro that is intimately tied with it. However, not +all users will need to use the proc-macro. By making the proc-macro an +optional-dependency, this allows you to conveniently choose whether or not it +is included. This is helpful, because sometimes the proc-macro version must +stay in sync with the parent package, and you don't want to force the users to +have to specify both dependencies and keep them in sync. + +An example is [`serde`] which has a [`derive`][serde-derive] feature which +enables the [`serde_derive`] proc-macro. The `serde_derive` crate is very +tightly tied to `serde`, so it uses an [equals version +requirement][serde-equals] to ensure they stay in sync. + +[`serde`]: https://crates.io/crates/serde +[`serde_derive`]: https://crates.io/crates/serde_derive +[serde-derive]: https://github.com/serde-rs/serde/blob/v1.0.118/serde/Cargo.toml#L34-L35 +[serde-equals]: https://github.com/serde-rs/serde/blob/v1.0.118/serde/Cargo.toml#L17 + +### Nightly-only features + +Some packages want to experiment with APIs or language features that are only +available on the Rust [nightly channel]. However, they may not want to require +their users to also use the nightly channel. An example is [`wasm-bindgen`] +which has a [`nightly` feature][wasm-bindgen-nightly] which enables an +[extended API][wasm-bindgen-unsize] that uses the [`Unsize`] marker trait that +is only available on the nightly channel at the time of this writing. + +Note that at the root of the crate it uses [`cfg_attr` to enable the nightly +feature][wasm-bindgen-cfg_attr]. Keep in mind that the [`feature` attribute] +is unrelated to Cargo features, and is used to opt-in to experimental language +features. + +The [`simd_support` feature][rand-simd_support] of the [`rand`] package is another example, +which relies on a dependency that only builds on the nightly channel. + +[`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen +[nightly channel]: ../../book/appendix-07-nightly-rust.html +[wasm-bindgen-nightly]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/Cargo.toml#L27 +[wasm-bindgen-unsize]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/closure.rs#L257-L269 +[`Unsize`]: ../../std/marker/trait.Unsize.html +[wasm-bindgen-cfg_attr]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L11 +[`feature` attribute]: ../../unstable-book/index.html +[`rand`]: https://crates.io/crates/rand +[rand-simd_support]: https://github.com/rust-random/rand/blob/0.7.3/Cargo.toml#L40 + +### Experimental features + +Some packages have new functionality that they may want to experiment with, +without having to commit to the stability of those APIs. The features are +usually documented that they are experimental, and thus may change or break in +the future, even during a minor release. An example is the [`async-std`] +package, which has an [`unstable` feature][async-std-unstable], which [gates +new APIs][async-std-gate] that people can opt-in to using, but may not be +completely ready to be relied upon. + +[`async-std`]: https://crates.io/crates/async-std +[async-std-unstable]: https://github.com/async-rs/async-std/blob/v1.8.0/Cargo.toml#L38-L42 +[async-std-gate]: https://github.com/async-rs/async-std/blob/v1.8.0/src/macros.rs#L46 diff --git a/src/doc/src/reference/features.md b/src/doc/src/reference/features.md new file mode 100644 index 0000000..40eb32c --- /dev/null +++ b/src/doc/src/reference/features.md @@ -0,0 +1,521 @@ +## Features + +Cargo "features" provide a mechanism to express [conditional compilation] and +[optional dependencies](#optional-dependencies). A package defines a set of +named features in the `[features]` table of `Cargo.toml`, and each feature can +either be enabled or disabled. Features for the package being built can be +enabled on the command-line with flags such as `--features`. Features for +dependencies can be enabled in the dependency declaration in `Cargo.toml`. + +See also the [Features Examples] chapter for some examples of how features can +be used. + +[conditional compilation]: ../../reference/conditional-compilation.md +[Features Examples]: features-examples.md + +### The `[features]` section + +Features are defined in the `[features]` table in `Cargo.toml`. Each feature +specifies an array of other features or optional dependencies that it enables. +The following examples illustrate how features could be used for a 2D image +processing library where support for different image formats can be optionally +included: + +```toml +[features] +# Defines a feature named `webp` that does not enable any other features. +webp = [] +``` + +With this feature defined, [`cfg` expressions] can be used to conditionally +include code to support the requested feature at compile time. For example, +inside `lib.rs` of the package could include this: + +```rust +// This conditionally includes a module which implements WEBP support. +#[cfg(feature = "webp")] +pub mod webp; +``` + +Cargo sets features in the package using the `rustc` [`--cfg` flag], and code +can test for their presence with the [`cfg` attribute] or the [`cfg` macro]. + +Features can list other features to enable. For example, the ICO image format +can contain BMP and PNG images, so when it is enabled, it should make sure +those other features are enabled, too: + +```toml +[features] +bmp = [] +png = [] +ico = ["bmp", "png"] +webp = [] +``` + +Feature names may include characters from the [Unicode XID standard] (which +includes most letters), and additionally allows starting with `_` or digits +`0` through `9`, and after the first character may also contain `-`, `+`, or +`.`. + +> **Note**: [crates.io] imposes additional constraints on feature name syntax +> that they must only be [ASCII alphanumeric] characters or `_`, `-`, or `+`. + +[crates.io]: https://crates.io/ +[Unicode XID standard]: https://unicode.org/reports/tr31/ +[ASCII alphanumeric]: ../../std/primitive.char.html#method.is_ascii_alphanumeric +[`--cfg` flag]: ../../rustc/command-line-arguments.md#option-cfg +[`cfg` expressions]: ../../reference/conditional-compilation.md +[`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute +[`cfg` macro]: ../../std/macro.cfg.html + +### The `default` feature + +By default, all features are disabled unless explicitly enabled. This can be +changed by specifying the `default` feature: + +```toml +[features] +default = ["ico", "webp"] +bmp = [] +png = [] +ico = ["bmp", "png"] +webp = [] +``` + +When the package is built, the `default` feature is enabled which in turn +enables the listed features. This behavior can be changed by: + +* The `--no-default-features` [command-line + flag](#command-line-feature-options) disables the default features of the + package. +* The `default-features = false` option can be specified in a [dependency + declaration](#dependency-features). + +> **Note**: Be careful about choosing the default feature set. The default +> features are a convenience that make it easier to use a package without +> forcing the user to carefully select which features to enable for common +> use, but there are some drawbacks. Dependencies automatically enable default +> features unless `default-features = false` is specified. This can make it +> difficult to ensure that the default features are not enabled, especially +> for a dependency that appears multiple times in the dependency graph. Every +> package must ensure that `default-features = false` is specified to avoid +> enabling them. +> +> Another issue is that it can be a [SemVer incompatible +> change](#semver-compatibility) to remove a feature from the default set, so +> you should be confident that you will keep those features. + +### Optional dependencies + +Dependencies can be marked "optional", which means they will not be compiled +by default. For example, let's say that our 2D image processing library uses +an external package to handle GIF images. This can be expressed like this: + +```toml +[dependencies] +gif = { version = "0.11.1", optional = true } +``` + +By default, this optional dependency implicitly defines a feature that looks +like this: + +```toml +[features] +gif = ["dep:gif"] +``` + +This means that this dependency will only be included if the `gif` +feature is enabled. +The same `cfg(feature = "gif")` syntax can be used in the code, and the +dependency can be enabled just like any feature such as `--features gif` (see +[Command-line feature options](#command-line-feature-options) below). + +In some cases, you may not want to expose a feature that has the same name +as the optional dependency. +For example, perhaps the optional dependency is an internal detail, or you +want to group multiple optional dependencies together, or you just want to use +a better name. +If you specify the optional dependency with the `dep:` prefix anywhere +in the `[features]` table, that disables the implicit feature. + +> **Note**: The `dep:` syntax is only available starting with Rust 1.60. +> Previous versions can only use the implicit feature name. + +For example, let's say in order to support the AVIF image format, our library +needs two other dependencies to be enabled: + +```toml +[dependencies] +ravif = { version = "0.6.3", optional = true } +rgb = { version = "0.8.25", optional = true } + +[features] +avif = ["dep:ravif", "dep:rgb"] +``` + +In this example, the `avif` feature will enable the two listed dependencies. +This also avoids creating the implicit `ravif` and `rgb` features, since we +don't want users to enable those individually as they are internal details to +our crate. + +> **Note**: Another way to optionally include a dependency is to use +> [platform-specific dependencies]. Instead of using features, these are +> conditional based on the target platform. + +[platform-specific dependencies]: specifying-dependencies.md#platform-specific-dependencies + +### Dependency features + +Features of dependencies can be enabled within the dependency declaration. The +`features` key indicates which features to enable: + +```toml +[dependencies] +# Enables the `derive` feature of serde. +serde = { version = "1.0.118", features = ["derive"] } +``` + +The [`default` features](#the-default-feature) can be disabled using +`default-features = false`: + +```toml +[dependencies] +flate2 = { version = "1.0.3", default-features = false, features = ["zlib"] } +``` + +> **Note**: This may not ensure the default features are disabled. If another +> dependency includes `flate2` without specifying `default-features = false`, +> then the default features will be enabled. See [feature +> unification](#feature-unification) below for more details. + +Features of dependencies can also be enabled in the `[features]` table. The +syntax is `"package-name/feature-name"`. For example: + +```toml +[dependencies] +jpeg-decoder = { version = "0.1.20", default-features = false } + +[features] +# Enables parallel processing support by enabling the "rayon" feature of jpeg-decoder. +parallel = ["jpeg-decoder/rayon"] +``` + +The `"package-name/feature-name"` syntax will also enable `package-name` +if it is an optional dependency. Often this is not what you want. +You can add a `?` as in `"package-name?/feature-name"` which will only enable +the given feature if something else enables the optional dependency. + +> **Note**: The `?` syntax is only available starting with Rust 1.60. + +For example, let's say we have added some serialization support to our +library, and it requires enabling a corresponding feature in some optional +dependencies. +That can be done like this: + +```toml +[dependencies] +serde = { version = "1.0.133", optional = true } +rgb = { version = "0.8.25", optional = true } + +[features] +serde = ["dep:serde", "rgb?/serde"] +``` + +In this example, enabling the `serde` feature will enable the serde +dependency. +It will also enable the `serde` feature for the `rgb` dependency, but only if +something else has enabled the `rgb` dependency. + +### Command-line feature options + +The following command-line flags can be used to control which features are +enabled: + +* `--features` _FEATURES_: Enables the listed features. Multiple features may + be separated with commas or spaces. If using spaces, be sure to use quotes + around all the features if running Cargo from a shell (such as `--features + "foo bar"`). If building multiple packages in a [workspace], the + `package-name/feature-name` syntax can be used to specify features for + specific workspace members. + +* `--all-features`: Activates all features of all packages selected on the + command-line. + +* `--no-default-features`: Does not activate the [`default` + feature](#the-default-feature) of the selected packages. + +[workspace]: workspaces.md + +### Feature unification + +Features are unique to the package that defines them. Enabling a feature on a +package does not enable a feature of the same name on other packages. + +When a dependency is used by multiple packages, Cargo will use the union of +all features enabled on that dependency when building it. This helps ensure +that only a single copy of the dependency is used. See the [features section] +of the resolver documentation for more details. + +For example, let's look at the [`winapi`] package which uses a [large +number][winapi-features] of features. If your package depends on a package +`foo` which enables the "fileapi" and "handleapi" features of `winapi`, and +another dependency `bar` which enables the "std" and "winnt" features of +`winapi`, then `winapi` will be built with all four of those features enabled. + + + +[`winapi`]: https://crates.io/crates/winapi +[winapi-features]: https://github.com/retep998/winapi-rs/blob/0.3.9/Cargo.toml#L25-L431 + +A consequence of this is that features should be *additive*. That is, enabling +a feature should not disable functionality, and it should usually be safe to +enable any combination of features. A feature should not introduce a +[SemVer-incompatible change](#semver-compatibility). + +For example, if you want to optionally support [`no_std`] environments, **do +not** use a `no_std` feature. Instead, use a `std` feature that *enables* +`std`. For example: + +```rust +#![no_std] + +#[cfg(feature = "std")] +extern crate std; + +#[cfg(feature = "std")] +pub fn function_that_requires_std() { + // ... +} +``` + +[`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute +[features section]: resolver.md#features + +#### Mutually exclusive features + +There are rare cases where features may be mutually incompatible with one +another. This should be avoided if at all possible, because it requires +coordinating all uses of the package in the dependency graph to cooperate to +avoid enabling them together. If it is not possible, consider adding a compile +error to detect this scenario. For example: + +```rust,ignore +#[cfg(all(feature = "foo", feature = "bar"))] +compile_error!("feature \"foo\" and feature \"bar\" cannot be enabled at the same time"); +``` + +Instead of using mutually exclusive features, consider some other options: + +* Split the functionality into separate packages. +* When there is a conflict, [choose one feature over + another][feature-precedence]. The [`cfg-if`] package can help with writing + more complex `cfg` expressions. +* Architect the code to allow the features to be enabled concurrently, and use + runtime options to control which is used. For example, use a config file, + command-line argument, or environment variable to choose which behavior to + enable. + +[`cfg-if`]: https://crates.io/crates/cfg-if +[feature-precedence]: features-examples.md#feature-precedence + +#### Inspecting resolved features + +In complex dependency graphs, it can sometimes be difficult to understand how +different features get enabled on various packages. The [`cargo tree`] command +offers several options to help inspect and visualize which features are +enabled. Some options to try: + +* `cargo tree -e features`: This will show features in the dependency graph. + Each feature will appear showing which package enabled it. +* `cargo tree -f "{p} {f}"`: This is a more compact view that shows a + comma-separated list of features enabled on each package. +* `cargo tree -e features -i foo`: This will invert the tree, showing how + features flow into the given package "foo". This can be useful because + viewing the entire graph can be quite large and overwhelming. Use this when + you are trying to figure out which features are enabled on a specific + package and why. See the example at the bottom of the [`cargo tree`] page on + how to read this. + +[`cargo tree`]: ../commands/cargo-tree.md + +### Feature resolver version 2 + +A different feature resolver can be specified with the `resolver` field in +`Cargo.toml`, like this: + +```toml +[package] +name = "my-package" +version = "1.0.0" +resolver = "2" +``` + +See the [resolver versions] section for more detail on specifying resolver +versions. + +The version `"2"` resolver avoids unifying features in a few situations where +that unification can be unwanted. The exact situations are described in the +[resolver chapter][resolver-v2], but in short, it avoids unifying in these +situations: + +* Features enabled on [platform-specific dependencies] for targets not + currently being built are ignored. +* [Build-dependencies] and proc-macros do not share features with normal + dependencies. +* [Dev-dependencies] do not activate features unless building a target that + needs them (like tests or examples). + +Avoiding the unification is necessary for some situations. For example, if a +build-dependency enables a `std` feature, and the same dependency is used as a +normal dependency for a `no_std` environment, enabling `std` would break the +build. + +However, one drawback is that this can increase build times because the +dependency is built multiple times (each with different features). When using +the version `"2"` resolver, it is recommended to check for dependencies that +are built multiple times to reduce overall build time. If it is not *required* +to build those duplicated packages with separate features, consider adding +features to the `features` list in the [dependency +declaration](#dependency-features) so that the duplicates end up with the same +features (and thus Cargo will build it only once). You can detect these +duplicate dependencies with the [`cargo tree --duplicates`][`cargo tree`] +command. It will show which packages are built multiple times; look for any +entries listed with the same version. See [Inspecting resolved +features](#inspecting-resolved-features) for more on fetching information on +the resolved features. For build dependencies, this is not necessary if you +are cross-compiling with the `--target` flag because build dependencies are +always built separately from normal dependencies in that scenario. + +#### Resolver version 2 command-line flags + +The `resolver = "2"` setting also changes the behavior of the `--features` and +`--no-default-features` [command-line options](#command-line-feature-options). + +With version `"1"`, you can only enable features for the package in the +current working directory. For example, in a workspace with packages `foo` and +`bar`, and you are in the directory for package `foo`, and ran the command +`cargo build -p bar --features bar-feat`, this would fail because the +`--features` flag only allowed enabling features on `foo`. + +With `resolver = "2"`, the features flags allow enabling features for any of +the packages selected on the command-line with `-p` and `--workspace` flags. +For example: + +```sh +# This command is allowed with resolver = "2", regardless of which directory +# you are in. +cargo build -p foo -p bar --features foo-feat,bar-feat + +# This explicit equivalent works with any resolver version: +cargo build -p foo -p bar --features foo/foo-feat,bar/bar-feat +``` + +Additionally, with `resolver = "1"`, the `--no-default-features` flag only +disables the default feature for the package in the current directory. With +version "2", it will disable the default features for all workspace members. + +[resolver versions]: resolver.md#resolver-versions +[build-dependencies]: specifying-dependencies.md#build-dependencies +[dev-dependencies]: specifying-dependencies.md#development-dependencies +[resolver-v2]: resolver.md#feature-resolver-version-2 + +### Build scripts + +[Build scripts] can detect which features are enabled on the package by +inspecting the `CARGO_FEATURE_<name>` environment variable, where `<name>` is +the feature name converted to uppercase and `-` converted to `_`. + +[build scripts]: build-scripts.md + +### Required features + +The [`required-features` field] can be used to disable specific [Cargo +targets] if a feature is not enabled. See the linked documentation for more +details. + +[`required-features` field]: cargo-targets.md#the-required-features-field +[Cargo targets]: cargo-targets.md + +### SemVer compatibility + +Enabling a feature should not introduce a SemVer-incompatible change. For +example, the feature shouldn't change an existing API in a way that could +break existing uses. More details about what changes are compatible can be +found in the [SemVer Compatibility chapter](semver.md). + +Care should be taken when adding and removing feature definitions and optional +dependencies, as these can sometimes be backwards-incompatible changes. More +details can be found in the [Cargo section](semver.md#cargo) of the SemVer +Compatibility chapter. In short, follow these rules: + +* The following is usually safe to do in a minor release: + * Add a [new feature][cargo-feature-add] or [optional dependency][cargo-dep-add]. + * [Change the features used on a dependency][cargo-change-dep-feature]. +* The following should usually **not** be done in a minor release: + * [Remove a feature][cargo-feature-remove] or [optional dependency][cargo-remove-opt-dep]. + * [Moving existing public code behind a feature][item-remove]. + * [Remove a feature from a feature list][cargo-feature-remove-another]. + +See the links for caveats and examples. + +[cargo-change-dep-feature]: semver.md#cargo-change-dep-feature +[cargo-dep-add]: semver.md#cargo-dep-add +[cargo-feature-add]: semver.md#cargo-feature-add +[item-remove]: semver.md#item-remove +[cargo-feature-remove]: semver.md#cargo-feature-remove +[cargo-remove-opt-dep]: semver.md#cargo-remove-opt-dep +[cargo-feature-remove-another]: semver.md#cargo-feature-remove-another + +### Feature documentation and discovery + +You are encouraged to document which features are available in your package. +This can be done by adding [doc comments] at the top of `lib.rs`. As an +example, see the [regex crate source], which when rendered can be viewed on +[docs.rs][regex-docs-rs]. If you have other documentation, such as a user +guide, consider adding the documentation there (for example, see [serde.rs]). +If you have a binary project, consider documenting the features in the README +or other documentation for the project (for example, see [sccache]). + +Clearly documenting the features can set expectations about features that are +considered "unstable" or otherwise shouldn't be used. For example, if there is +an optional dependency, but you don't want users to explicitly list that +optional dependency as a feature, exclude it from the documented list. + +Documentation published on [docs.rs] can use metadata in `Cargo.toml` to +control which features are enabled when the documentation is built. See +[docs.rs metadata documentation] for more details. + +> **Note**: Rustdoc has experimental support for annotating the documentation +> to indicate which features are required to use certain APIs. See the +> [`doc_cfg`] documentation for more details. An example is the [`syn` +> documentation], where you can see colored boxes which note which features +> are required to use it. + +[docs.rs metadata documentation]: https://docs.rs/about/metadata +[docs.rs]: https://docs.rs/ +[serde.rs]: https://serde.rs/feature-flags.html +[doc comments]: ../../rustdoc/how-to-write-documentation.html +[regex crate source]: https://github.com/rust-lang/regex/blob/1.4.2/src/lib.rs#L488-L583 +[regex-docs-rs]: https://docs.rs/regex/1.4.2/regex/#crate-features +[sccache]: https://github.com/mozilla/sccache/blob/0.2.13/README.md#build-requirements +[`doc_cfg`]: ../../unstable-book/language-features/doc-cfg.html +[`syn` documentation]: https://docs.rs/syn/1.0.54/syn/#modules + +#### Discovering features + +When features are documented in the library API, this can make it easier for +your users to discover which features are available and what they do. If the +feature documentation for a package isn't readily available, you can look at +the `Cargo.toml` file, but sometimes it can be hard to track it down. The +crate page on [crates.io] has a link to the source repository if available. +Tools like [`cargo vendor`] or [cargo-clone-crate] can be used to download the +source and inspect it. + +[`cargo vendor`]: ../commands/cargo-vendor.md +[cargo-clone-crate]: https://crates.io/crates/cargo-clone-crate + +### Feature combinations + +Because features are a form of conditional compilation, they require an exponential number of configurations and test cases to be 100% covered. By default, tests, docs, and other tooling such as [Clippy](https://github.com/rust-lang/rust-clippy) will only run with the default set of features. + +We encourage you to consider your strategy and tooling in regards to different feature combinations --- Every project will have different requirements in conjunction with time, resources, and the cost-benefit of covering specific scenarios. Common configurations may be with / without default features, specific combinations of features, or all combinations of features. diff --git a/src/doc/src/reference/future-incompat-report.md b/src/doc/src/reference/future-incompat-report.md new file mode 100644 index 0000000..b72f117 --- /dev/null +++ b/src/doc/src/reference/future-incompat-report.md @@ -0,0 +1,37 @@ +### Future incompat report + +Cargo checks for future-incompatible warnings in all dependencies. These are warnings for +changes that may become hard errors in the future, causing the dependency to +stop building in a future version of rustc. If any warnings are found, a small +notice is displayed indicating that the warnings were found, and provides +instructions on how to display a full report. + +For example, you may see something like this at the end of a build: + +```text +warning: the following packages contain code that will be rejected by a future + version of Rust: rental v0.5.5 +note: to see what the problems were, use the option `--future-incompat-report`, + or run `cargo report future-incompatibilities --id 1` +``` + +A full report can be displayed with the `cargo report future-incompatibilities +--id ID` command, or by running the build again with +the `--future-incompat-report` flag. The developer should then update their +dependencies to a version where the issue is fixed, or work with the +developers of the dependencies to help resolve the issue. + +## Configuration + +This feature can be configured through a [`[future-incompat-report]`][config] +section in `.cargo/config.toml`. Currently, the supported options are: + +```toml +[future-incompat-report] +frequency = "always" +``` + +The supported values for the frequency are `"always"` and `"never"`, which control +whether or not a message is printed out at the end of `cargo build` / `cargo check`. + +[config]: config.md#future-incompat-report diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md new file mode 100644 index 0000000..b931306 --- /dev/null +++ b/src/doc/src/reference/index.md @@ -0,0 +1,26 @@ +## Cargo Reference + +The reference covers the details of various areas of Cargo. + +* [Specifying Dependencies](specifying-dependencies.md) + * [Overriding Dependencies](overriding-dependencies.md) +* [The Manifest Format](manifest.md) + * [Cargo Targets](cargo-targets.md) +* [Workspaces](workspaces.md) +* [Features](features.md) + * [Features Examples](features-examples.md) +* [Profiles](profiles.md) +* [Configuration](config.md) +* [Environment Variables](environment-variables.md) +* [Build Scripts](build-scripts.md) + * [Build Script Examples](build-script-examples.md) +* [Publishing on crates.io](publishing.md) +* [Package ID Specifications](pkgid-spec.md) +* [Source Replacement](source-replacement.md) +* [External Tools](external-tools.md) +* [Registries](registries.md) +* [Dependency Resolution](resolver.md) +* [SemVer Compatibility](semver.md) +* [Future incompat report](future-incompat-report.md) +* [Reporting build timings](timings.md) +* [Unstable Features](unstable.md) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md new file mode 100644 index 0000000..49d5b96 --- /dev/null +++ b/src/doc/src/reference/manifest.md @@ -0,0 +1,632 @@ +## The Manifest Format + +The `Cargo.toml` file for each package is called its *manifest*. It is written +in the [TOML] format. It contains metadata that is needed to compile the package. Checkout +the `cargo locate-project` section for more detail on how cargo finds the manifest file. + +Every manifest file consists of the following sections: + +* [`cargo-features`](unstable.md) --- Unstable, nightly-only features. +* [`[package]`](#the-package-section) --- Defines a package. + * [`name`](#the-name-field) --- The name of the package. + * [`version`](#the-version-field) --- The version of the package. + * [`authors`](#the-authors-field) --- The authors of the package. + * [`edition`](#the-edition-field) --- The Rust edition. + * [`rust-version`](#the-rust-version-field) --- The minimal supported Rust version. + * [`description`](#the-description-field) --- A description of the package. + * [`documentation`](#the-documentation-field) --- URL of the package documentation. + * [`readme`](#the-readme-field) --- Path to the package's README file. + * [`homepage`](#the-homepage-field) --- URL of the package homepage. + * [`repository`](#the-repository-field) --- URL of the package source repository. + * [`license`](#the-license-and-license-file-fields) --- The package license. + * [`license-file`](#the-license-and-license-file-fields) --- Path to the text of the license. + * [`keywords`](#the-keywords-field) --- Keywords for the package. + * [`categories`](#the-categories-field) --- Categories of the package. + * [`workspace`](#the-workspace-field) --- Path to the workspace for the package. + * [`build`](#the-build-field) --- Path to the package build script. + * [`links`](#the-links-field) --- Name of the native library the package links with. + * [`exclude`](#the-exclude-and-include-fields) --- Files to exclude when publishing. + * [`include`](#the-exclude-and-include-fields) --- Files to include when publishing. + * [`publish`](#the-publish-field) --- Can be used to prevent publishing the package. + * [`metadata`](#the-metadata-table) --- Extra settings for external tools. + * [`default-run`](#the-default-run-field) --- The default binary to run by [`cargo run`]. + * [`autobins`](cargo-targets.md#target-auto-discovery) --- Disables binary auto discovery. + * [`autoexamples`](cargo-targets.md#target-auto-discovery) --- Disables example auto discovery. + * [`autotests`](cargo-targets.md#target-auto-discovery) --- Disables test auto discovery. + * [`autobenches`](cargo-targets.md#target-auto-discovery) --- Disables bench auto discovery. + * [`resolver`](resolver.md#resolver-versions) --- Sets the dependency resolver to use. +* Target tables: (see [configuration](cargo-targets.md#configuring-a-target) for settings) + * [`[lib]`](cargo-targets.md#library) --- Library target settings. + * [`[[bin]]`](cargo-targets.md#binaries) --- Binary target settings. + * [`[[example]]`](cargo-targets.md#examples) --- Example target settings. + * [`[[test]]`](cargo-targets.md#tests) --- Test target settings. + * [`[[bench]]`](cargo-targets.md#benchmarks) --- Benchmark target settings. +* Dependency tables: + * [`[dependencies]`](specifying-dependencies.md) --- Package library dependencies. + * [`[dev-dependencies]`](specifying-dependencies.md#development-dependencies) --- Dependencies for examples, tests, and benchmarks. + * [`[build-dependencies]`](specifying-dependencies.md#build-dependencies) --- Dependencies for build scripts. + * [`[target]`](specifying-dependencies.md#platform-specific-dependencies) --- Platform-specific dependencies. +* [`[badges]`](#the-badges-section) --- Badges to display on a registry. +* [`[features]`](features.md) --- Conditional compilation features. +* [`[patch]`](overriding-dependencies.md#the-patch-section) --- Override dependencies. +* [`[replace]`](overriding-dependencies.md#the-replace-section) --- Override dependencies (deprecated). +* [`[profile]`](profiles.md) --- Compiler settings and optimizations. +* [`[workspace]`](workspaces.md) --- The workspace definition. + +<a id="package-metadata"></a> +### The `[package]` section + +The first section in a `Cargo.toml` is `[package]`. + +```toml +[package] +name = "hello_world" # the name of the package +version = "0.1.0" # the current version, obeying semver +authors = ["Alice <a@example.com>", "Bob <b@example.com>"] +``` + +The only fields required by Cargo are [`name`](#the-name-field) and +[`version`](#the-version-field). If publishing to a registry, the registry may +require additional fields. See the notes below and [the publishing +chapter][publishing] for requirements for publishing to [crates.io]. + +#### The `name` field + +The package name is an identifier used to refer to the package. It is used +when listed as a dependency in another package, and as the default name of +inferred lib and bin targets. + +The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty. + +Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on +the package name, such as enforcing that it is a valid Rust identifier and not +a keyword. [crates.io] imposes even more restrictions, such as: + +- Only ASCII characters are allowed. +- Do not use reserved names. +- Do not use special Windows names such as "nul". +- Use a maximum of 64 characters of length. + +[alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric + +#### The `version` field + +Cargo bakes in the concept of [Semantic +Versioning](https://semver.org/), so make sure you follow some basic rules: + +* Before you reach 1.0.0, anything goes, but if you make breaking changes, + increment the minor version. In Rust, breaking changes include adding fields to + structs or variants to enums. +* After 1.0.0, only make breaking changes when you increment the major version. + Don’t break the build. +* After 1.0.0, don’t add any new public API (no new `pub` anything) in patch-level + versions. Always increment the minor version if you add any new `pub` structs, + traits, fields, types, functions, methods or anything else. +* Use version numbers with three numeric parts such as 1.0.0 rather than 1.0. + +See the [Resolver] chapter for more information on how Cargo uses versions to +resolve dependencies, and for guidelines on setting your own version. See the +[SemVer compatibility] chapter for more details on exactly what constitutes a +breaking change. + +[Resolver]: resolver.md +[SemVer compatibility]: semver.md + +<a id="the-authors-field-optional"></a> +#### The `authors` field + +The optional `authors` field lists in an array the people or organizations that are considered +the "authors" of the package. The exact meaning is open to interpretation --- it +may list the original or primary authors, current maintainers, or owners of the +package. An optional email address may be included within angled brackets at +the end of each author entry. + +```toml +[package] +# ... +authors = ["Graydon Hoare", "Fnu Lnu <no-reply@rust-lang.org>"] +``` + +This field is only surfaced in package metadata and in the `CARGO_PKG_AUTHORS` +environment variable within `build.rs`. It is not displayed in the [crates.io] +user interface. + +> **Warning**: Package manifests cannot be changed once published, so this +> field cannot be changed or removed in already-published versions of a +> package. + +<a id="the-edition-field-optional"></a> +#### The `edition` field + +The `edition` key is an optional key that affects which [Rust Edition] your package +is compiled with. Setting the `edition` key in `[package]` will affect all +targets/crates in the package, including test suites, benchmarks, binaries, +examples, etc. + +```toml +[package] +# ... +edition = '2021' +``` + +Most manifests have the `edition` field filled in automatically by [`cargo new`] +with the latest stable edition. By default `cargo new` creates a manifest with +the 2021 edition currently. + +If the `edition` field is not present in `Cargo.toml`, then the 2015 edition is +assumed for backwards compatibility. Note that all manifests +created with [`cargo new`] will not use this historical fallback because they +will have `edition` explicitly specified to a newer value. + +#### The `rust-version` field + +The `rust-version` field is an optional key that tells cargo what version of the +Rust language and compiler your package can be compiled with. If the currently +selected version of the Rust compiler is older than the stated version, cargo +will exit with an error, telling the user what version is required. + +The first version of Cargo that supports this field was released with Rust 1.56.0. +In older releases, the field will be ignored, and Cargo will display a warning. + +```toml +[package] +# ... +rust-version = "1.56" +``` + +The Rust version must be a bare version number with two or three components; it +cannot include semver operators or pre-release identifiers. Compiler pre-release +identifiers such as -nightly will be ignored while checking the Rust version. +The `rust-version` must be equal to or newer than the version that first +introduced the configured `edition`. + +The `rust-version` may be ignored using the `--ignore-rust-version` option. + +Setting the `rust-version` key in `[package]` will affect all targets/crates in +the package, including test suites, benchmarks, binaries, examples, etc. + +#### The `description` field + +The description is a short blurb about the package. [crates.io] will display +this with your package. This should be plain text (not Markdown). + +```toml +[package] +# ... +description = "A short description of my package" +``` + +> **Note**: [crates.io] requires the `description` to be set. + +<a id="the-documentation-field-optional"></a> +#### The `documentation` field + +The `documentation` field specifies a URL to a website hosting the crate's +documentation. If no URL is specified in the manifest file, [crates.io] will +automatically link your crate to the corresponding [docs.rs] page. + +```toml +[package] +# ... +documentation = "https://docs.rs/bitflags" +``` + +#### The `readme` field + +The `readme` field should be the path to a file in the package root (relative +to this `Cargo.toml`) that contains general information about the package. +This file will be transferred to the registry when you publish. [crates.io] +will interpret it as Markdown and render it on the crate's page. + +```toml +[package] +# ... +readme = "README.md" +``` + +If no value is specified for this field, and a file named `README.md`, +`README.txt` or `README` exists in the package root, then the name of that +file will be used. You can suppress this behavior by setting this field to +`false`. If the field is set to `true`, a default value of `README.md` will +be assumed. + +#### The `homepage` field + +The `homepage` field should be a URL to a site that is the home page for your +package. + +```toml +[package] +# ... +homepage = "https://serde.rs/" +``` + +#### The `repository` field + +The `repository` field should be a URL to the source repository for your +package. + +```toml +[package] +# ... +repository = "https://github.com/rust-lang/cargo/" +``` + +#### The `license` and `license-file` fields + +The `license` field contains the name of the software license that the package +is released under. The `license-file` field contains the path to a file +containing the text of the license (relative to this `Cargo.toml`). + +[crates.io] interprets the `license` field as an [SPDX 2.1 license +expression][spdx-2.1-license-expressions]. The name must be a known license +from the [SPDX license list 3.11][spdx-license-list-3.11]. Parentheses are not +currently supported. See the [SPDX site] for more information. + +SPDX license expressions support AND and OR operators to combine multiple +licenses.[^slash] + +```toml +[package] +# ... +license = "MIT OR Apache-2.0" +``` + +Using `OR` indicates the user may choose either license. Using `AND` indicates +the user must comply with both licenses simultaneously. The `WITH` operator +indicates a license with a special exception. Some examples: + +* `MIT OR Apache-2.0` +* `LGPL-2.1-only AND MIT AND BSD-2-Clause` +* `GPL-2.0-or-later WITH Bison-exception-2.2` + +If a package is using a nonstandard license, then the `license-file` field may +be specified in lieu of the `license` field. + +```toml +[package] +# ... +license-file = "LICENSE.txt" +``` + +> **Note**: [crates.io] requires either `license` or `license-file` to be set. + +[^slash]: Previously multiple licenses could be separated with a `/`, but that +usage is deprecated. + +#### The `keywords` field + +The `keywords` field is an array of strings that describe this package. This +can help when searching for the package on a registry, and you may choose any +words that would help someone find this crate. + +```toml +[package] +# ... +keywords = ["gamedev", "graphics"] +``` + +> **Note**: [crates.io] has a maximum of 5 keywords. Each keyword must be +> ASCII text, start with a letter, and only contain letters, numbers, `_` or +> `-`, and have at most 20 characters. + +#### The `categories` field + +The `categories` field is an array of strings of the categories this package +belongs to. + +```toml +categories = ["command-line-utilities", "development-tools::cargo-plugins"] +``` + +> **Note**: [crates.io] has a maximum of 5 categories. Each category should +> match one of the strings available at <https://crates.io/category_slugs>, and +> must match exactly. + +<a id="the-workspace--field-optional"></a> +#### The `workspace` field + +The `workspace` field can be used to configure the workspace that this package +will be a member of. If not specified this will be inferred as the first +Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is +useful if the member is not inside a subdirectory of the workspace root. + +```toml +[package] +# ... +workspace = "path/to/workspace/root" +``` + +This field cannot be specified if the manifest already has a `[workspace]` +table defined. That is, a crate cannot both be a root crate in a workspace +(contain `[workspace]`) and also be a member crate of another workspace +(contain `package.workspace`). + +For more information, see the [workspaces chapter](workspaces.md). + +<a id="package-build"></a> +<a id="the-build-field-optional"></a> +#### The `build` field + +The `build` field specifies a file in the package root which is a [build +script] for building native code. More information can be found in the [build +script guide][build script]. + +[build script]: build-scripts.md + +```toml +[package] +# ... +build = "build.rs" +``` + +The default is `"build.rs"`, which loads the script from a file named +`build.rs` in the root of the package. Use `build = "custom_build_name.rs"` to +specify a path to a different file or `build = false` to disable automatic +detection of the build script. + +<a id="the-links-field-optional"></a> +#### The `links` field + +The `links` field specifies the name of a native library that is being linked +to. More information can be found in the [`links`][links] section of the build +script guide. + +[links]: build-scripts.md#the-links-manifest-key + +For example, a crate that links a native library called "git2" (e.g. `libgit2.a` +on Linux) may specify: + +```toml +[package] +# ... +links = "git2" +``` + +<a id="the-exclude-and-include-fields-optional"></a> +#### The `exclude` and `include` fields + +The `exclude` and `include` fields can be used to explicitly specify which +files are included when packaging a project to be [published][publishing], +and certain kinds of change tracking (described below). +The patterns specified in the `exclude` field identify a set of files that are +not included, and the patterns in `include` specify files that are explicitly +included. +You may run [`cargo package --list`][`cargo package`] to verify which files will +be included in the package. + +```toml +[package] +# ... +exclude = ["/ci", "images/", ".*"] +``` + +```toml +[package] +# ... +include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"] +``` + +The default if neither field is specified is to include all files from the +root of the package, except for the exclusions listed below. + +If `include` is not specified, then the following files will be excluded: + +* If the package is not in a git repository, all "hidden" files starting with + a dot will be skipped. +* If the package is in a git repository, any files that are ignored by the + [gitignore] rules of the repository and global git configuration will be + skipped. + +Regardless of whether `exclude` or `include` is specified, the following files +are always excluded: + +* Any sub-packages will be skipped (any subdirectory that contains a + `Cargo.toml` file). +* A directory named `target` in the root of the package will be skipped. + +The following files are always included: + +* The `Cargo.toml` file of the package itself is always included, it does not + need to be listed in `include`. +* A minimized `Cargo.lock` is automatically included if the package contains a + binary or example target, see [`cargo package`] for more information. +* If a [`license-file`](#the-license-and-license-file-fields) is specified, it + is always included. + +The options are mutually exclusive; setting `include` will override an +`exclude`. If you need to have exclusions to a set of `include` files, use the +`!` operator described below. + +The patterns should be [gitignore]-style patterns. Briefly: + +- `foo` matches any file or directory with the name `foo` anywhere in the + package. This is equivalent to the pattern `**/foo`. +- `/foo` matches any file or directory with the name `foo` only in the root of + the package. +- `foo/` matches any *directory* with the name `foo` anywhere in the package. +- Common glob patterns like `*`, `?`, and `[]` are supported: + - `*` matches zero or more characters except `/`. For example, `*.html` + matches any file or directory with the `.html` extension anywhere in the + package. + - `?` matches any character except `/`. For example, `foo?` matches `food`, + but not `foo`. + - `[]` allows for matching a range of characters. For example, `[ab]` + matches either `a` or `b`. `[a-z]` matches letters a through z. +- `**/` prefix matches in any directory. For example, `**/foo/bar` matches the + file or directory `bar` anywhere that is directly under directory `foo`. +- `/**` suffix matches everything inside. For example, `foo/**` matches all + files inside directory `foo`, including all files in subdirectories below + `foo`. +- `/**/` matches zero or more directories. For example, `a/**/b` matches + `a/b`, `a/x/b`, `a/x/y/b`, and so on. +- `!` prefix negates a pattern. For example, a pattern of `src/*.rs` and + `!foo.rs` would match all files with the `.rs` extension inside the `src` + directory, except for any file named `foo.rs`. + +The include/exclude list is also used for change tracking in some situations. +For targets built with `rustdoc`, it is used to determine the list of files to +track to determine if the target should be rebuilt. If the package has a +[build script] that does not emit any `rerun-if-*` directives, then the +include/exclude list is used for tracking if the build script should be re-run +if any of those files change. + +[gitignore]: https://git-scm.com/docs/gitignore + +<a id="the-publish--field-optional"></a> +#### The `publish` field + +The `publish` field can be used to prevent a package from being published to a +package registry (like *crates.io*) by mistake, for instance to keep a package +private in a company. + +```toml +[package] +# ... +publish = false +``` + +The value may also be an array of strings which are registry names that are +allowed to be published to. + +```toml +[package] +# ... +publish = ["some-registry-name"] +``` + +If publish array contains a single registry, `cargo publish` command will use +it when `--registry` flag is not specified. + +<a id="the-metadata-table-optional"></a> +#### The `metadata` table + +Cargo by default will warn about unused keys in `Cargo.toml` to assist in +detecting typos and such. The `package.metadata` table, however, is completely +ignored by Cargo and will not be warned about. This section can be used for +tools which would like to store package configuration in `Cargo.toml`. For +example: + +```toml +[package] +name = "..." +# ... + +# Metadata used when generating an Android APK, for example. +[package.metadata.android] +package-name = "my-awesome-android-app" +assets = "path/to/static" +``` + +There is a similar table at the workspace level at +[`workspace.metadata`][workspace-metadata]. While cargo does not specify a +format for the content of either of these tables, it is suggested that +external tools may wish to use them in a consistent fashion, such as referring +to the data in `workspace.metadata` if data is missing from `package.metadata`, +if that makes sense for the tool in question. + +[workspace-metadata]: workspaces.md#the-metadata-table + +#### The `default-run` field + +The `default-run` field in the `[package]` section of the manifest can be used +to specify a default binary picked by [`cargo run`]. For example, when there is +both `src/bin/a.rs` and `src/bin/b.rs`: + +```toml +[package] +default-run = "a" +``` + +### The `[badges]` section + +The `[badges]` section is for specifying status badges that can be displayed +on a registry website when the package is published. + +> Note: [crates.io] previously displayed badges next to a crate on its +> website, but that functionality has been removed. Packages should place +> badges in its README file which will be displayed on [crates.io] (see [the +> `readme` field](#the-readme-field)). + +```toml +[badges] +# The `maintenance` table indicates the status of the maintenance of +# the crate. This may be used by a registry, but is currently not +# used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437 +# and https://github.com/rust-lang/crates.io/issues/2438 for more details. +# +# The `status` field is required. Available options are: +# - `actively-developed`: New features are being added and bugs are being fixed. +# - `passively-maintained`: There are no plans for new features, but the maintainer intends to +# respond to issues that get filed. +# - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on +# it or providing support, but it works for the purposes it was designed for. +# - `experimental`: The author wants to share it with the community but is not intending to meet +# anyone's particular use case. +# - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone +# else. +# - `deprecated`: The maintainer does not recommend using this crate (the description of the crate +# can describe why, there could be a better solution available or there could be problems with +# the crate that the author does not want to fix). +# - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify +# their intentions, potential crate users will need to investigate on their own. +maintenance = { status = "..." } +``` + +### Dependency sections + +See the [specifying dependencies page](specifying-dependencies.md) for +information on the `[dependencies]`, `[dev-dependencies]`, +`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections. + +### The `[profile.*]` sections + +The `[profile]` tables provide a way to customize compiler settings such as +optimizations and debug settings. See [the Profiles chapter](profiles.md) for +more detail. + + + +[`cargo init`]: ../commands/cargo-init.md +[`cargo new`]: ../commands/cargo-new.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo run`]: ../commands/cargo-run.md +[crates.io]: https://crates.io/ +[docs.rs]: https://docs.rs/ +[publishing]: publishing.md +[Rust Edition]: ../../edition-guide/index.html +[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 +[spdx-license-list-3.11]: https://github.com/spdx/license-list-data/tree/v3.11 +[SPDX site]: https://spdx.org/license-list +[TOML]: https://toml.io/ + +<script> +(function() { + var fragments = { + "#the-project-layout": "../guide/project-layout.html", + "#examples": "cargo-targets.html#examples", + "#tests": "cargo-targets.html#tests", + "#integration-tests": "cargo-targets.html#integration-tests", + "#configuring-a-target": "cargo-targets.html#configuring-a-target", + "#target-auto-discovery": "cargo-targets.html#target-auto-discovery", + "#the-required-features-field-optional": "cargo-targets.html#the-required-features-field", + "#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field", + "#the-workspace-section": "workspaces.html#the-workspace-section", + "#virtual-workspace": "workspaces.html", + "#package-selection": "workspaces.html#package-selection", + "#the-features-section": "features.html#the-features-section", + "#rules": "features.html", + "#usage-in-end-products": "features.html", + "#usage-in-packages": "features.html", + "#the-patch-section": "overriding-dependencies.html#the-patch-section", + "#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions", + "#the-replace-section": "overriding-dependencies.html#the-replace-section", + }; + var target = fragments[window.location.hash]; + if (target) { + var url = window.location.toString(); + var base = url.substring(0, url.lastIndexOf('/')); + window.location.replace(base + "/" + target); + } +})(); +</script> diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md new file mode 100644 index 0000000..c8e8fbc --- /dev/null +++ b/src/doc/src/reference/overriding-dependencies.md @@ -0,0 +1,359 @@ +## Overriding Dependencies + +The desire to override a dependency can arise through a number of scenarios. +Most of them, however, boil down to the ability to work with a crate before +it's been published to [crates.io]. For example: + +* A crate you're working on is also used in a much larger application you're + working on, and you'd like to test a bug fix to the library inside of the + larger application. +* An upstream crate you don't work on has a new feature or a bug fix on the + master branch of its git repository which you'd like to test out. +* You're about to publish a new major version of your crate, but you'd like to + do integration testing across an entire package to ensure the new major + version works. +* You've submitted a fix to an upstream crate for a bug you found, but you'd + like to immediately have your application start depending on the fixed + version of the crate to avoid blocking on the bug fix getting merged. + +These scenarios can be solved with the [`[patch]` manifest +section](#the-patch-section). + +This chapter walks through a few different use cases, and includes details +on the different ways to override a dependency. + +* Example use cases + * [Testing a bugfix](#testing-a-bugfix) + * [Working with an unpublished minor version](#working-with-an-unpublished-minor-version) + * [Overriding repository URL](#overriding-repository-url) + * [Prepublishing a breaking change](#prepublishing-a-breaking-change) + * [Using `[patch]` with multiple versions](#using-patch-with-multiple-versions) +* Reference + * [The `[patch]` section](#the-patch-section) + * [The `[replace]` section](#the-replace-section) + * [`paths` overrides](#paths-overrides) + +> **Note**: See also specifying a dependency with [multiple locations], which +> can be used to override the source for a single dependency declaration in a +> local package. + +### Testing a bugfix + +Let's say you're working with the [`uuid` crate] but while you're working on it +you discover a bug. You are, however, quite enterprising so you decide to also +try to fix the bug! Originally your manifest will look like: + +[`uuid` crate]: https://crates.io/crates/uuid + +```toml +[package] +name = "my-library" +version = "0.1.0" + +[dependencies] +uuid = "1.0" +``` + +First thing we'll do is to clone the [`uuid` repository][uuid-repository] +locally via: + +```console +$ git clone https://github.com/uuid-rs/uuid.git +``` + +Next we'll edit the manifest of `my-library` to contain: + +```toml +[patch.crates-io] +uuid = { path = "../path/to/uuid" } +``` + +Here we declare that we're *patching* the source `crates-io` with a new +dependency. This will effectively add the local checked out version of `uuid` to +the crates.io registry for our local package. + +Next up we need to ensure that our lock file is updated to use this new version +of `uuid` so our package uses the locally checked out copy instead of one from +crates.io. The way `[patch]` works is that it'll load the dependency at +`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid` +it'll *also* return the local version. + +This means that the version number of the local checkout is significant and will +affect whether the patch is used. Our manifest declared `uuid = "1.0"` which +means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution +algorithm also means that we'll resolve to the maximum version within that +range. Typically this doesn't matter as the version of the git repository will +already be greater or match the maximum version published on crates.io, but it's +important to keep this in mind! + +In any case, typically all you need to do now is: + +```console +$ cargo build + Compiling uuid v1.0.0 (.../uuid) + Compiling my-library v0.1.0 (.../my-library) + Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs +``` + +And that's it! You're now building with the local version of `uuid` (note the +path in parentheses in the build output). If you don't see the local path version getting +built then you may need to run `cargo update -p uuid --precise $version` where +`$version` is the version of the locally checked out copy of `uuid`. + +Once you've fixed the bug you originally found the next thing you'll want to do +is to likely submit that as a pull request to the `uuid` crate itself. Once +you've done this then you can also update the `[patch]` section. The listing +inside of `[patch]` is just like the `[dependencies]` section, so once your pull +request is merged you could change your `path` dependency to: + +```toml +[patch.crates-io] +uuid = { git = 'https://github.com/uuid-rs/uuid.git' } +``` + +[uuid-repository]: https://github.com/uuid-rs/uuid + +### Working with an unpublished minor version + +Let's now shift gears a bit from bug fixes to adding features. While working on +`my-library` you discover that a whole new feature is needed in the `uuid` +crate. You've implemented this feature, tested it locally above with `[patch]`, +and submitted a pull request. Let's go over how you continue to use and test it +before it's actually published. + +Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but +since then the master branch of the git repository has updated to `1.0.1`. This +branch includes your new feature you submitted previously. To use this +repository we'll edit our `Cargo.toml` to look like + +```toml +[package] +name = "my-library" +version = "0.1.0" + +[dependencies] +uuid = "1.0.1" + +[patch.crates-io] +uuid = { git = 'https://github.com/uuid-rs/uuid.git' } +``` + +Note that our local dependency on `uuid` has been updated to `1.0.1` as it's +what we'll actually require once the crate is published. This version doesn't +exist on crates.io, though, so we provide it with the `[patch]` section of the +manifest. + +Now when our library is built it'll fetch `uuid` from the git repository and +resolve to 1.0.1 inside the repository instead of trying to download a version +from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can +be deleted. + +It's also worth noting that `[patch]` applies *transitively*. Let's say you use +`my-library` in a larger package, such as: + +```toml +[package] +name = "my-binary" +version = "0.1.0" + +[dependencies] +my-library = { git = 'https://example.com/git/my-library' } +uuid = "1.0" + +[patch.crates-io] +uuid = { git = 'https://github.com/uuid-rs/uuid.git' } +``` + +Remember that `[patch]` is applicable *transitively* but can only be defined at +the *top level* so we consumers of `my-library` have to repeat the `[patch]` section +if necessary. Here, though, the new `uuid` crate applies to *both* our dependency on +`uuid` and the `my-library -> uuid` dependency. The `uuid` crate will be resolved to +one version for this entire crate graph, 1.0.1, and it'll be pulled from the git +repository. + +#### Overriding repository URL + +In case the dependency you want to override isn't loaded from `crates.io`, +you'll have to change a bit how you use `[patch]`. For example, if the +dependency is a git dependency, you can override it to a local path with: + +```toml +[patch."https://github.com/your/repository"] +my-library = { path = "../my-library/path" } +``` + +And that's it! + +### Prepublishing a breaking change + +Let's take a look at working with a new major version of a crate, typically +accompanied with breaking changes. Sticking with our previous crates, this +means that we're going to be creating version 2.0.0 of the `uuid` crate. After +we've submitted all changes upstream we can update our manifest for +`my-library` to look like: + +```toml +[dependencies] +uuid = "2.0" + +[patch.crates-io] +uuid = { git = "https://github.com/uuid-rs/uuid.git", branch = "2.0.0" } +``` + +And that's it! Like with the previous example the 2.0.0 version doesn't actually +exist on crates.io but we can still put it in through a git dependency through +the usage of the `[patch]` section. As a thought exercise let's take another +look at the `my-binary` manifest from above again as well: + +```toml +[package] +name = "my-binary" +version = "0.1.0" + +[dependencies] +my-library = { git = 'https://example.com/git/my-library' } +uuid = "1.0" + +[patch.crates-io] +uuid = { git = 'https://github.com/uuid-rs/uuid.git', branch = '2.0.0' } +``` + +Note that this will actually resolve to two versions of the `uuid` crate. The +`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but +the `my-library` crate will use the `2.0.0` version of `uuid`. This will allow you +to gradually roll out breaking changes to a crate through a dependency graph +without being forced to update everything all at once. + +### Using `[patch]` with multiple versions + +You can patch in multiple versions of the same crate with the `package` key +used to rename dependencies. For example let's say that the `serde` crate has +a bugfix that we'd like to use to its `1.*` series but we'd also like to +prototype using a `2.0.0` version of serde we have in our git repository. To +configure this we'd do: + +```toml +[patch.crates-io] +serde = { git = 'https://github.com/serde-rs/serde.git' } +serde2 = { git = 'https://github.com/example/serde.git', package = 'serde', branch = 'v2' } +``` + +The first `serde = ...` directive indicates that serde `1.*` should be used +from the git repository (pulling in the bugfix we need) and the second `serde2 += ...` directive indicates that the `serde` package should also be pulled from +the `v2` branch of `https://github.com/example/serde`. We're assuming here +that `Cargo.toml` on that branch mentions version `2.0.0`. + +Note that when using the `package` key the `serde2` identifier here is actually +ignored. We simply need a unique name which doesn't conflict with other patched +crates. + +### The `[patch]` section + +The `[patch]` section of `Cargo.toml` can be used to override dependencies +with other copies. The syntax is similar to the +[`[dependencies]`][dependencies] section: + +```toml +[patch.crates-io] +foo = { git = 'https://github.com/example/foo.git' } +bar = { path = 'my/local/bar' } + +[dependencies.baz] +git = 'https://github.com/example/baz.git' + +[patch.'https://github.com/example/baz'] +baz = { git = 'https://github.com/example/patched-baz.git', branch = 'my-branch' } +``` + +> **Note**: The `[patch]` table can also be specified as a [configuration +> option](config.md), such as in a `.cargo/config.toml` file or a CLI option +> like `--config 'patch.crates-io.rand.path="rand"'`. This can be useful for +> local-only changes that you don't want to commit, or temporarily testing a +> patch. + +The `[patch]` table is made of dependency-like sub-tables. Each key after +`[patch]` is a URL of the source that is being patched, or the name of a +registry. The name `crates-io` may be used to override the default registry +[crates.io]. The first `[patch]` in the example above demonstrates overriding +[crates.io], and the second `[patch]` demonstrates overriding a git source. + +Each entry in these tables is a normal dependency specification, the same as +found in the `[dependencies]` section of the manifest. The dependencies listed +in the `[patch]` section are resolved and used to patch the source at the +URL specified. The above manifest snippet patches the `crates-io` source (e.g. +crates.io itself) with the `foo` crate and `bar` crate. It also +patches the `https://github.com/example/baz` source with a `my-branch` that +comes from elsewhere. + +Sources can be patched with versions of crates that do not exist, and they can +also be patched with versions of crates that already exist. If a source is +patched with a crate version that already exists in the source, then the +source's original crate is replaced. + +Cargo only looks at the patch settings in the `Cargo.toml` manifest at the +root of the workspace. Patch settings defined in dependencies will be +ignored. + +### The `[replace]` section + +> **Note**: `[replace]` is deprecated. You should use the +> [`[patch]`](#the-patch-section) table instead. + +This section of Cargo.toml can be used to override dependencies with other +copies. The syntax is similar to the `[dependencies]` section: + +```toml +[replace] +"foo:0.1.0" = { git = 'https://github.com/example/foo.git' } +"bar:1.0.2" = { path = 'my/local/bar' } +``` + +Each key in the `[replace]` table is a [package ID +specification](pkgid-spec.md), which allows arbitrarily choosing a node in the +dependency graph to override (the 3-part version number is required). The +value of each key is the same as the `[dependencies]` syntax for specifying +dependencies, except that you can't specify features. Note that when a crate +is overridden the copy it's overridden with must have both the same name and +version, but it can come from a different source (e.g., git or a local path). + +Cargo only looks at the replace settings in the `Cargo.toml` manifest at the +root of the workspace. Replace settings defined in dependencies will be +ignored. + +### `paths` overrides + +Sometimes you're only temporarily working on a crate and you don't want to have +to modify `Cargo.toml` like with the `[patch]` section above. For this use +case Cargo offers a much more limited version of overrides called **path +overrides**. + +Path overrides are specified through [`.cargo/config.toml`](config.md) instead of +`Cargo.toml`. Inside of `.cargo/config.toml` you'll specify a key called `paths`: + +```toml +paths = ["/path/to/uuid"] +``` + +This array should be filled with directories that contain a `Cargo.toml`. In +this instance, we’re just adding `uuid`, so it will be the only one that’s +overridden. This path can be either absolute or relative to the directory that +contains the `.cargo` folder. + +Path overrides are more restricted than the `[patch]` section, however, in +that they cannot change the structure of the dependency graph. When a +path replacement is used then the previous set of dependencies +must all match exactly to the new `Cargo.toml` specification. For example this +means that path overrides cannot be used to test out adding a dependency to a +crate, instead `[patch]` must be used in that situation. As a result usage of a +path override is typically isolated to quick bug fixes rather than larger +changes. + +Note: using a local configuration to override paths will only work for crates +that have been published to [crates.io]. You cannot use this feature to tell +Cargo how to find local unpublished crates. + + +[crates.io]: https://crates.io/ +[multiple locations]: specifying-dependencies.md#multiple-locations +[dependencies]: specifying-dependencies.md diff --git a/src/doc/src/reference/pkgid-spec.md b/src/doc/src/reference/pkgid-spec.md new file mode 100644 index 0000000..6c11b4b --- /dev/null +++ b/src/doc/src/reference/pkgid-spec.md @@ -0,0 +1,67 @@ +## Package ID Specifications + +### Package ID specifications + +Subcommands of Cargo frequently need to refer to a particular package within a +dependency graph for various operations like updating, cleaning, building, etc. +To solve this problem, Cargo supports *Package ID Specifications*. A specification +is a string which is used to uniquely refer to one package within a graph of +packages. + +The specification may be fully qualified, such as +`https://github.com/rust-lang/crates.io-index#regex@1.4.3` or it may be +abbreviated, such as `regex`. The abbreviated form may be used as long as it +uniquely identifies a single package in the dependency graph. If there is +ambiguity, additional qualifiers can be added to make it unique. For example, +if there are two versions of the `regex` package in the graph, then it can be +qualified with a version to make it unique, such as `regex@1.4.3`. + +#### Specification grammar + +The formal grammar for a Package Id Specification is: + +```notrust +spec := pkgname + | proto "://" hostname-and-path [ "#" ( pkgname | semver ) ] +pkgname := name [ ("@" | ":" ) semver ] + +proto := "http" | "git" | ... +``` + +Here, brackets indicate that the contents are optional. + +The URL form can be used for git dependencies, or to differentiate packages +that come from different sources such as different registries. + +#### Example specifications + +The following are references to the `regex` package on `crates.io`: + +| Spec | Name | Version | +|:------------------------------------------------------------|:-------:|:-------:| +| `regex` | `regex` | `*` | +| `regex@1.4.3` | `regex` | `1.4.3` | +| `https://github.com/rust-lang/crates.io-index#regex` | `regex` | `*` | +| `https://github.com/rust-lang/crates.io-index#regex@1.4.3` | `regex` | `1.4.3` | + +The following are some examples of specs for several different git dependencies: + +| Spec | Name | Version | +|:----------------------------------------------------------|:----------------:|:--------:| +| `https://github.com/rust-lang/cargo#0.52.0` | `cargo` | `0.52.0` | +| `https://github.com/rust-lang/cargo#cargo-platform@0.1.2` | <nobr>`cargo-platform`</nobr> | `0.1.2` | +| `ssh://git@github.com/rust-lang/regex.git#regex@1.4.3` | `regex` | `1.4.3` | + +Local packages on the filesystem can use `file://` URLs to reference them: + +| Spec | Name | Version | +|:---------------------------------------|:-----:|:-------:| +| `file:///path/to/my/project/foo` | `foo` | `*` | +| `file:///path/to/my/project/foo#1.1.8` | `foo` | `1.1.8` | + +#### Brevity of specifications + +The goal of this is to enable both succinct and exhaustive syntaxes for +referring to packages in a dependency graph. Ambiguous references may refer to +one or more packages. Most commands generate an error if more than one package +could be referred to with the same specification. diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md new file mode 100644 index 0000000..56c8538 --- /dev/null +++ b/src/doc/src/reference/profiles.md @@ -0,0 +1,469 @@ +## Profiles + +Profiles provide a way to alter the compiler settings, influencing things like +optimizations and debugging symbols. + +Cargo has 4 built-in profiles: `dev`, `release`, `test`, and `bench`. The +profile is automatically chosen based on which command is being run if a +profile is not specified on the command-line. In addition to the built-in +profiles, custom user-defined profiles can also be specified. + +Profile settings can be changed in [`Cargo.toml`](manifest.md) with the +`[profile]` table. Within each named profile, individual settings can be changed +with key/value pairs like this: + +```toml +[profile.dev] +opt-level = 1 # Use slightly better optimizations. +overflow-checks = false # Disable integer overflow checks. +``` + +Cargo only looks at the profile settings in the `Cargo.toml` manifest at the +root of the workspace. Profile settings defined in dependencies will be +ignored. + +Additionally, profiles can be overridden from a [config] definition. +Specifying a profile in a config file or environment variable will override +the settings from `Cargo.toml`. + +[config]: config.md + +### Profile settings + +The following is a list of settings that can be controlled in a profile. + +#### opt-level + +The `opt-level` setting controls the [`-C opt-level` flag] which controls the level +of optimization. Higher optimization levels may produce faster runtime code at +the expense of longer compiler times. Higher levels may also change and +rearrange the compiled code which may make it harder to use with a debugger. + +The valid options are: + +* `0`: no optimizations +* `1`: basic optimizations +* `2`: some optimizations +* `3`: all optimizations +* `"s"`: optimize for binary size +* `"z"`: optimize for binary size, but also turn off loop vectorization. + +It is recommended to experiment with different levels to find the right +balance for your project. There may be surprising results, such as level `3` +being slower than `2`, or the `"s"` and `"z"` levels not being necessarily +smaller. You may also want to reevaluate your settings over time as newer +versions of `rustc` changes optimization behavior. + +See also [Profile Guided Optimization] for more advanced optimization +techniques. + +[`-C opt-level` flag]: ../../rustc/codegen-options/index.html#opt-level +[Profile Guided Optimization]: ../../rustc/profile-guided-optimization.html + +#### debug + +The `debug` setting controls the [`-C debuginfo` flag] which controls the +amount of debug information included in the compiled binary. + +The valid options are: + +* `0` or `false`: no debug info at all +* `1`: line tables only +* `2` or `true`: full debug info + +You may wish to also configure the [`split-debuginfo`](#split-debuginfo) option +depending on your needs as well. + +[`-C debuginfo` flag]: ../../rustc/codegen-options/index.html#debuginfo + +#### split-debuginfo + +The `split-debuginfo` setting controls the [`-C split-debuginfo` flag] which +controls whether debug information, if generated, is either placed in the +executable itself or adjacent to it. + +This option is a string and acceptable values are the same as those the +[compiler accepts][`-C split-debuginfo` flag]. The default value for this option +is `unpacked` on macOS for profiles that have debug information otherwise +enabled. Otherwise the default for this option is [documented with rustc][`-C +split-debuginfo` flag] and is platform-specific. Some options are only +available on the [nightly channel]. The Cargo default may change in the future +once more testing has been performed, and support for DWARF is stabilized. + +[nightly channel]: ../../book/appendix-07-nightly-rust.html +[`-C split-debuginfo` flag]: ../../rustc/codegen-options/index.html#split-debuginfo + +#### strip + +The `strip` option controls the [`-C strip` flag], which directs rustc to +strip either symbols or debuginfo from a binary. This can be enabled like so: + +```toml +[package] +# ... + +[profile.release] +strip = "debuginfo" +``` + +Possible string values of `strip` are `"none"`, `"debuginfo"`, and `"symbols"`. +The default is `"none"`. + +You can also configure this option with the boolean values `true` or `false`. +`strip = true` is equivalent to `strip = "symbols"`. `strip = false` is +equivalent to `strip = "none"` and disables `strip` completely. + +[`-C strip` flag]: ../../rustc/codegen-options/index.html#strip + +#### debug-assertions + +The `debug-assertions` setting controls the [`-C debug-assertions` flag] which +turns `cfg(debug_assertions)` [conditional compilation] on or off. Debug +assertions are intended to include runtime validation which is only available +in debug/development builds. These may be things that are too expensive or +otherwise undesirable in a release build. Debug assertions enables the +[`debug_assert!` macro] in the standard library. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +[`-C debug-assertions` flag]: ../../rustc/codegen-options/index.html#debug-assertions +[conditional compilation]: ../../reference/conditional-compilation.md#debug_assertions +[`debug_assert!` macro]: ../../std/macro.debug_assert.html + +#### overflow-checks + +The `overflow-checks` setting controls the [`-C overflow-checks` flag] which +controls the behavior of [runtime integer overflow]. When overflow-checks are +enabled, a panic will occur on overflow. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +[`-C overflow-checks` flag]: ../../rustc/codegen-options/index.html#overflow-checks +[runtime integer overflow]: ../../reference/expressions/operator-expr.md#overflow + +#### lto + +The `lto` setting controls the [`-C lto` flag] which controls LLVM's [link +time optimizations]. LTO can produce better optimized code, using +whole-program analysis, at the cost of longer linking time. + +The valid options are: + +* `false`: Performs "thin local LTO" which performs "thin" LTO on the local + crate only across its [codegen units](#codegen-units). No LTO is performed + if codegen units is 1 or [opt-level](#opt-level) is 0. +* `true` or `"fat"`: Performs "fat" LTO which attempts to perform + optimizations across all crates within the dependency graph. +* `"thin"`: Performs ["thin" LTO]. This is similar to "fat", but takes + substantially less time to run while still achieving performance gains + similar to "fat". +* `"off"`: Disables LTO. + +See also the [`-C linker-plugin-lto`] `rustc` flag for cross-language LTO. + +[`-C lto` flag]: ../../rustc/codegen-options/index.html#lto +[link time optimizations]: https://llvm.org/docs/LinkTimeOptimization.html +[`-C linker-plugin-lto`]: ../../rustc/codegen-options/index.html#linker-plugin-lto +["thin" LTO]: http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html + +#### panic + +The `panic` setting controls the [`-C panic` flag] which controls which panic +strategy to use. + +The valid options are: + +* `"unwind"`: Unwind the stack upon panic. +* `"abort"`: Terminate the process upon panic. + +When set to `"unwind"`, the actual value depends on the default of the target +platform. For example, the NVPTX platform does not support unwinding, so it +always uses `"abort"`. + +Tests, benchmarks, build scripts, and proc macros ignore the `panic` setting. +The `rustc` test harness currently requires `unwind` behavior. See the +[`panic-abort-tests`] unstable flag which enables `abort` behavior. + +Additionally, when using the `abort` strategy and building a test, all of the +dependencies will also be forced to build with the `unwind` strategy. + +[`-C panic` flag]: ../../rustc/codegen-options/index.html#panic +[`panic-abort-tests`]: unstable.md#panic-abort-tests + +#### incremental + +The `incremental` setting controls the [`-C incremental` flag] which controls +whether or not incremental compilation is enabled. Incremental compilation +causes `rustc` to save additional information to disk which will be reused +when recompiling the crate, improving re-compile times. The additional +information is stored in the `target` directory. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +Incremental compilation is only used for workspace members and "path" +dependencies. + +The incremental value can be overridden globally with the `CARGO_INCREMENTAL` +[environment variable] or the [`build.incremental`] config variable. + +[`-C incremental` flag]: ../../rustc/codegen-options/index.html#incremental +[environment variable]: environment-variables.md +[`build.incremental`]: config.md#buildincremental + +#### codegen-units + +The `codegen-units` setting controls the [`-C codegen-units` flag] which +controls how many "code generation units" a crate will be split into. More +code generation units allows more of a crate to be processed in parallel +possibly reducing compile time, but may produce slower code. + +This option takes an integer greater than 0. + +The default is 256 for [incremental](#incremental) builds, and 16 for +non-incremental builds. + +[`-C codegen-units` flag]: ../../rustc/codegen-options/index.html#codegen-units + +#### rpath + +The `rpath` setting controls the [`-C rpath` flag] which controls +whether or not [`rpath`] is enabled. + +[`-C rpath` flag]: ../../rustc/codegen-options/index.html#rpath +[`rpath`]: https://en.wikipedia.org/wiki/Rpath + +### Default profiles + +#### dev + +The `dev` profile is used for normal development and debugging. It is the +default for build commands like [`cargo build`], and is used for `cargo install --debug`. + +The default settings for the `dev` profile are: + +```toml +[profile.dev] +opt-level = 0 +debug = true +split-debuginfo = '...' # Platform-specific. +debug-assertions = true +overflow-checks = true +lto = false +panic = 'unwind' +incremental = true +codegen-units = 256 +rpath = false +``` + +#### release + +The `release` profile is intended for optimized artifacts used for releases +and in production. This profile is used when the `--release` flag is used, and +is the default for [`cargo install`]. + +The default settings for the `release` profile are: + +```toml +[profile.release] +opt-level = 3 +debug = false +split-debuginfo = '...' # Platform-specific. +debug-assertions = false +overflow-checks = false +lto = false +panic = 'unwind' +incremental = false +codegen-units = 16 +rpath = false +``` + +#### test + +The `test` profile is the default profile used by [`cargo test`]. +The `test` profile inherits the settings from the [`dev`](#dev) profile. + +#### bench + +The `bench` profile is the default profile used by [`cargo bench`]. +The `bench` profile inherits the settings from the [`release`](#release) profile. + +#### Build Dependencies + +To compile quickly, all profiles, by default, do not optimize build +dependencies (build scripts, proc macros, and their dependencies), and avoid +computing debug info when a build dependency is not used as a runtime +dependency. The default settings for build overrides are: + +```toml +[profile.dev.build-override] +opt-level = 0 +codegen-units = 256 +debug = false # when possible + +[profile.release.build-override] +opt-level = 0 +codegen-units = 256 +``` + +However, if errors occur while running build dependencies, turning full debug +info on will improve backtraces and debuggability when needed: + +```toml +debug = true +``` + +Build dependencies otherwise inherit settings from the active profile in use, as +described in [Profile selection](#profile-selection). + +### Custom profiles + +In addition to the built-in profiles, additional custom profiles can be +defined. These may be useful for setting up multiple workflows and build +modes. When defining a custom profile, you must specify the `inherits` key to +specify which profile the custom profile inherits settings from when the +setting is not specified. + +For example, let's say you want to compare a normal release build with a +release build with [LTO](#lto) optimizations, you can specify something like +the following in `Cargo.toml`: + +```toml +[profile.release-lto] +inherits = "release" +lto = true +``` + +The `--profile` flag can then be used to choose this custom profile: + +```console +cargo build --profile release-lto +``` + +The output for each profile will be placed in a directory of the same name +as the profile in the [`target` directory]. As in the example above, the +output would go into the `target/release-lto` directory. + +[`target` directory]: ../guide/build-cache.md + +### Profile selection + +The profile used depends on the command, the command-line flags like +`--release` or `--profile`, and the package (in the case of +[overrides](#overrides)). The default profile if none is specified is: + +| Command | Default Profile | +|---------|-----------------| +| [`cargo run`], [`cargo build`],<br>[`cargo check`], [`cargo rustc`] | [`dev` profile](#dev) | +| [`cargo test`] | [`test` profile](#test) +| [`cargo bench`] | [`bench` profile](#bench) +| [`cargo install`] | [`release` profile](#release) + +You can switch to a different profile using the `--profile=NAME` option which will used the given profile. +The `--release` flag is equivalent to `--profile=release`. + +The selected profile applies to all Cargo targets, +including [library](./cargo-targets.md#library), +[binary](./cargo-targets.md#binaries), +[example](./cargo-targets.md#examples), +[test](./cargo-targets.md#tests), +and [benchmark](./cargo-targets.md#benchmarks). + +The profile for specific packages can be specified with +[overrides](#overrides), described below. + +[`cargo bench`]: ../commands/cargo-bench.md +[`cargo build`]: ../commands/cargo-build.md +[`cargo check`]: ../commands/cargo-check.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo rustc`]: ../commands/cargo-rustc.md +[`cargo test`]: ../commands/cargo-test.md + +### Overrides + +Profile settings can be overridden for specific packages and build-time +crates. To override the settings for a specific package, use the `package` +table to change the settings for the named package: + +```toml +# The `foo` package will use the -Copt-level=3 flag. +[profile.dev.package.foo] +opt-level = 3 +``` + +The package name is actually a [Package ID Spec](pkgid-spec.md), so you can +target individual versions of a package with syntax such as +`[profile.dev.package."foo:2.1.0"]`. + +To override the settings for all dependencies (but not any workspace member), +use the `"*"` package name: + +```toml +# Set the default for dependencies. +[profile.dev.package."*"] +opt-level = 2 +``` + +To override the settings for build scripts, proc macros, and their +dependencies, use the `build-override` table: + +```toml +# Set the settings for build scripts and proc-macros. +[profile.dev.build-override] +opt-level = 3 +``` + +> Note: When a dependency is both a normal dependency and a build dependency, +> Cargo will try to only build it once when `--target` is not specified. When +> using `build-override`, the dependency may need to be built twice, once as a +> normal dependency and once with the overridden build settings. This may +> increase initial build times. + +The precedence for which value is used is done in the following order (first +match wins): + +1. `[profile.dev.package.name]` --- A named package. +2. `[profile.dev.package."*"]` --- For any non-workspace member. +3. `[profile.dev.build-override]` --- Only for build scripts, proc macros, and + their dependencies. +4. `[profile.dev]` --- Settings in `Cargo.toml`. +5. Default values built-in to Cargo. + +Overrides cannot specify the `panic`, `lto`, or `rpath` settings. + +#### Overrides and generics + +The location where generic code is instantiated will influence the +optimization settings used for that generic code. This can cause subtle +interactions when using profile overrides to change the optimization level of +a specific crate. If you attempt to raise the optimization level of a +dependency which defines generic functions, those generic functions may not be +optimized when used in your local crate. This is because the code may be +generated in the crate where it is instantiated, and thus may use the +optimization settings of that crate. + +For example, [nalgebra] is a library which defines vectors and matrices making +heavy use of generic parameters. If your local code defines concrete nalgebra +types like `Vector4<f64>` and uses their methods, the corresponding nalgebra +code will be instantiated and built within your crate. Thus, if you attempt to +increase the optimization level of `nalgebra` using a profile override, it may +not result in faster performance. + +Further complicating the issue, `rustc` has some optimizations where it will +attempt to share monomorphized generics between crates. If the opt-level is 2 +or 3, then a crate will not use monomorphized generics from other crates, nor +will it export locally defined monomorphized items to be shared with other +crates. When experimenting with optimizing dependencies for development, +consider trying opt-level 1, which will apply some optimizations while still +allowing monomorphized items to be shared. + +[nalgebra]: https://crates.io/crates/nalgebra diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md new file mode 100644 index 0000000..013faf6 --- /dev/null +++ b/src/doc/src/reference/publishing.md @@ -0,0 +1,279 @@ +## Publishing on crates.io + +Once you've got a library that you'd like to share with the world, it's time to +publish it on [crates.io]! Publishing a crate is when a specific +version is uploaded to be hosted on [crates.io]. + +Take care when publishing a crate, because a publish is **permanent**. The +version can never be overwritten, and the code cannot be deleted. There is no +limit to the number of versions which can be published, however. + +### Before your first publish + +First things first, you’ll need an account on [crates.io] to acquire +an API token. To do so, [visit the home page][crates.io] and log in via a GitHub +account (required for now). You will also need to verify your email address on the +[Account Settings](https://crates.io/me) page. Once that is done create an API token, +make sure you copy it. Once you leave the page you will not be able to see it +again. + +Then run the [`cargo login`] command. + +```console +$ cargo login +``` + +Then at the prompt put in the token specified. +```console +please paste the API Token found on https://crates.io/me below +abcdefghijklmnopqrstuvwxyz012345 +``` + +This command will inform Cargo of your API token and store it locally in your +`~/.cargo/credentials.toml`. Note that this token is a **secret** and should not be +shared with anyone else. If it leaks for any reason, you should revoke it +immediately. + +### Before publishing a new crate + +Keep in mind that crate names on [crates.io] are allocated on a first-come-first-serve +basis. Once a crate name is taken, it cannot be used for another crate. + +Check out the [metadata you can specify](manifest.md) in `Cargo.toml` to +ensure your crate can be discovered more easily! Before publishing, make sure +you have filled out the following fields: + +- [`license` or `license-file`] +- [`description`] +- [`homepage`] +- [`documentation`] +- [`repository`] +- [`readme`] + +It would also be a good idea to include some [`keywords`] and [`categories`], +though they are not required. + +If you are publishing a library, you may also want to consult the [Rust API +Guidelines]. + +#### Packaging a crate + +The next step is to package up your crate and upload it to [crates.io]. For +this we’ll use the [`cargo publish`] subcommand. This command performs the following +steps: + +1. Perform some verification checks on your package. +2. Compress your source code into a `.crate` file. +3. Extract the `.crate` file into a temporary directory and verify that it + compiles. +4. Upload the `.crate` file to [crates.io]. +5. The registry will perform some additional checks on the uploaded package + before adding it. + +It is recommended that you first run `cargo publish --dry-run` (or [`cargo +package`] which is equivalent) to ensure there aren't any warnings or errors +before publishing. This will perform the first three steps listed above. + +```console +$ cargo publish --dry-run +``` + +You can inspect the generated `.crate` file in the `target/package` directory. +[crates.io] currently has a 10MB size limit on the `.crate` file. You may want +to check the size of the `.crate` file to ensure you didn't accidentally +package up large assets that are not required to build your package, such as +test data, website documentation, or code generation. You can check which +files are included with the following command: + +```console +$ cargo package --list +``` + +Cargo will automatically ignore files ignored by your version control system +when packaging, but if you want to specify an extra set of files to ignore you +can use the [`exclude` key](manifest.md#the-exclude-and-include-fields) in the +manifest: + +```toml +[package] +# ... +exclude = [ + "public/assets/*", + "videos/*", +] +``` + +If you’d rather explicitly list the files to include, Cargo also supports an +`include` key, which if set, overrides the `exclude` key: + +```toml +[package] +# ... +include = [ + "**/*.rs", + "Cargo.toml", +] +``` + +### Uploading the crate + +When you are ready to publish, use the [`cargo publish`] command +to upload to [crates.io]: + +```console +$ cargo publish +``` + +And that’s it, you’ve now published your first crate! + +### Publishing a new version of an existing crate + +In order to release a new version, change [the `version` value](manifest.md#the-version-field) specified in your `Cargo.toml` manifest. +Keep in mind [the SemVer rules](semver.md) which provide guidelines on what is a compatible change. +Then run [`cargo publish`] as described above to upload the new version. + +### Managing a crates.io-based crate + +Management of crates is primarily done through the command line `cargo` tool +rather than the [crates.io] web interface. For this, there are a few subcommands +to manage a crate. + +#### `cargo yank` + +Occasions may arise where you publish a version of a crate that actually ends up +being broken for one reason or another (syntax error, forgot to include a file, +etc.). For situations such as this, Cargo supports a “yank” of a version of a +crate. + +```console +$ cargo yank --version 1.0.1 +$ cargo yank --version 1.0.1 --undo +``` + +A yank **does not** delete any code. This feature is not intended for deleting +accidentally uploaded secrets, for example. If that happens, you must reset +those secrets immediately. + +The semantics of a yanked version are that no new dependencies can be created +against that version, but all existing dependencies continue to work. One of the +major goals of [crates.io] is to act as a permanent archive of crates that does +not change over time, and allowing deletion of a version would go against this +goal. Essentially a yank means that all packages with a `Cargo.lock` will not +break, while any future `Cargo.lock` files generated will not list the yanked +version. + +#### `cargo owner` + +A crate is often developed by more than one person, or the primary maintainer +may change over time! The owner of a crate is the only person allowed to publish +new versions of the crate, but an owner may designate additional owners. + +```console +$ cargo owner --add github-handle +$ cargo owner --remove github-handle +$ cargo owner --add github:rust-lang:owners +$ cargo owner --remove github:rust-lang:owners +``` + +The owner IDs given to these commands must be GitHub user names or GitHub teams. + +If a user name is given to `--add`, that user is invited as a “named” owner, with +full rights to the crate. In addition to being able to publish or yank versions +of the crate, they have the ability to add or remove owners, *including* the +owner that made *them* an owner. Needless to say, you shouldn’t make people you +don’t fully trust into a named owner. In order to become a named owner, a user +must have logged into [crates.io] previously. + +If a team name is given to `--add`, that team is invited as a “team” owner, with +restricted right to the crate. While they have permission to publish or yank +versions of the crate, they *do not* have the ability to add or remove owners. +In addition to being more convenient for managing groups of owners, teams are +just a bit more secure against owners becoming malicious. + +The syntax for teams is currently `github:org:team` (see examples above). +In order to invite a team as an owner one must be a member of that team. No +such restriction applies to removing a team as an owner. + +### GitHub permissions + +Team membership is not something GitHub provides simple public access to, and it +is likely for you to encounter the following message when working with them: + +> It looks like you don’t have permission to query a necessary property from +GitHub to complete this request. You may need to re-authenticate on [crates.io] +to grant permission to read GitHub org memberships. + +This is basically a catch-all for “you tried to query a team, and one of the +five levels of membership access control denied this”. That is not an +exaggeration. GitHub’s support for team access control is Enterprise Grade. + +The most likely cause of this is simply that you last logged in before this +feature was added. We originally requested *no* permissions from GitHub when +authenticating users, because we didn’t actually ever use the user’s token for +anything other than logging them in. However to query team membership on your +behalf, we now require [the `read:org` scope][oauth-scopes]. + +You are free to deny us this scope, and everything that worked before teams +were introduced will keep working. However you will never be able to add a team +as an owner, or publish a crate as a team owner. If you ever attempt to do this, +you will get the error above. You may also see this error if you ever try to +publish a crate that you don’t own at all, but otherwise happens to have a team. + +If you ever change your mind, or just aren’t sure if [crates.io] has sufficient +permission, you can always go to <https://crates.io/> and re-authenticate, +which will prompt you for permission if [crates.io] doesn’t have all the scopes +it would like to. + +An additional barrier to querying GitHub is that the organization may be +actively denying third party access. To check this, you can go to: + +```text +https://github.com/organizations/:org/settings/oauth_application_policy +``` + +where `:org` is the name of the organization (e.g., `rust-lang`). You may see +something like: + + + +Where you may choose to explicitly remove [crates.io] from your organization’s +blacklist, or simply press the “Remove Restrictions” button to allow all third +party applications to access this data. + +Alternatively, when [crates.io] requested the `read:org` scope, you could have +explicitly whitelisted [crates.io] querying the org in question by pressing +the “Grant Access” button next to its name: + + + +#### Troubleshooting GitHub team access errors + +When trying to add a GitHub team as crate owner, you may see an error like: + +```text +error: failed to invite owners to crate <crate_name>: api errors (status 200 OK): could not find the github team org/repo +``` +In that case, you should go to [the GitHub Application settings page] and +check if crates.io is listed in the `Authorized OAuth Apps` tab. +If it isn't, you should go to <https://crates.io/> and authorize it. +Then go back to the Application Settings page on GitHub, click on the +crates.io application in the list, and make sure you or your organization is +listed in the "Organization access" list with a green check mark. If there's +a button labeled `Grant` or `Request`, you should grant the access or +request the org owner to do so. + +[Rust API Guidelines]: https://rust-lang.github.io/api-guidelines/ +[`cargo login`]: ../commands/cargo-login.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo publish`]: ../commands/cargo-publish.md +[`categories`]: manifest.md#the-categories-field +[`description`]: manifest.md#the-description-field +[`documentation`]: manifest.md#the-documentation-field +[`homepage`]: manifest.md#the-homepage-field +[`keywords`]: manifest.md#the-keywords-field +[`license` or `license-file`]: manifest.md#the-license-and-license-file-fields +[`readme`]: manifest.md#the-readme-field +[`repository`]: manifest.md#the-repository-field +[crates.io]: https://crates.io/ +[oauth-scopes]: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/ +[the GitHub Application settings page]: https://github.com/settings/applications diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md new file mode 100644 index 0000000..7714a36 --- /dev/null +++ b/src/doc/src/reference/registries.md @@ -0,0 +1,151 @@ +## Registries + +Cargo installs crates and fetches dependencies from a "registry". The default +registry is [crates.io]. A registry contains an "index" which contains a +searchable list of available crates. A registry may also provide a web API to +support publishing new crates directly from Cargo. + +> Note: If you are interested in mirroring or vendoring an existing registry, +> take a look at [Source Replacement]. + +If you are implementing a registry server, see [Running a Registry] for more +details about the protocol between Cargo and a registry. + +### Using an Alternate Registry + +To use a registry other than [crates.io], the name and index URL of the +registry must be added to a [`.cargo/config.toml` file][config]. The `registries` +table has a key for each registry, for example: + +```toml +[registries] +my-registry = { index = "https://my-intranet:8080/git/index" } +``` + +The `index` key should be a URL to a git repository with the registry's index or a +Cargo sparse registry URL with the `sparse+` prefix. + +A crate can then depend on a crate from another registry by specifying the +`registry` key and a value of the registry's name in that dependency's entry +in `Cargo.toml`: + +```toml +# Sample Cargo.toml +[package] +name = "my-project" +version = "0.1.0" +edition = "2021" + +[dependencies] +other-crate = { version = "1.0", registry = "my-registry" } +``` + +As with most config values, the index may be specified with an environment +variable instead of a config file. For example, setting the following +environment variable will accomplish the same thing as defining a config file: + +```ignore +CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index +``` + +> Note: [crates.io] does not accept packages that depend on crates from other +> registries. + +### Publishing to an Alternate Registry + +If the registry supports web API access, then packages can be published +directly to the registry from Cargo. Several of Cargo's commands such as +[`cargo publish`] take a `--registry` command-line flag to indicate which +registry to use. For example, to publish the package in the current directory: + +1. `cargo login --registry=my-registry` + + This only needs to be done once. You must enter the secret API token + retrieved from the registry's website. Alternatively the token may be + passed directly to the `publish` command with the `--token` command-line + flag or an environment variable with the name of the registry such as + `CARGO_REGISTRIES_MY_REGISTRY_TOKEN`. + +2. `cargo publish --registry=my-registry` + +Instead of always passing the `--registry` command-line option, the default +registry may be set in [`.cargo/config.toml`][config] with the `registry.default` +key. For example: + +```toml +[registry] +default = "my-registry" +``` + +Setting the `package.publish` key in the `Cargo.toml` manifest restricts which +registries the package is allowed to be published to. This is useful to +prevent accidentally publishing a closed-source package to [crates.io]. The +value may be a list of registry names, for example: + +```toml +[package] +# ... +publish = ["my-registry"] +``` + +The `publish` value may also be `false` to restrict all publishing, which is +the same as an empty list. + +The authentication information saved by [`cargo login`] is stored in the +`credentials.toml` file in the Cargo home directory (default `$HOME/.cargo`). It +has a separate table for each registry, for example: + +```toml +[registries.my-registry] +token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" +``` + +### Registry Protocols +Cargo supports two remote registry protocols: `git` and `sparse`. If the registry +index URL starts with `sparse+`, Cargo uses the sparse protocol. Otherwise +Cargo uses the `git` protocol. + +The `git` protocol stores index metadata in a git repository and requires Cargo to clone +the entire repo. + +The `sparse` protocol fetches individual metadata files using plain HTTP requests. +Since Cargo only downloads the metadata for relevant crates, the `sparse` protocol can +save significant time and bandwidth. + +The [crates.io] registry supports both protocols. The protocol for crates.io is +controlled via the [`registries.crates-io.protocol`] config key. + +[Source Replacement]: source-replacement.md +[Running a Registry]: running-a-registry.md +[`cargo publish`]: ../commands/cargo-publish.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo login`]: ../commands/cargo-login.md +[config]: config.md +[crates.io]: https://crates.io/ +[`registries.crates-io.protocol`]: config.md#registriescrates-ioprotocol + + +<script> +(function() { + var fragments = { + "#running-a-registry": "running-a-registry.html", + "#index-format": "registry-index.html", + "#web-api": "registry-web-api.html", + "#publish": "registry-web-api.html#publish", + "#yank": "registry-web-api.html#yank", + "#unyank": "registry-web-api.html#unyank", + "#owners": "registry-web-api.html#owners", + "#owners-list": "registry-web-api.html#owners-list", + "#owners-add": "registry-web-api.html#owners-add", + "#owners-remove": "registry-web-api.html#owners-remove", + "#search": "registry-web-api.html#search", + "#login": "registry-web-api.html#login", + }; + var target = fragments[window.location.hash]; + if (target) { + var url = window.location.toString(); + var base = url.substring(0, url.lastIndexOf('/')); + window.location.replace(base + "/" + target); + } +})(); +</script> diff --git a/src/doc/src/reference/registry-index.md b/src/doc/src/reference/registry-index.md new file mode 100644 index 0000000..ceba148 --- /dev/null +++ b/src/doc/src/reference/registry-index.md @@ -0,0 +1,259 @@ +## Index Format + +The following defines the format of the index. New features are occasionally +added, which are only understood starting with the version of Cargo that +introduced them. Older versions of Cargo may not be able to use packages that +make use of new features. However, the format for older packages should not +change, so older versions of Cargo should be able to use them. + +### Index Configuration +The root of the index contains a file named `config.json` which contains JSON +information used by Cargo for accessing the registry. This is an example of +what the [crates.io] config file looks like: + +```javascript +{ + "dl": "https://crates.io/api/v1/crates", + "api": "https://crates.io" +} +``` + +The keys are: +- `dl`: This is the URL for downloading crates listed in the index. The value + may have the following markers which will be replaced with their + corresponding value: + + - `{crate}`: The name of crate. + - `{version}`: The crate version. + - `{prefix}`: A directory prefix computed from the crate name. For example, + a crate named `cargo` has a prefix of `ca/rg`. See below for details. + - `{lowerprefix}`: Lowercase variant of `{prefix}`. + - `{sha256-checksum}`: The crate's sha256 checksum. + + If none of the markers are present, then the value + `/{crate}/{version}/download` is appended to the end. +- `api`: This is the base URL for the web API. This key is optional, but if it + is not specified, commands such as [`cargo publish`] will not work. The web + API is described below. + + +### Download Endpoint +The download endpoint should send the `.crate` file for the requested package. +Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2. +The exact specifics of TLS support depend on the platform that Cargo is +running on, the version of Cargo, and how it was compiled. + + +### Index files +The rest of the index repository contains one file for each package, where the +filename is the name of the package in lowercase. Each version of the package +has a separate line in the file. The files are organized in a tier of +directories: + +- Packages with 1 character names are placed in a directory named `1`. +- Packages with 2 character names are placed in a directory named `2`. +- Packages with 3 character names are placed in the directory + `3/{first-character}` where `{first-character}` is the first character of + the package name. +- All other packages are stored in directories named + `{first-two}/{second-two}` where the top directory is the first two + characters of the package name, and the next subdirectory is the third and + fourth characters of the package name. For example, `cargo` would be stored + in a file named `ca/rg/cargo`. + +> Note: Although the index filenames are in lowercase, the fields that contain +> package names in `Cargo.toml` and the index JSON data are case-sensitive and +> may contain upper and lower case characters. + +The directory name above is calculated based on the package name converted to +lowercase; it is represented by the marker `{lowerprefix}`. When the original +package name is used without case conversion, the resulting directory name is +represented by the marker `{prefix}`. For example, the package `MyCrate` would +have a `{prefix}` of `My/Cr` and a `{lowerprefix}` of `my/cr`. In general, +using `{prefix}` is recommended over `{lowerprefix}`, but there are pros and +cons to each choice. Using `{prefix}` on case-insensitive filesystems results +in (harmless-but-inelegant) directory aliasing. For example, `crate` and +`CrateTwo` have `{prefix}` values of `cr/at` and `Cr/at`; these are distinct on +Unix machines but alias to the same directory on Windows. Using directories +with normalized case avoids aliasing, but on case-sensitive filesystems it's +harder to support older versions of Cargo that lack `{prefix}`/`{lowerprefix}`. +For example, nginx rewrite rules can easily construct `{prefix}` but can't +perform case-conversion to construct `{lowerprefix}`. + +Registries should consider enforcing limitations on package names added to +their index. Cargo itself allows names with any [alphanumeric], `-`, or `_` +characters. [crates.io] imposes its own limitations, including the following: + +- Only allows ASCII characters. +- Only alphanumeric, `-`, and `_` characters. +- First character must be alphabetic. +- Case-insensitive collision detection. +- Prevent differences of `-` vs `_`. +- Under a specific length (max 64). +- Rejects reserved names, such as Windows special filenames like "nul". + +Registries should consider incorporating similar restrictions, and consider +the security implications, such as [IDN homograph +attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack) and other +concerns in [UTR36](https://www.unicode.org/reports/tr36/) and +[UTS39](https://www.unicode.org/reports/tr39/). + +Each line in a package file contains a JSON object that describes a published +version of the package. The following is a pretty-printed example with comments +explaining the format of the entry. + +```javascript +{ + // The name of the package. + // This must only contain alphanumeric, `-`, or `_` characters. + "name": "foo", + // The version of the package this row is describing. + // This must be a valid version number according to the Semantic + // Versioning 2.0.0 spec at https://semver.org/. + "vers": "0.1.0", + // Array of direct dependencies of the package. + "deps": [ + { + // Name of the dependency. + // If the dependency is renamed from the original package name, + // this is the new name. The original package name is stored in + // the `package` field. + "name": "rand", + // The SemVer requirement for this dependency. + // This must be a valid version requirement defined at + // https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html. + "req": "^0.6", + // Array of features (as strings) enabled for this dependency. + "features": ["i128_support"], + // Boolean of whether or not this is an optional dependency. + "optional": false, + // Boolean of whether or not default features are enabled. + "default_features": true, + // The target platform for the dependency. + // null if not a target dependency. + // Otherwise, a string such as "cfg(windows)". + "target": null, + // The dependency kind. + // "dev", "build", or "normal". + // Note: this is a required field, but a small number of entries + // exist in the crates.io index with either a missing or null + // `kind` field due to implementation bugs. + "kind": "normal", + // The URL of the index of the registry where this dependency is + // from as a string. If not specified or null, it is assumed the + // dependency is in the current registry. + "registry": null, + // If the dependency is renamed, this is a string of the actual + // package name. If not specified or null, this dependency is not + // renamed. + "package": null, + } + ], + // A SHA256 checksum of the `.crate` file. + "cksum": "d867001db0e2b6e0496f9fac96930e2d42233ecd3ca0413e0753d4c7695d289c", + // Set of features defined for the package. + // Each feature maps to an array of features or dependencies it enables. + "features": { + "extras": ["rand/simd_support"] + }, + // Boolean of whether or not this version has been yanked. + "yanked": false, + // The `links` string value from the package's manifest, or null if not + // specified. This field is optional and defaults to null. + "links": null, + // An unsigned 32-bit integer value indicating the schema version of this + // entry. + // + // If this not specified, it should be interpreted as the default of 1. + // + // Cargo (starting with version 1.51) will ignore versions it does not + // recognize. This provides a method to safely introduce changes to index + // entries and allow older versions of cargo to ignore newer entries it + // doesn't understand. Versions older than 1.51 ignore this field, and + // thus may misinterpret the meaning of the index entry. + // + // The current values are: + // + // * 1: The schema as documented here, not including newer additions. + // This is honored in Rust version 1.51 and newer. + // * 2: The addition of the `features2` field. + // This is honored in Rust version 1.60 and newer. + "v": 2, + // This optional field contains features with new, extended syntax. + // Specifically, namespaced features (`dep:`) and weak dependencies + // (`pkg?/feat`). + // + // This is separated from `features` because versions older than 1.19 + // will fail to load due to not being able to parse the new syntax, even + // with a `Cargo.lock` file. + // + // Cargo will merge any values listed here with the "features" field. + // + // If this field is included, the "v" field should be set to at least 2. + // + // Registries are not required to use this field for extended feature + // syntax, they are allowed to include those in the "features" field. + // Using this is only necessary if the registry wants to support cargo + // versions older than 1.19, which in practice is only crates.io since + // those older versions do not support other registries. + "features2": { + "serde": ["dep:serde", "chrono?/serde"] + } +} +``` + +The JSON objects should not be modified after they are added except for the +`yanked` field whose value may change at any time. + +### Index Protocols +Cargo supports two remote registry protocols: `git` and `sparse`. The `git` protocol +stores index files in a git repository and the `sparse` protocol fetches individual +files over HTTP. + +#### Git Protocol +The git protocol has no protocol prefix in the index url. For example the git index URL +for [crates.io] is `https://github.com/rust-lang/crates.io-index`. + +Cargo caches the git repository on disk so that it can efficiently incrementally fetch +updates. + +#### Sparse Protocol +The sparse protocol uses the `sparse+` protocol prefix in the registry URL. For example, +the sparse index URL for [crates.io] is `sparse+https://index.crates.io/`. + +The sparse protocol downloads each index file using an individual HTTP request. Since +this results in a large number of small HTTP requests, performance is signficiantly +improved with a server that supports pipelining and HTTP/2. + +##### Caching +Cargo caches the crate metadata files, and captures the `ETag` or `Last-Modified` +HTTP header from the server for each entry. When refreshing crate metadata, Cargo +sends the `If-None-Match` or `If-Modified-Since` header to allow the server to respond +with HTTP 304 "Not Modified" if the local cache is valid, saving time and bandwidth. +If both `ETag` and `Last-Modified` headers are present, Cargo uses the `ETag` only. + +##### Cache Invalidation +If a registry is using some kind of CDN or proxy which caches access to the index files, +then it is recommended that registries implement some form of cache invalidation when +the files are updated. If these caches are not updated, then users may not be able to +access new crates until the cache is cleared. + +##### Nonexistent Crates +For crates that do not exist, the registry should respond with a 404 "Not Found", 410 "Gone" +or 451 "Unavailable For Legal Reasons" code. + +##### Sparse Limitations +Since the URL of the registry is stored in the lockfile, it's not recommended to offer +a registry with both protocols. Discussion about a transition plan is ongoing in issue +[#10964]. The [crates.io] registry is an exception, since Cargo internally substitues +the equivalent git URL when the sparse protocol is used. + +If a registry does offer both protocols, it's currently recommended to choose one protocol +as the canonical protocol and use [source replacement] for the other protocol. + + +[`cargo publish`]: ../commands/cargo-publish.md +[alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric +[crates.io]: https://crates.io/ +[source replacement]: ../reference/source-replacement.md +[#10964]: https://github.com/rust-lang/cargo/issues/10964 diff --git a/src/doc/src/reference/registry-web-api.md b/src/doc/src/reference/registry-web-api.md new file mode 100644 index 0000000..618ae0b --- /dev/null +++ b/src/doc/src/reference/registry-web-api.md @@ -0,0 +1,354 @@ + +## Web API + +A registry may host a web API at the location defined in `config.json` to +support any of the actions listed below. + +Cargo includes the `Authorization` header for requests that require +authentication. The header value is the API token. The server should respond +with a 403 response code if the token is not valid. Users are expected to +visit the registry's website to obtain a token, and Cargo can store the token +using the [`cargo login`] command, or by passing the token on the +command-line. + +Responses use the 200 response code for success. +Errors should use an appropriate response code, such as 404. +Failure +responses should have a JSON object with the following structure: + +```javascript +{ + // Array of errors to display to the user. + "errors": [ + { + // The error message as a string. + "detail": "error message text" + } + ] +} +``` + +If the response has this structure Cargo will display the detailed message to the user, even if the response code is 200. +If the response code indicates an error and the content does not have this structure, Cargo will display to the user a + message intended to help debugging the server error. A server returning an `errors` object allows a registry to provide a more +detailed or user-centric error message. + +For backwards compatibility, servers should ignore any unexpected query +parameters or JSON fields. If a JSON field is missing, it should be assumed to +be null. The endpoints are versioned with the `v1` component of the path, and +Cargo is responsible for handling backwards compatibility fallbacks should any +be required in the future. + +Cargo sets the following headers for all requests: + +- `Content-Type`: `application/json` +- `Accept`: `application/json` +- `User-Agent`: The Cargo version such as `cargo 1.32.0 (8610973aa + 2019-01-02)`. This may be modified by the user in a configuration value. + Added in 1.29. + +### Publish + +- Endpoint: `/api/v1/crates/new` +- Method: PUT +- Authorization: Included + +The publish endpoint is used to publish a new version of a crate. The server +should validate the crate, make it available for download, and add it to the +index. + +The body of the data sent by Cargo is: + +- 32-bit unsigned little-endian integer of the length of JSON data. +- Metadata of the package as a JSON object. +- 32-bit unsigned little-endian integer of the length of the `.crate` file. +- The `.crate` file. + +The following is a commented example of the JSON object. Some notes of some +restrictions imposed by [crates.io] are included only to illustrate some +suggestions on types of validation that may be done, and should not be +considered as an exhaustive list of restrictions [crates.io] imposes. + +```javascript +{ + // The name of the package. + "name": "foo", + // The version of the package being published. + "vers": "0.1.0", + // Array of direct dependencies of the package. + "deps": [ + { + // Name of the dependency. + // If the dependency is renamed from the original package name, + // this is the original name. The new package name is stored in + // the `explicit_name_in_toml` field. + "name": "rand", + // The semver requirement for this dependency. + "version_req": "^0.6", + // Array of features (as strings) enabled for this dependency. + "features": ["i128_support"], + // Boolean of whether or not this is an optional dependency. + "optional": false, + // Boolean of whether or not default features are enabled. + "default_features": true, + // The target platform for the dependency. + // null if not a target dependency. + // Otherwise, a string such as "cfg(windows)". + "target": null, + // The dependency kind. + // "dev", "build", or "normal". + "kind": "normal", + // The URL of the index of the registry where this dependency is + // from as a string. If not specified or null, it is assumed the + // dependency is in the current registry. + "registry": null, + // If the dependency is renamed, this is a string of the new + // package name. If not specified or null, this dependency is not + // renamed. + "explicit_name_in_toml": null, + } + ], + // Set of features defined for the package. + // Each feature maps to an array of features or dependencies it enables. + // Cargo does not impose limitations on feature names, but crates.io + // requires alphanumeric ASCII, `_` or `-` characters. + "features": { + "extras": ["rand/simd_support"] + }, + // List of strings of the authors. + // May be empty. + "authors": ["Alice <a@example.com>"], + // Description field from the manifest. + // May be null. crates.io requires at least some content. + "description": null, + // String of the URL to the website for this package's documentation. + // May be null. + "documentation": null, + // String of the URL to the website for this package's home page. + // May be null. + "homepage": null, + // String of the content of the README file. + // May be null. + "readme": null, + // String of a relative path to a README file in the crate. + // May be null. + "readme_file": null, + // Array of strings of keywords for the package. + "keywords": [], + // Array of strings of categories for the package. + "categories": [], + // String of the license for the package. + // May be null. crates.io requires either `license` or `license_file` to be set. + "license": null, + // String of a relative path to a license file in the crate. + // May be null. + "license_file": null, + // String of the URL to the website for the source repository of this package. + // May be null. + "repository": null, + // Optional object of "status" badges. Each value is an object of + // arbitrary string to string mappings. + // crates.io has special interpretation of the format of the badges. + "badges": { + "travis-ci": { + "branch": "master", + "repository": "rust-lang/cargo" + } + }, + // The `links` string value from the package's manifest, or null if not + // specified. This field is optional and defaults to null. + "links": null +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Optional object of warnings to display to the user. + "warnings": { + // Array of strings of categories that are invalid and ignored. + "invalid_categories": [], + // Array of strings of badge names that are invalid and ignored. + "invalid_badges": [], + // Array of strings of arbitrary warnings to display to the user. + "other": [] + } +} +``` + +### Yank + +- Endpoint: `/api/v1/crates/{crate_name}/{version}/yank` +- Method: DELETE +- Authorization: Included + +The yank endpoint will set the `yank` field of the given version of a crate to +`true` in the index. + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the delete succeeded, always true. + "ok": true, +} +``` + +### Unyank + +- Endpoint: `/api/v1/crates/{crate_name}/{version}/unyank` +- Method: PUT +- Authorization: Included + +The unyank endpoint will set the `yank` field of the given version of a crate +to `false` in the index. + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the delete succeeded, always true. + "ok": true, +} +``` + +### Owners + +Cargo does not have an inherent notion of users and owners, but it does +provide the `owner` command to assist managing who has authorization to +control a crate. It is up to the registry to decide exactly how users and +owners are handled. See the [publishing documentation] for a description of +how [crates.io] handles owners via GitHub users and teams. + +#### Owners: List + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: GET +- Authorization: Included + +The owners endpoint returns a list of owners of the crate. + +A successful response includes the JSON object: + +```javascript +{ + // Array of owners of the crate. + "users": [ + { + // Unique unsigned 32-bit integer of the owner. + "id": 70, + // The unique username of the owner. + "login": "github:rust-lang:core", + // Name of the owner. + // This is optional and may be null. + "name": "Core", + } + ] +} +``` + +#### Owners: Add + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: PUT +- Authorization: Included + +A PUT request will send a request to the registry to add a new owner to a +crate. It is up to the registry how to handle the request. For example, +[crates.io] sends an invite to the user that they must accept before being +added. + +The request should include the following JSON object: + +```javascript +{ + // Array of `login` strings of owners to add. + "users": ["login_name"] +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the add succeeded, always true. + "ok": true, + // A string to be displayed to the user. + "msg": "user ehuss has been invited to be an owner of crate cargo" +} +``` + +#### Owners: Remove + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: DELETE +- Authorization: Included + +A DELETE request will remove an owner from a crate. The request should include +the following JSON object: + +```javascript +{ + // Array of `login` strings of owners to remove. + "users": ["login_name"] +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the remove succeeded, always true. + "ok": true +} +``` + +### Search + +- Endpoint: `/api/v1/crates` +- Method: GET +- Query Parameters: + - `q`: The search query string. + - `per_page`: Number of results, default 10, max 100. + +The search request will perform a search for crates, using criteria defined on +the server. + +A successful response includes the JSON object: + +```javascript +{ + // Array of results. + "crates": [ + { + // Name of the crate. + "name": "rand", + // The highest version available. + "max_version": "0.6.1", + // Textual description of the crate. + "description": "Random number generators and other randomness functionality.\n", + } + ], + "meta": { + // Total number of results available on the server. + "total": 119 + } +} +``` + +### Login + +- Endpoint: `/me` + +The "login" endpoint is not an actual API request. It exists solely for the +[`cargo login`] command to display a URL to instruct a user to visit in a web +browser to log in and retrieve an API token. + +[`cargo login`]: ../commands/cargo-login.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo publish`]: ../commands/cargo-publish.md +[alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric +[config]: config.md +[crates.io]: https://crates.io/ +[publishing documentation]: publishing.md#cargo-owner diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md new file mode 100644 index 0000000..af02d6c --- /dev/null +++ b/src/doc/src/reference/resolver.md @@ -0,0 +1,558 @@ +# Dependency Resolution + +One of Cargo's primary tasks is to determine the versions of dependencies to +use based on the version requirements specified in each package. This process +is called "dependency resolution" and is performed by the "resolver". The +result of the resolution is stored in the `Cargo.lock` file which "locks" the +dependencies to specific versions, and keeps them fixed over time. + +The resolver attempts to unify common dependencies while considering possibly +conflicting requirements. It turns out, however, that in many cases there is no +single "best" dependency resolution, and so the resolver must use heuristics to +choose a preferred solution. The sections below provide some details on how +requirements are handled, and how to work with the resolver. + +See the chapter [Specifying Dependencies] for more details about how +dependency requirements are specified. + +The [`cargo tree`] command can be used to visualize the result of the +resolver. + +[Specifying Dependencies]: specifying-dependencies.md +[`cargo tree`]: ../commands/cargo-tree.md + +## SemVer compatibility + +Cargo uses [SemVer] for specifying version numbers. This establishes a common +convention for what is compatible between different versions of a package. See +the [SemVer Compatibility] chapter for guidance on what is considered a +"compatible" change. This notion of "compatibility" is important because Cargo +assumes it should be safe to update a dependency within a compatibility range +without breaking the build. + +Versions are considered compatible if their left-most non-zero +major/minor/patch component is the same. For example, `1.0.3` and `1.1.0` are +considered compatible, and thus it should be safe to update from the older +release to the newer one. However, an update from `1.1.0` to `2.0.0` would not +be allowed to be made automatically. This convention also applies to versions +with leading zeros. For example, `0.1.0` and `0.1.2` are compatible, but +`0.1.0` and `0.2.0` are not. Similarly, `0.0.1` and `0.0.2` are not +compatible. + +As a quick refresher, the +[*version requirement* syntax][Specifying Dependencies] Cargo uses for +dependencies is: + +Requirement | Example | Equivalence | Description +------------|---------|-------------|------------- +Caret | `1.2.3` or `^1.2.3` | <code>>=1.2.3, <2.0.0</code> | Any SemVer-compatible version of at least the given value. +Tilde | `~1.2` | <code>>=1.2.0, <1.3.0</code> | Minimum version, with restricted compatibility range. +Wildcard | `1.*` | <code>>=1.0.0, <2.0.0</code> | Any version in the `*` position. +Equals | `=1.2.3` | <code>=1.2.3</code> | Exactly the specified version only. +Comparison | `>1.1` | <code>>=1.2.0</code> | Naive numeric comparison of specified digits. +Compound | <code>>=1.2, <1.5</code> | <code>>1.2.0, <1.5.0</code> | Multiple requirements that must be simultaneously satisfied. + +When multiple packages specify a dependency for a common package, the resolver +attempts to ensure that they use the same version of that common package, as +long as they are within a SemVer compatibility range. It also attempts to use +the greatest version currently available within that compatibility range. For +example, if there are two packages in the resolve graph with the following +requirements: + +```toml +# Package A +[dependencies] +bitflags = "1.0" + +# Package B +[dependencies] +bitflags = "1.1" +``` + +If at the time the `Cargo.lock` file is generated, the greatest version of +`bitflags` is `1.2.1`, then both packages will use `1.2.1` because it is the +greatest within the compatibility range. If `2.0.0` is published, it will +still use `1.2.1` because `2.0.0` is considered incompatible. + +If multiple packages have a common dependency with semver-incompatible +versions, then Cargo will allow this, but will build two separate copies of +the dependency. For example: + +```toml +# Package A +[dependencies] +rand = "0.7" + +# Package B +[dependencies] +rand = "0.6" +``` + +The above will result in Package A using the greatest `0.7` release (`0.7.3` +at the time of this writing) and Package B will use the greatest `0.6` release +(`0.6.5` for example). This can lead to potential problems, see the +[Version-incompatibility hazards] section for more details. + +Multiple versions within the same compatibility range are not allowed and will +result in a resolver error if it is constrained to two different versions +within a compatibility range. For example, if there are two packages in the +resolve graph with the following requirements: + +```toml +# Package A +[dependencies] +log = "=0.4.11" + +# Package B +[dependencies] +log = "=0.4.8" +``` + +The above will fail because it is not allowed to have two separate copies of +the `0.4` release of the `log` package. + +[SemVer]: https://semver.org/ +[SemVer Compatibility]: semver.md +[Version-incompatibility hazards]: #version-incompatibility-hazards + +### Version-incompatibility hazards + +When multiple versions of a crate appear in the resolve graph, this can cause +problems when types from those crates are exposed by the crates using them. +This is because the types and items are considered different by the Rust +compiler, even if they have the same name. Libraries should take care when +publishing a SemVer-incompatible version (for example, publishing `2.0.0` +after `1.0.0` has been in use), particularly for libraries that are widely +used. + +The "[semver trick]" is a workaround for this problem of publishing a breaking +change while retaining compatibility with older versions. The linked page goes +into detail about what the problem is and how to address it. In short, when a +library wants to publish a SemVer-breaking release, publish the new release, +and also publish a point release of the previous version that reexports the +types from the newer version. + +These incompatibilities usually manifest as a compile-time error, but +sometimes they will only appear as a runtime misbehavior. For example, let's +say there is a common library named `foo` that ends up appearing with both +version `1.0.0` and `2.0.0` in the resolve graph. If [`downcast_ref`] is used +on a object created by a library using version `1.0.0`, and the code calling +`downcast_ref` is downcasting to a type from version `2.0.0`, the downcast +will fail at runtime. + +It is important to make sure that if you have multiple versions of a library +that you are properly using them, especially if it is ever possible for the +types from different versions to be used together. The [`cargo tree +-d`][`cargo tree`] command can be used to identify duplicate versions and +where they come from. Similarly, it is important to consider the impact on the +ecosystem if you publish a SemVer-incompatible version of a popular library. + +[semver trick]: https://github.com/dtolnay/semver-trick +[`downcast_ref`]: ../../std/any/trait.Any.html#method.downcast_ref + +### Pre-releases + +SemVer has the concept of "pre-releases" with a dash in the version, such as +`1.0.0-alpha`, or `1.0.0-beta`. Cargo will avoid automatically using +pre-releases unless explicitly asked. For example, if `1.0.0-alpha` of package +`foo` is published, then a requirement of `foo = "1.0"` will *not* match, and +will return an error. The pre-release must be specified, such as `foo = +"1.0.0-alpha"`. Similarly [`cargo install`] will avoid pre-releases unless +explicitly asked to install one. + +Cargo allows "newer" pre-releases to be used automatically. For example, if +`1.0.0-beta` is published, then a requirement `foo = "1.0.0-alpha"` will allow +updating to the `beta` version. Beware that pre-release versions can be +unstable, and as such care should be taken when using them. Some projects may +choose to publish breaking changes between pre-release versions. It is +recommended to not use pre-release dependencies in a library if your library +is not also a pre-release. Care should also be taken when updating your +`Cargo.lock`, and be prepared if a pre-release update causes issues. + +The pre-release tag may be separated with periods to distinguish separate +components. Numeric components will use numeric comparison. For example, +`1.0.0-alpha.4` will use numeric comparison for the `4` component. That means +that if `1.0.0-alpha.11` is published, that will be chosen as the greatest +release. Non-numeric components are compared lexicographically. + +[`cargo install`]: ../commands/cargo-install.md + +### Version metadata + +SemVer has the concept of "version metadata" with a plus in the version, such +as `1.0.0+21AF26D3`. This metadata is usually ignored, and should not be used +in a version requirement. You should never publish multiple versions that +differ only in the metadata tag (note, this is a [known issue] with +[crates.io] that currently permits this). + +[known issue]: https://github.com/rust-lang/crates.io/issues/1059 +[crates.io]: https://crates.io/ + +## Other constraints + +Version requirements aren't the only constraint that the resolver considers +when selecting and unifying dependencies. The following sections cover some of +the other constraints that can affect resolution. + +### Features + +For the purpose of generating `Cargo.lock`, the resolver builds the dependency +graph as-if all [features] of all [workspace] members are enabled. This +ensures that any optional dependencies are available and properly resolved +with the rest of the graph when features are added or removed with the +[`--features` command-line flag](features.md#command-line-feature-options). +The resolver runs a second time to determine the actual features used when +*compiling* a crate, based on the features selected on the command-line. + +Dependencies are resolved with the union of all features enabled on them. For +example, if one package depends on the [`im`] package with the [`serde` +dependency] enabled and another package depends on it with the [`rayon` +dependency] enabled, then `im` will be built with both features enabled, and +the `serde` and `rayon` crates will be included in the resolve graph. If no +packages depend on `im` with those features, then those optional dependencies +will be ignored, and they will not affect resolution. + +When building multiple packages in a workspace (such as with `--workspace` or +multiple `-p` flags), the features of the dependencies of all of those +packages are unified. If you have a circumstance where you want to avoid that +unification for different workspace members, you will need to build them via +separate `cargo` invocations. + +The resolver will skip over versions of packages that are missing required +features. For example, if a package depends on version `^1` of [`regex`] with +the [`perf` feature], then the oldest version it can select is `1.3.0`, +because versions prior to that did not contain the `perf` feature. Similarly, +if a feature is removed from a new release, then packages that require that +feature will be stuck on the older releases that contain that feature. It is +discouraged to remove features in a SemVer-compatible release. Beware that +optional dependencies also define an implicit feature, so removing an optional +dependency or making it non-optional can cause problems, see [removing an +optional dependency]. + +[`im`]: https://crates.io/crates/im +[`perf` feature]: https://github.com/rust-lang/regex/blob/1.3.0/Cargo.toml#L56 +[`rayon` dependency]: https://github.com/bodil/im-rs/blob/v15.0.0/Cargo.toml#L47 +[`regex`]: https://crates.io/crates/regex +[`serde` dependency]: https://github.com/bodil/im-rs/blob/v15.0.0/Cargo.toml#L46 +[features]: features.md +[removing an optional dependency]: semver.md#cargo-remove-opt-dep +[workspace]: workspaces.md + +#### Feature resolver version 2 + +When `resolver = "2"` is specified in `Cargo.toml` (see [resolver +versions](#resolver-versions) below), a different feature resolver is used +which uses a different algorithm for unifying features. The version `"1"` +resolver will unify features for a package no matter where it is specified. +The version `"2"` resolver will avoid unifying features in the following +situations: + +* Features for target-specific dependencies are not enabled if the target is + not currently being built. For example: + + ```toml + [dependencies.common] + version = "1.0" + features = ["f1"] + + [target.'cfg(windows)'.dependencies.common] + version = "1.0" + features = ["f2"] + ``` + + When building this example for a non-Windows platform, the `f2` feature will + *not* be enabled. + +* Features enabled on [build-dependencies] or proc-macros will not be unified + when those same dependencies are used as a normal dependency. For example: + + ```toml + [dependencies] + log = "0.4" + + [build-dependencies] + log = {version = "0.4", features=['std']} + ``` + + When building the build script, the `log` crate will be built with the `std` + feature. When building the library of your package, it will not enable the + feature. + +* Features enabled on [dev-dependencies] will not be unified when those same + dependencies are used as a normal dependency, unless those dev-dependencies + are currently being built. For example: + + ```toml + [dependencies] + serde = {version = "1.0", default-features = false} + + [dev-dependencies] + serde = {version = "1.0", features = ["std"]} + ``` + + In this example, the library will normally link against `serde` without the + `std` feature. However, when built as a test or example, it will include the + `std` feature. For example, `cargo test` or `cargo build --all-targets` will + unify these features. Note that dev-dependencies in dependencies are always + ignored, this is only relevant for the top-level package or workspace + members. + +[build-dependencies]: specifying-dependencies.md#build-dependencies +[dev-dependencies]: specifying-dependencies.md#development-dependencies +[resolver-field]: features.md#resolver-versions + +### `links` + +The [`links` field] is used to ensure only one copy of a native library is +linked into a binary. The resolver will attempt to find a graph where there is +only one instance of each `links` name. If it is unable to find a graph that +satisfies that constraint, it will return an error. + +For example, it is an error if one package depends on [`libgit2-sys`] version +`0.11` and another depends on `0.12`, because Cargo is unable to unify those, +but they both link to the `git2` native library. Due to this requirement, it +is encouraged to be very careful when making SemVer-incompatible releases with +the `links` field if your library is in common use. + +[`links` field]: manifest.md#the-links-field +[`libgit2-sys`]: https://crates.io/crates/libgit2-sys + +### Yanked versions + +[Yanked releases][yank] are those that are marked that they should not be +used. When the resolver is building the graph, it will ignore all yanked +releases unless they already exist in the `Cargo.lock` file. + +[yank]: publishing.md#cargo-yank + +## Dependency updates + +Dependency resolution is automatically performed by all Cargo commands that +need to know about the dependency graph. For example, [`cargo build`] will run +the resolver to discover all the dependencies to build. After the first time +it runs, the result is stored in the `Cargo.lock` file. Subsequent commands +will run the resolver, keeping dependencies locked to the versions in +`Cargo.lock` *if it can*. + +If the dependency list in `Cargo.toml` has been modified, for example changing +the version of a dependency from `1.0` to `2.0`, then the resolver will select +a new version for that dependency that matches the new requirements. If that +new dependency introduces new requirements, those new requirements may also +trigger additional updates. The `Cargo.lock` file will be updated with the new +result. The `--locked` or `--frozen` flags can be used to change this behavior +to prevent automatic updates when requirements change, and return an error +instead. + +[`cargo update`] can be used to update the entries in `Cargo.lock` when new +versions are published. Without any options, it will attempt to update all +packages in the lock file. The `-p` flag can be used to target the update for +a specific package, and other flags such as `--aggressive` or `--precise` can +be used to control how versions are selected. + +[`cargo build`]: ../commands/cargo-build.md +[`cargo update`]: ../commands/cargo-update.md + +## Overrides + +Cargo has several mechanisms to override dependencies within the graph. The +[Overriding Dependencies] chapter goes into detail on how to use overrides. +The overrides appear as an overlay to a registry, replacing the patched +version with the new entry. Otherwise, resolution is performed like normal. + +[Overriding Dependencies]: overriding-dependencies.md + +## Dependency kinds + +There are three kinds of dependencies in a package: normal, [build], and +[dev][dev-dependencies]. For the most part these are all treated the same from +the perspective of the resolver. One difference is that dev-dependencies for +non-workspace members are always ignored, and do not influence resolution. + +[Platform-specific dependencies] with the `[target]` table are resolved as-if +all platforms are enabled. In other words, the resolver ignores the platform +or `cfg` expression. + +[build]: specifying-dependencies.md#build-dependencies +[dev-dependencies]: specifying-dependencies.md#development-dependencies +[Platform-specific dependencies]: specifying-dependencies.md#platform-specific-dependencies + +### dev-dependency cycles + +Usually the resolver does not allow cycles in the graph, but it does allow +them for [dev-dependencies]. For example, project "foo" has a dev-dependency +on "bar", which has a normal dependency on "foo" (usually as a "path" +dependency). This is allowed because there isn't really a cycle from the +perspective of the build artifacts. In this example, the "foo" library is +built (which does not need "bar" because "bar" is only used for tests), and +then "bar" can be built depending on "foo", then the "foo" tests can be built +linking to "bar". + +Beware that this can lead to confusing errors. In the case of building library +unit tests, there are actually two copies of the library linked into the final +test binary: the one that was linked with "bar", and the one built that +contains the unit tests. Similar to the issues highlighted in the +[Version-incompatibility hazards] section, the types between the two are not +compatible. Be careful when exposing types of "foo" from "bar" in this +situation, since the "foo" unit tests won't treat them the same as the local +types. + +If possible, try to split your package into multiple packages and restructure +it so that it remains strictly acyclic. + +## Resolver versions + +A different feature resolver algorithm can be used by specifying the resolver +version in `Cargo.toml` like this: + +```toml +[package] +name = "my-package" +version = "1.0.0" +resolver = "2" +``` + +The version `"1"` resolver is the original resolver that shipped with Cargo up to version 1.50. +The default is `"2"` if the root package specifies [`edition = "2021"`](manifest.md#the-edition-field) or a newer edition. +Otherwise the default is `"1"`. + +The version `"2"` resolver introduces changes in [feature +unification](#features). See the [features chapter][features-2] for more +details. + +The resolver is a global option that affects the entire workspace. The +`resolver` version in dependencies is ignored, only the value in the top-level +package will be used. If using a [virtual workspace], the version should be +specified in the `[workspace]` table, for example: + +```toml +[workspace] +members = ["member1", "member2"] +resolver = "2" +``` + +[virtual workspace]: workspaces.md#virtual-workspace +[features-2]: features.md#feature-resolver-version-2 + +## Recommendations + +The following are some recommendations for setting the version within your +package, and for specifying dependency requirements. These are general +guidelines that should apply to common situations, but of course some +situations may require specifying unusual requirements. + +* Follow the [SemVer guidelines] when deciding how to update your version + number, and whether or not you will need to make a SemVer-incompatible + version change. +* Use caret requirements for dependencies, such as `"1.2.3"`, for most + situations. This ensures that the resolver can be maximally flexible in + choosing a version while maintaining build compatibility. + * Specify all three components with the version you are currently using. + This helps set the minimum version that will be used, and ensures that + other users won't end up with an older version of the dependency that + might be missing something that your package requires. + * Avoid `*` requirements, as they are not allowed on [crates.io], and they + can pull in SemVer-breaking changes during a normal `cargo update`. + * Avoid overly broad version requirements. For example, `>=2.0.0` can pull + in any SemVer-incompatible version, like version `5.0.0`, which can result + in broken builds in the future. + * Avoid overly narrow version requirements if possible. For example, if you + specify a tilde requirement like `bar="~1.3"`, and another package + specifies a requirement of `bar="1.4"`, this will fail to resolve, even + though minor releases should be compatible. +* Try to keep the dependency versions up-to-date with the actual minimum + versions that your library requires. For example, if you have a requirement + of `bar="1.0.12"`, and then in a future release you start using new features + added in the `1.1.0` release of "bar", update your dependency requirement to + `bar="1.1.0"`. + + If you fail to do this, it may not be immediately obvious because Cargo can + opportunistically choose the newest version when you run a blanket `cargo + update`. However, if another user depends on your library, and runs `cargo + update -p your-library`, it will *not* automatically update "bar" if it is + locked in their `Cargo.lock`. It will only update "bar" in that situation if + the dependency declaration is also updated. Failure to do so can cause + confusing build errors for the user using `cargo update -p`. +* If two packages are tightly coupled, then an `=` dependency requirement may + help ensure that they stay in sync. For example, a library with a companion + proc-macro library will sometimes make assumptions between the two libraries + that won't work well if the two are out of sync (and it is never expected to + use the two libraries independently). The parent library can use an `=` + requirement on the proc-macro, and re-export the macros for easy access. +* `0.0.x` versions can be used for packages that are permanently unstable. + +In general, the stricter you make the dependency requirements, the more likely +it will be for the resolver to fail. Conversely, if you use requirements that +are too loose, it may be possible for new versions to be published that will +break the build. + +[SemVer guidelines]: semver.md + +## Troubleshooting + +The following illustrates some problems you may experience, and some possible +solutions. + +### Unexpected dependency duplication + +The resolver algorithm may converge on a solution that includes two copies of a +dependency when one would suffice. For example: + +```toml +# Package A +[dependencies] +rand = "0.7" + +# Package B +[dependencies] +rand = ">=0.6" # note: open requirements such as this are discouraged +``` + +In this example, Cargo may build two copies of the `rand` crate, even though a +single copy at version `0.7.3` would meet all requirements. This is because the +resolver's algorithm favors building the latest available version of `rand` for +Package B, which is `0.8.5` at the time of this writing, and that is +incompatible with Package A's specification. The resolver's algorithm does not +currently attempt to "deduplicate" in this situation. + +The use of open-ended version requirements like `>=0.6` is discouraged in Cargo. +But, if you run into this situation, the [`cargo update`] command with the +`--precise` flag can be used to manually remove such duplications. + +[`cargo update`]: ../commands/cargo-update.md + + +### SemVer-breaking patch release breaks the build + +Sometimes a project may inadvertently publish a point release with a +SemVer-breaking change. When users update with `cargo update`, they will pick +up this new release, and then their build may break. In this situation, it is +recommended that the project should [yank] the release, and either remove the +SemVer-breaking change, or publish it as a new SemVer-major version increase. + +If the change happened in a third-party project, if possible try to +(politely!) work with the project to resolve the issue. + +While waiting for the release to be yanked, some workarounds depend on the +circumstances: + +* If your project is the end product (such as a binary executable), just avoid + updating the offending package in `Cargo.lock`. This can be done with the + `--precise` flag in [`cargo update`]. +* If you publish a binary on [crates.io], then you can temporarily add an `=` + requirement to force the dependency to a specific good version. + * Binary projects can alternatively recommend users to use the `--locked` + flag with [`cargo install`] to use the original `Cargo.lock` that contains + the known good version. +* Libraries may also consider publishing a temporary new release with stricter + requirements that avoid the troublesome dependency. You may want to consider + using range requirements (instead of `=`) to avoid overly-strict + requirements that may conflict with other packages using the same + dependency. Once the problem has been resolved, you can publish another + point release that relaxes the dependency back to a caret requirement. +* If it looks like the third-party project is unable or unwilling to yank the + release, then one option is to update your code to be compatible with the + changes, and update the dependency requirement to set the minimum version to + the new release. You will also need to consider if this is a SemVer-breaking + change of your own library, for example if it exposes types from the + dependency. + diff --git a/src/doc/src/reference/running-a-registry.md b/src/doc/src/reference/running-a-registry.md new file mode 100644 index 0000000..144f1ee --- /dev/null +++ b/src/doc/src/reference/running-a-registry.md @@ -0,0 +1,20 @@ +## Running a Registry + +A minimal registry can be implemented by having a git repository that contains +an index, and a server that contains the compressed `.crate` files created by +[`cargo package`]. Users won't be able to use Cargo to publish to it, but this +may be sufficient for closed environments. The index format is described in +[Registry Index]. + +A full-featured registry that supports publishing will additionally need to +have a web API service that conforms to the API used by Cargo. The web API is +described in [Registry Web API]. + +Commercial and community projects are available for building and running a +registry. See <https://github.com/rust-lang/cargo/wiki/Third-party-registries> +for a list of what is available. + +[Registry Web API]: registry-web-api.md +[Registry Index]: registry-index.md +[`cargo publish`]: ../commands/cargo-publish.md +[`cargo package`]: ../commands/cargo-package.md diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md new file mode 100644 index 0000000..22c4261 --- /dev/null +++ b/src/doc/src/reference/semver.md @@ -0,0 +1,1404 @@ +# SemVer Compatibility + +This chapter provides details on what is conventionally considered a +compatible or breaking SemVer change for new releases of a package. See the +[SemVer compatibility] section for details on what SemVer is, and how Cargo +uses it to ensure compatibility of libraries. + +These are only *guidelines*, and not necessarily hard-and-fast rules that all +projects will obey. The [Change categories] section details how this guide +classifies the level and severity of a change. Most of this guide focuses on +changes that will cause `cargo` and `rustc` to fail to build something that +previously worked. Almost every change carries some risk that it will +negatively affect the runtime behavior, and for those cases it is usually a +judgment call by the project maintainers whether or not it is a +SemVer-incompatible change. + +See also [rust-semverver], which is an experimental tool that attempts to +programmatically check compatibility rules. + +[Change categories]: #change-categories +[rust-semverver]: https://github.com/rust-lang/rust-semverver +[SemVer compatibility]: resolver.md#semver-compatibility + +## Change categories + +All of the policies listed below are categorized by the level of change: + +* **Major change**: a change that requires a major SemVer bump. +* **Minor change**: a change that requires only a minor SemVer bump. +* **Possibly-breaking change**: a change that some projects may consider major + and others consider minor. + +The "Possibly-breaking" category covers changes that have the *potential* to +break during an update, but may not necessarily cause a breakage. The impact +of these changes should be considered carefully. The exact nature will depend +on the change and the principles of the project maintainers. + +Some projects may choose to only bump the patch number on a minor change. It +is encouraged to follow the SemVer spec, and only apply bug fixes in patch +releases. However, a bug fix may require an API change that is marked as a +"minor change", and shouldn't affect compatibility. This guide does not take a +stance on how each individual "minor change" should be treated, as the +difference between minor and patch changes are conventions that depend on the +nature of the change. + +Some changes are marked as "minor", even though they carry the potential risk +of breaking a build. This is for situations where the potential is extremely +low, and the potentially breaking code is unlikely to be written in idiomatic +Rust, or is specifically discouraged from use. + +This guide uses the terms "major" and "minor" assuming this relates to a +"1.0.0" release or later. Initial development releases starting with "0.y.z" +can treat changes in "y" as a major release, and "z" as a minor release. +"0.0.z" releases are always major changes. This is because Cargo uses the +convention that only changes in the left-most non-zero component are +considered incompatible. + +* API compatibility + * Items + * [Major: renaming/moving/removing any public items](#item-remove) + * [Minor: adding new public items](#item-new) + * Structs + * [Major: adding a private struct field when all current fields are public](#struct-add-private-field-when-public) + * [Major: adding a public field when no private field exists](#struct-add-public-field-when-no-private) + * [Minor: adding or removing private fields when at least one already exists](#struct-private-fields-with-private) + * [Minor: going from a tuple struct with all private fields (with at least one field) to a normal struct, or vice versa](#struct-tuple-normal-with-private) + * Enums + * [Major: adding new enum variants (without `non_exhaustive`)](#enum-variant-new) + * [Major: adding new fields to an enum variant](#enum-fields-new) + * Traits + * [Major: adding a non-defaulted trait item](#trait-new-item-no-default) + * [Major: any change to trait item signatures](#trait-item-signature) + * [Possibly-breaking: adding a defaulted trait item](#trait-new-default-item) + * [Major: adding a trait item that makes the trait non-object safe](#trait-object-safety) + * [Major: adding a type parameter without a default](#trait-new-parameter-no-default) + * [Minor: adding a defaulted trait type parameter](#trait-new-parameter-default) + * Implementations + * [Possibly-breaking change: adding any inherent items](#impl-item-new) + * Generics + * [Major: tightening generic bounds](#generic-bounds-tighten) + * [Minor: loosening generic bounds](#generic-bounds-loosen) + * [Minor: adding defaulted type parameters](#generic-new-default) + * [Minor: generalizing a type to use generics (with identical types)](#generic-generalize-identical) + * [Major: generalizing a type to use generics (with possibly different types)](#generic-generalize-different) + * [Minor: changing a generic type to a more generic type](#generic-more-generic) + * Functions + * [Major: adding/removing function parameters](#fn-change-arity) + * [Possibly-breaking: introducing a new function type parameter](#fn-generic-new) + * [Minor: generalizing a function to use generics (supporting original type)](#fn-generalize-compatible) + * [Major: generalizing a function to use generics with type mismatch](#fn-generalize-mismatch) + * Attributes + * [Major: switching from `no_std` support to requiring `std`](#attr-no-std-to-std) +* Tooling and environment compatibility + * [Possibly-breaking: changing the minimum version of Rust required](#env-new-rust) + * [Possibly-breaking: changing the platform and environment requirements](#env-change-requirements) + * [Minor: introducing new lints](#new-lints) + * Cargo + * [Minor: adding a new Cargo feature](#cargo-feature-add) + * [Major: removing a Cargo feature](#cargo-feature-remove) + * [Major: removing a feature from a feature list if that changes functionality or public items](#cargo-feature-remove-another) + * [Possibly-breaking: removing an optional dependency](#cargo-remove-opt-dep) + * [Minor: changing dependency features](#cargo-change-dep-feature) + * [Minor: adding dependencies](#cargo-dep-add) +* [Application compatibility](#application-compatibility) + +## API compatibility + +All of the examples below contain three parts: the original code, the code +after it has been modified, and an example usage of the code that could appear +in another project. In a minor change, the example usage should successfully +build with both the before and after versions. + +<a id="item-remove"></a> +### Major: renaming/moving/removing any public items + +The absence of a publicly exposed [item][items] will cause any uses of that item to +fail to compile. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// After +// ... item has been removed + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + updated_crate::foo(); // Error: cannot find function `foo` +} +``` + +This includes adding any sort of [`cfg` attribute] which can change which +items or behavior is available based on [conditional compilation]. + +Mitigating strategies: +* Mark items to be removed as [deprecated], and then remove them at a later + date in a SemVer-breaking release. +* Mark renamed items as [deprecated], and use a [`pub use`] item to re-export + to the old name. + +<a id="item-new"></a> +### Minor: adding new public items + +Adding new, public [items] is a minor change. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +// ... absence of item + +/////////////////////////////////////////////////////////// +// After +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +// `foo` is not used since it didn't previously exist. +``` + +Note that in some rare cases this can be a **breaking change** due to glob +imports. For example, if you add a new trait, and a project has used a glob +import that brings that trait into scope, and the new trait introduces an +associated item that conflicts with any types it is implemented on, this can +cause a compile-time error due to the ambiguity. Example: + +```rust,ignore +// Breaking change example + +/////////////////////////////////////////////////////////// +// Before +// ... absence of trait + +/////////////////////////////////////////////////////////// +// After +pub trait NewTrait { + fn foo(&self) {} +} + +impl NewTrait for i32 {} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::*; + +pub trait LocalTrait { + fn foo(&self) {} +} + +impl LocalTrait for i32 {} + +fn main() { + 123i32.foo(); // Error: multiple applicable items in scope +} +``` + +This is not considered a major change because conventionally glob imports are +a known forwards-compatibility hazard. Glob imports of items from external +crates should be avoided. + +<a id="struct-add-private-field-when-public"></a> +### Major: adding a private struct field when all current fields are public + +When a private field is added to a struct that previously had all public fields, +this will break any code that attempts to construct it with a [struct literal]. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo { + pub f1: i32, +} + +/////////////////////////////////////////////////////////// +// After +pub struct Foo { + pub f1: i32, + f2: i32, +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + let x = updated_crate::Foo { f1: 123 }; // Error: cannot construct `Foo` +} +``` + +Mitigation strategies: +* Do not add new fields to all-public field structs. +* Mark structs as [`#[non_exhaustive]`][non_exhaustive] when first introducing + a struct to prevent users from using struct literal syntax, and instead + provide a constructor method and/or [Default] implementation. + +<a id="struct-add-public-field-when-no-private"></a> +### Major: adding a public field when no private field exists + +When a public field is added to a struct that has all public fields, this will +break any code that attempts to construct it with a [struct literal]. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo { + pub f1: i32, +} + +/////////////////////////////////////////////////////////// +// After +pub struct Foo { + pub f1: i32, + pub f2: i32, +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + let x = updated_crate::Foo { f1: 123 }; // Error: missing field `f2` +} +``` + +Mitigation strategies: +* Do not add new new fields to all-public field structs. +* Mark structs as [`#[non_exhaustive]`][non_exhaustive] when first introducing + a struct to prevent users from using struct literal syntax, and instead + provide a constructor method and/or [Default] implementation. + +<a id="struct-private-fields-with-private"></a> +### Minor: adding or removing private fields when at least one already exists + +It is safe to add or remove private fields from a struct when the struct +already has at least one private field. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +#[derive(Default)] +pub struct Foo { + f1: i32, +} + +/////////////////////////////////////////////////////////// +// After +#[derive(Default)] +pub struct Foo { + f2: f64, +} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +fn main() { + // Cannot access private fields. + let x = updated_crate::Foo::default(); +} +``` + +This is safe because existing code cannot use a [struct literal] to construct +it, nor exhaustively match its contents. + +Note that for tuple structs, this is a **major change** if the tuple contains +public fields, and the addition or removal of a private field changes the +index of any public field. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +#[derive(Default)] +pub struct Foo(pub i32, i32); + +/////////////////////////////////////////////////////////// +// After +#[derive(Default)] +pub struct Foo(f64, pub i32, i32); + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + let x = updated_crate::Foo::default(); + let y = x.0; // Error: is private +} +``` + +<a id="struct-tuple-normal-with-private"></a> +### Minor: going from a tuple struct with all private fields (with at least one field) to a normal struct, or vice versa + +Changing a tuple struct to a normal struct (or vice-versa) is safe if all +fields are private. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +#[derive(Default)] +pub struct Foo(i32); + +/////////////////////////////////////////////////////////// +// After +#[derive(Default)] +pub struct Foo { + f1: i32, +} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +fn main() { + // Cannot access private fields. + let x = updated_crate::Foo::default(); +} +``` + +This is safe because existing code cannot use a [struct literal] to construct +it, nor match its contents. + +<a id="enum-variant-new"></a> +### Major: adding new enum variants (without `non_exhaustive`) + +It is a breaking change to add a new enum variant if the enum does not use the +[`#[non_exhaustive]`][non_exhaustive] attribute. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub enum E { + Variant1, +} + +/////////////////////////////////////////////////////////// +// After +pub enum E { + Variant1, + Variant2, +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + use updated_crate::E; + let x = E::Variant1; + match x { // Error: `E::Variant2` not covered + E::Variant1 => {} + } +} +``` + +Mitigation strategies: +* When introducing the enum, mark it as [`#[non_exhaustive]`][non_exhaustive] + to force users to use [wildcard patterns] to catch new variants. + +<a id="enum-fields-new"></a> +### Major: adding new fields to an enum variant + +It is a breaking change to add new fields to an enum variant because all +fields are public, and constructors and matching will fail to compile. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub enum E { + Variant1 { f1: i32 }, +} + +/////////////////////////////////////////////////////////// +// After +pub enum E { + Variant1 { f1: i32, f2: i32 }, +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + use updated_crate::E; + let x = E::Variant1 { f1: 1 }; // Error: missing f2 + match x { + E::Variant1 { f1 } => {} // Error: missing f2 + } +} +``` + +Mitigation strategies: +* When introducing the enum, mark the variant as [`non_exhaustive`][non_exhaustive] + so that it cannot be constructed or matched without wildcards. + ```rust,ignore,skip + pub enum E { + #[non_exhaustive] + Variant1{f1: i32} + } + ``` +* When introducing the enum, use an explicit struct as a value, where you can + have control over the field visibility. + ```rust,ignore,skip + pub struct Foo { + f1: i32, + f2: i32, + } + pub enum E { + Variant1(Foo) + } + ``` + +<a id="trait-new-item-no-default"></a> +### Major: adding a non-defaulted trait item + +It is a breaking change to add a non-defaulted item to a trait. This will +break any implementors of the trait. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait { + fn foo(&self); +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Trait; +struct Foo; + +impl Trait for Foo {} // Error: not all trait items implemented +``` + +Mitigation strategies: +* Always provide a default implementation or value for new associated trait + items. +* When introducing the trait, use the [sealed trait] technique to prevent + users outside of the crate from implementing the trait. + +<a id="trait-item-signature"></a> +### Major: any change to trait item signatures + +It is a breaking change to make any change to a trait item signature. This can +break external implementors of the trait. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait { + fn f(&self, x: i32) {} +} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait { + // For sealed traits or normal functions, this would be a minor change + // because generalizing with generics strictly expands the possible uses. + // But in this case, trait implementations must use the same signature. + fn f<V>(&self, x: V) {} +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Trait; +struct Foo; + +impl Trait for Foo { + fn f(&self, x: i32) {} // Error: trait declaration has 1 type parameter +} +``` + +Mitigation strategies: +* Introduce new items with default implementations to cover the new + functionality instead of modifying existing items. +* When introducing the trait, use the [sealed trait] technique to prevent + users outside of the crate from implementing the trait. + +<a id="trait-new-default-item"></a> +### Possibly-breaking: adding a defaulted trait item + +It is usually safe to add a defaulted trait item. However, this can sometimes +cause a compile error. For example, this can introduce an ambiguity if a +method of the same name exists in another trait. + +```rust,ignore +// Breaking change example + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait { + fn foo(&self) {} +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Trait; +struct Foo; + +trait LocalTrait { + fn foo(&self) {} +} + +impl Trait for Foo {} +impl LocalTrait for Foo {} + +fn main() { + let x = Foo; + x.foo(); // Error: multiple applicable items in scope +} +``` + +Note that this ambiguity does *not* exist for name collisions on [inherent +implementations], as they take priority over trait items. + +See [trait-object-safety](#trait-object-safety) for a special case to consider +when adding trait items. + +Mitigation strategies: +* Some projects may deem this acceptable breakage, particularly if the new + item name is unlikely to collide with any existing code. Choose names + carefully to help avoid these collisions. Additionally, it may be acceptable + to require downstream users to add [disambiguation syntax] to select the + correct function when updating the dependency. + +<a id="trait-object-safety"></a> +### Major: adding a trait item that makes the trait non-object safe + +It is a breaking change to add a trait item that changes the trait to not be +[object safe]. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait { + // An associated const makes the trait not object-safe. + const CONST: i32 = 123; +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Trait; +struct Foo; + +impl Trait for Foo {} + +fn main() { + let obj: Box<dyn Trait> = Box::new(Foo); // Error: cannot be made into an object +} +``` + +It is safe to do the converse (making a non-object safe trait into a safe +one). + +<a id="trait-new-parameter-no-default"></a> +### Major: adding a type parameter without a default + +It is a breaking change to add a type parameter without a default to a trait. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait<T> {} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Trait; +struct Foo; + +impl Trait for Foo {} // Error: missing generics +``` + +Mitigating strategies: +* See [adding a defaulted trait type parameter](#trait-new-parameter-default). + +<a id="trait-new-parameter-default"></a> +### Minor: adding a defaulted trait type parameter + +It is safe to add a type parameter to a trait as long as it has a default. +External implementors will use the default without needing to specify the +parameter. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait<T = i32> {} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::Trait; +struct Foo; + +impl Trait for Foo {} +``` + +<a id="impl-item-new"></a> +### Possibly-breaking change: adding any inherent items + +Usually adding inherent items to an implementation should be safe because +inherent items take priority over trait items. However, in some cases the +collision can cause problems if the name is the same as an implemented trait +item with a different signature. + +```rust,ignore +// Breaking change example + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo; + +/////////////////////////////////////////////////////////// +// After +pub struct Foo; + +impl Foo { + pub fn foo(&self) {} +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Foo; + +trait Trait { + fn foo(&self, x: i32) {} +} + +impl Trait for Foo {} + +fn main() { + let x = Foo; + x.foo(1); // Error: this method takes 0 arguments but 1 argument was supplied +} +``` + +Note that if the signatures match, there would not be a compile-time error, +but possibly a silent change in runtime behavior (because it is now executing +a different function). + +Mitigation strategies: +* Some projects may deem this acceptable breakage, particularly if the new + item name is unlikely to collide with any existing code. Choose names + carefully to help avoid these collisions. Additionally, it may be acceptable + to require downstream users to add [disambiguation syntax] to select the + correct function when updating the dependency. + +<a id="generic-bounds-tighten"></a> +### Major: tightening generic bounds + +It is a breaking change to tighten generic bounds on a type since this can +break users expecting the looser bounds. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo<A> { + pub f1: A, +} + +/////////////////////////////////////////////////////////// +// After +pub struct Foo<A: Eq> { + pub f1: A, +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Foo; + +fn main() { + let s = Foo { f1: 1.23 }; // Error: the trait bound `{float}: Eq` is not satisfied +} +``` + +<a id="generic-bounds-loosen"></a> +### Minor: loosening generic bounds + +It is safe to loosen the generic bounds on a type, as it only expands what is +allowed. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo<A: Clone> { + pub f1: A, +} + +/////////////////////////////////////////////////////////// +// After +pub struct Foo<A> { + pub f1: A, +} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::Foo; + +fn main() { + let s = Foo { f1: 123 }; +} +``` + +<a id="generic-new-default"></a> +### Minor: adding defaulted type parameters + +It is safe to add a type parameter to a type as long as it has a default. All +existing references will use the default without needing to specify the +parameter. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +#[derive(Default)] +pub struct Foo {} + +/////////////////////////////////////////////////////////// +// After +#[derive(Default)] +pub struct Foo<A = i32> { + f1: A, +} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::Foo; + +fn main() { + let s: Foo = Default::default(); +} +``` + +<a id="generic-generalize-identical"></a> +### Minor: generalizing a type to use generics (with identical types) + +A struct or enum field can change from a concrete type to a generic type +parameter, provided that the change results in an identical type for all +existing use cases. For example, the following change is permitted: + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo(pub u8); + +/////////////////////////////////////////////////////////// +// After +pub struct Foo<T = u8>(pub T); + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::Foo; + +fn main() { + let s: Foo = Foo(123); +} +``` + +because existing uses of `Foo` are shorthand for `Foo<u8>` which yields the +identical field type. + +<a id="generic-generalize-different"></a> +### Major: generalizing a type to use generics (with possibly different types) + +Changing a struct or enum field from a concrete type to a generic type +parameter can break if the type can change. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo<T = u8>(pub T, pub u8); + +/////////////////////////////////////////////////////////// +// After +pub struct Foo<T = u8>(pub T, pub T); + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::Foo; + +fn main() { + let s: Foo<f32> = Foo(3.14, 123); // Error: mismatched types +} +``` + +<a id="generic-more-generic"></a> +### Minor: changing a generic type to a more generic type + +It is safe to change a generic type to a more generic one. For example, the +following adds a generic parameter that defaults to the original type, which +is safe because all existing users will be using the same type for both +fields, the the defaulted parameter does not need to be specified. + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub struct Foo<T>(pub T, pub T); + +/////////////////////////////////////////////////////////// +// After +pub struct Foo<T, U = T>(pub T, pub U); + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::Foo; + +fn main() { + let s: Foo<f32> = Foo(1.0, 2.0); +} +``` + +<a id="fn-change-arity"></a> +### Major: adding/removing function parameters + +Changing the arity of a function is a breaking change. + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// After +pub fn foo(x: i32) {} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +fn main() { + updated_crate::foo(); // Error: this function takes 1 argument +} +``` + +Mitigating strategies: +* Introduce a new function with the new signature and possibly + [deprecate][deprecated] the old one. +* Introduce functions that take a struct argument, where the struct is built + with the builder pattern. This allows new fields to be added to the struct + in the future. + +<a id="fn-generic-new"></a> +### Possibly-breaking: introducing a new function type parameter + +Usually, adding a non-defaulted type parameter is safe, but in some +cases it can be a breaking change: + +```rust,ignore +// Breaking change example + +/////////////////////////////////////////////////////////// +// Before +pub fn foo<T>() {} + +/////////////////////////////////////////////////////////// +// After +pub fn foo<T, U>() {} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::foo; + +fn main() { + foo::<u8>(); // Error: function takes 2 generic arguments but 1 generic argument was supplied +} +``` + +However, such explicit calls are rare enough (and can usually be written in +other ways) that this breakage is usually acceptable. One should take into +account how likely it is that the function in question is being called with +explicit type arguments. + +<a id="fn-generalize-compatible"></a> +### Minor: generalizing a function to use generics (supporting original type) + +The type of a parameter to a function, or its return value, can be +*generalized* to use generics, including by introducing a new type parameter, +as long as it can be instantiated to the original type. For example, the +following changes are allowed: + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub fn foo(x: u8) -> u8 { + x +} +pub fn bar<T: Iterator<Item = u8>>(t: T) {} + +/////////////////////////////////////////////////////////// +// After +use std::ops::Add; +pub fn foo<T: Add>(x: T) -> T { + x +} +pub fn bar<T: IntoIterator<Item = u8>>(t: T) {} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::{bar, foo}; + +fn main() { + foo(1); + bar(vec![1, 2, 3].into_iter()); +} +``` + +because all existing uses are instantiations of the new signature. + +Perhaps somewhat surprisingly, generalization applies to trait objects as +well, given that every trait implements itself: + +```rust,ignore +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub trait Trait {} +pub fn foo(t: &dyn Trait) {} + +/////////////////////////////////////////////////////////// +// After +pub trait Trait {} +pub fn foo<T: Trait + ?Sized>(t: &T) {} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. +use updated_crate::{foo, Trait}; + +struct Foo; +impl Trait for Foo {} + +fn main() { + let obj = Foo; + foo(&obj); +} +``` + +(The use of `?Sized` is essential; otherwise you couldn't recover the original +signature.) + +Introducing generics in this way can potentially create type inference +failures. These are usually rare, and may be acceptable breakage for some +projects, as this can be fixed with additional type annotations. + +```rust,ignore +// Breaking change example + +/////////////////////////////////////////////////////////// +// Before +pub fn foo() -> i32 { + 0 +} + +/////////////////////////////////////////////////////////// +// After +pub fn foo<T: Default>() -> T { + Default::default() +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::foo; + +fn main() { + let x = foo(); // Error: type annotations needed +} +``` + +<a id="fn-generalize-mismatch"></a> +### Major: generalizing a function to use generics with type mismatch + +It is a breaking change to change a function parameter or return type if the +generic type constrains or changes the types previously allowed. For example, +the following adds a generic constraint that may not be satisfied by existing +code: + +```rust,ignore +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub fn foo(x: Vec<u8>) {} + +/////////////////////////////////////////////////////////// +// After +pub fn foo<T: Copy + IntoIterator<Item = u8>>(x: T) {} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +use updated_crate::foo; + +fn main() { + foo(vec![1, 2, 3]); // Error: `Copy` is not implemented for `Vec<u8>` +} +``` + +<a id="attr-no-std-to-std"></a> +### Major: switching from `no_std` support to requiring `std` + +If your library specifically supports a [`no_std`] environment, it is a +breaking change to make a new release that requires `std`. + +```rust,ignore,skip +// MAJOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +#![no_std] +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// After +pub fn foo() { + std::time::SystemTime::now(); +} + +/////////////////////////////////////////////////////////// +// Example usage that will break. +// This will fail to link for no_std targets because they don't have a `std` crate. +#![no_std] +use updated_crate::foo; + +fn example() { + foo(); +} +``` + +Mitigation strategies: +* A common idiom to avoid this is to include a `std` [Cargo feature] that + optionally enables `std` support, and when the feature is off, the library + can be used in a `no_std` environment. + +## Tooling and environment compatibility + +<a id="env-new-rust"></a> +### Possibly-breaking: changing the minimum version of Rust required + +Introducing the use of new features in a new release of Rust can break +projects that are using older versions of Rust. This also includes using new +features in a new release of Cargo, and requiring the use of a nightly-only +feature in a crate that previously worked on stable. + +Some projects choose to allow this in a minor release for various reasons. It +is usually relatively easy to update to a newer version of Rust. Rust also has +a rapid 6-week release cycle, and some projects will provide compatibility +within a window of releases (such as the current stable release plus N +previous releases). Just keep in mind that some large projects may not be able +to update their Rust toolchain rapidly. + +Mitigation strategies: +* Use [Cargo features] to make the new features opt-in. +* Provide a large window of support for older releases. +* Copy the source of new standard library items if possible so that you + can continue to use an older version but take advantage of the new feature. +* Provide a separate branch of older minor releases that can receive backports + of important bugfixes. +* Keep an eye out for the [`[cfg(version(..))]`][cfg-version] and + [`#[cfg(accessible(..))]`][cfg-accessible] features which provide an opt-in + mechanism for new features. These are currently unstable and only available + in the nightly channel. + +<a id="env-change-requirements"></a> +### Possibly-breaking: changing the platform and environment requirements + +There is a very wide range of assumptions a library makes about the +environment that it runs in, such as the host platform, operating system +version, available services, filesystem support, etc. It can be a breaking +change if you make a new release that restricts what was previously supported, +for example requiring a newer version of an operating system. These changes +can be difficult to track, since you may not always know if a change breaks in +an environment that is not automatically tested. + +Some projects may deem this acceptable breakage, particularly if the breakage +is unlikely for most users, or the project doesn't have the resources to +support all environments. Another notable situation is when a vendor +discontinues support for some hardware or OS, the project may deem it +reasonable to also discontinue support. + +Mitigation strategies: +* Document the platforms and environments you specifically support. +* Test your code on a wide range of environments in CI. + +<a id="new-lints"></a> +### Minor: introducing new lints + +Some changes to a library may cause new lints to be triggered in users of that library. +This should generally be considered a compatible change. + +```rust,ignore,dont-deny +// MINOR CHANGE + +/////////////////////////////////////////////////////////// +// Before +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// After +#[deprecated] +pub fn foo() {} + +/////////////////////////////////////////////////////////// +// Example use of the library that will safely work. + +fn main() { + updated_crate::foo(); // Warning: use of deprecated function +} +``` + +Beware that it may be possible for this to technically cause a project to fail if they have explicitly denied the warning, and the updated crate is a direct dependency. +Denying warnings should be done with care and the understanding that new lints may be introduced over time. +However, library authors should be cautious about introducing new warnings and may want to consider the potential impact on their users. + +The following lints are examples of those that may be introduced when updating a dependency: + +* [`deprecated`][deprecated-lint] --- Introduced when a dependency adds the [`#[deprecated]` attribute][deprecated] to an item you are using. +* [`unused_must_use`] --- Introduced when a dependency adds the [`#[must_use]` attribute][must-use-attr] to an item where you are not consuming the result. +* [`unused_unsafe`] --- Introduced when a dependency *removes* the `unsafe` qualifier from a function, and that is the only unsafe function called in an unsafe block. + +Additionally, updating `rustc` to a new version may introduce new lints. + +Transitive dependencies which introduce new lints should not usually cause a failure because Cargo uses [`--cap-lints`](../../rustc/lints/levels.html#capping-lints) to suppress all lints in dependencies. + +Mitigating strategies: +* If you build with warnings denied, understand you may need to deal with resolving new warnings whenever you update your dependencies. + If using RUSTFLAGS to pass `-Dwarnings`, also add the `-A` flag to allow lints that are likely to cause issues, such as `-Adeprecated`. +* Introduce deprecations behind a [feature][Cargo features]. + For example `#[cfg_attr(feature = "deprecated", deprecated="use bar instead")]`. + Then, when you plan to remove an item in a future SemVer breaking change, you can communicate with your users that they should enable the `deprecated` feature *before* updating to remove the use of the deprecated items. + This allows users to choose when to respond to deprecations without needing to immediately respond to them. + A downside is that it can be difficult to communicate to users that they need to take these manual steps to prepare for a major update. + +[`unused_must_use`]: ../../rustc/lints/listing/warn-by-default.html#unused-must-use +[deprecated-lint]: ../../rustc/lints/listing/warn-by-default.html#deprecated +[must-use-attr]: ../../reference/attributes/diagnostics.html#the-must_use-attribute +[`unused_unsafe`]: ../../rustc/lints/listing/warn-by-default.html#unused-unsafe + +### Cargo + +<a id="cargo-feature-add"></a> +#### Minor: adding a new Cargo feature + +It is usually safe to add new [Cargo features]. If the feature introduces new +changes that cause a breaking change, this can cause difficulties for projects +that have stricter backwards-compatibility needs. In that scenario, avoid +adding the feature to the "default" list, and possibly document the +consequences of enabling the feature. + +```toml +# MINOR CHANGE + +########################################################### +# Before +[features] +# ..empty + +########################################################### +# After +[features] +std = [] +``` + +<a id="cargo-feature-remove"></a> +#### Major: removing a Cargo feature + +It is usually a breaking change to remove [Cargo features]. This will cause +an error for any project that enabled the feature. + +```toml +# MAJOR CHANGE + +########################################################### +# Before +[features] +logging = [] + +########################################################### +# After +[dependencies] +# ..logging removed +``` + +Mitigation strategies: +* Clearly document your features. If there is an internal or experimental + feature, mark it as such, so that users know the status of the feature. +* Leave the old feature in `Cargo.toml`, but otherwise remove its + functionality. Document that the feature is deprecated, and remove it in a + future major SemVer release. + +<a id="cargo-feature-remove-another"></a> +#### Major: removing a feature from a feature list if that changes functionality or public items + +If removing a feature from another feature, this can break existing users if +they are expecting that functionality to be available through that feature. + +```toml +# Breaking change example + +########################################################### +# Before +[features] +default = ["std"] +std = [] + +########################################################### +# After +[features] +default = [] # This may cause packages to fail if they are expecting std to be enabled. +std = [] +``` + +<a id="cargo-remove-opt-dep"></a> +#### Possibly-breaking: removing an optional dependency + +Removing an optional dependency can break a project using your library because +another project may be enabling that dependency via [Cargo features]. + +```toml +# Breaking change example + +########################################################### +# Before +[dependencies] +curl = { version = "0.4.31", optional = true } + +########################################################### +# After +[dependencies] +# ..curl removed +``` + +Mitigation strategies: +* Clearly document your features. If the optional dependency is not included + in the documented list of features, then you may decide to consider it safe + to change undocumented entries. +* Leave the optional dependency, and just don't use it within your library. +* Replace the optional dependency with a [Cargo feature] that does nothing, + and document that it is deprecated. +* Use high-level features which enable optional dependencies, and document + those as the preferred way to enable the extended functionality. For + example, if your library has optional support for something like + "networking", create a generic feature name "networking" that enables the + optional dependencies necessary to implement "networking". Then document the + "networking" feature. + +<a id="cargo-change-dep-feature"></a> +#### Minor: changing dependency features + +It is usually safe to change the features on a dependency, as long as the +feature does not introduce a breaking change. + +```toml +# MINOR CHANGE + +########################################################### +# Before +[dependencies] +rand = { version = "0.7.3", features = ["small_rng"] } + + +########################################################### +# After +[dependencies] +rand = "0.7.3" +``` + +<a id="cargo-dep-add"></a> +#### Minor: adding dependencies + +It is usually safe to add new dependencies, as long as the new dependency +does not introduce new requirements that result in a breaking change. +For example, adding a new dependency that requires nightly in a project +that previously worked on stable is a major change. + +```toml +# MINOR CHANGE + +########################################################### +# Before +[dependencies] +# ..empty + +########################################################### +# After +[dependencies] +log = "0.4.11" +``` + +## Application compatibility + +Cargo projects may also include executable binaries which have their own +interfaces (such as a CLI interface, OS-level interaction, etc.). Since these +are part of the Cargo package, they often use and share the same version as +the package. You will need to decide if and how you want to employ a SemVer +contract with your users in the changes you make to your application. The +potential breaking and compatible changes to an application are too numerous +to list, so you are encouraged to use the spirit of the [SemVer] spec to guide +your decisions on how to apply versioning to your application, or at least +document what your commitments are. + +[`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute +[`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute +[`pub use`]: ../../reference/items/use-declarations.html +[Cargo feature]: features.md +[Cargo features]: features.md +[cfg-accessible]: https://github.com/rust-lang/rust/issues/64797 +[cfg-version]: https://github.com/rust-lang/rust/issues/64796 +[conditional compilation]: ../../reference/conditional-compilation.md +[Default]: ../../std/default/trait.Default.html +[deprecated]: ../../reference/attributes/diagnostics.html#the-deprecated-attribute +[disambiguation syntax]: ../../reference/expressions/call-expr.html#disambiguating-function-calls +[inherent implementations]: ../../reference/items/implementations.html#inherent-implementations +[items]: ../../reference/items.html +[non_exhaustive]: ../../reference/attributes/type_system.html#the-non_exhaustive-attribute +[object safe]: ../../reference/items/traits.html#object-safety +[rust-feature]: https://doc.rust-lang.org/nightly/unstable-book/ +[sealed trait]: https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed +[SemVer]: https://semver.org/ +[struct literal]: ../../reference/expressions/struct-expr.html +[wildcard patterns]: ../../reference/patterns.html#wildcard-pattern diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md new file mode 100644 index 0000000..b8bcdc7 --- /dev/null +++ b/src/doc/src/reference/source-replacement.md @@ -0,0 +1,130 @@ +## Source Replacement + +This document is about replacing the crate index. You can read about overriding +dependencies in the [overriding dependencies] section of this +documentation. + +A *source* is a provider that contains crates that may be included as +dependencies for a package. Cargo supports the ability to **replace one source +with another** to express strategies such as: + +* Vendoring --- custom sources can be defined which represent crates on the local + filesystem. These sources are subsets of the source that they're replacing and + can be checked into packages if necessary. + +* Mirroring --- sources can be replaced with an equivalent version which acts as a + cache for crates.io itself. + +Cargo has a core assumption about source replacement that the source code is +exactly the same from both sources. Note that this also means that +a replacement source is not allowed to have crates which are not present in the +original source. + +As a consequence, source replacement is not appropriate for situations such as +patching a dependency or a private registry. Cargo supports patching +dependencies through the usage of [the `[patch]` key][overriding +dependencies], and private registry support is described in [the Registries +chapter][registries]. + +When using source replacement, running commands like `cargo publish` that need to +contact the registry require passing the `--registry` option. This helps avoid +any ambiguity about which registry to contact, and will use the authentication +token for the specified registry. + +[overriding dependencies]: overriding-dependencies.md +[registries]: registries.md + +### Configuration + +Configuration of replacement sources is done through [`.cargo/config.toml`][config] +and the full set of available keys are: + +```toml +# The `source` table is where all keys related to source-replacement +# are stored. +[source] + +# Under the `source` table are a number of other tables whose keys are a +# name for the relevant source. For example this section defines a new +# source, called `my-vendor-source`, which comes from a directory +# located at `vendor` relative to the directory containing this `.cargo/config.toml` +# file +[source.my-vendor-source] +directory = "vendor" + +# The crates.io default source for crates is available under the name +# "crates-io", and here we use the `replace-with` key to indicate that it's +# replaced with our source above. +# +# The `replace-with` key can also reference an alternative registry name +# defined in the `[registries]` table. +[source.crates-io] +replace-with = "my-vendor-source" + +# Each source has its own table where the key is the name of the source +[source.the-source-name] + +# Indicate that `the-source-name` will be replaced with `another-source`, +# defined elsewhere +replace-with = "another-source" + +# Several kinds of sources can be specified (described in more detail below): +registry = "https://example.com/path/to/index" +local-registry = "path/to/registry" +directory = "path/to/vendor" + +# Git sources can optionally specify a branch/tag/rev as well +git = "https://example.com/path/to/repo" +# branch = "master" +# tag = "v1.0.1" +# rev = "313f44e8" +``` + +[config]: config.md + +### Registry Sources + +A "registry source" is one that is the same as crates.io itself. That is, it has +an index served in a git repository which matches the format of the +[crates.io index](https://github.com/rust-lang/crates.io-index). That repository +then has configuration indicating where to download crates from. + +Currently there is not an already-available project for setting up a mirror of +crates.io. Stay tuned though! + +### Local Registry Sources + +A "local registry source" is intended to be a subset of another registry +source, but available on the local filesystem (aka vendoring). Local registries +are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are +made up of a set of `*.crate` files and an index like the normal registry is. + +The primary way to manage and create local registry sources is through the +[`cargo-local-registry`][cargo-local-registry] subcommand, +[available on crates.io][cargo-local-registry] and can be installed with +`cargo install cargo-local-registry`. + +[cargo-local-registry]: https://crates.io/crates/cargo-local-registry + +Local registries are contained within one directory and contain a number of +`*.crate` files downloaded from crates.io as well as an `index` directory with +the same format as the crates.io-index project (populated with just entries for +the crates that are present). + +### Directory Sources + +A "directory source" is similar to a local registry source where it contains a +number of crates available on the local filesystem, suitable for vendoring +dependencies. Directory sources are primarily managed by the `cargo vendor` +subcommand. + +Directory sources are distinct from local registries though in that they contain +the unpacked version of `*.crate` files, making it more suitable in some +situations to check everything into source control. A directory source is just a +directory containing a number of other directories which contain the source code +for crates (the unpacked version of `*.crate` files). Currently no restriction +is placed on the name of each directory. + +Each crate in a directory source also has an associated metadata file indicating +the checksum of each file in the crate to protect against accidental +modifications. diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md new file mode 100644 index 0000000..8d9eac3 --- /dev/null +++ b/src/doc/src/reference/specifying-dependencies.md @@ -0,0 +1,513 @@ +## Specifying Dependencies + +Your crates can depend on other libraries from [crates.io] or other +registries, `git` repositories, or subdirectories on your local file system. +You can also temporarily override the location of a dependency --- for example, +to be able to test out a bug fix in the dependency that you are working on +locally. You can have different dependencies for different platforms, and +dependencies that are only used during development. Let's take a look at how +to do each of these. + +### Specifying dependencies from crates.io + +Cargo is configured to look for dependencies on [crates.io] by default. Only +the name and a version string are required in this case. In [the cargo +guide](../guide/index.md), we specified a dependency on the `time` crate: + +```toml +[dependencies] +time = "0.1.12" +``` + +The string `"0.1.12"` is a version requirement. Although it looks like a +specific *version* of the `time` crate, it actually specifies a *range* of +versions and allows [SemVer] compatible updates. An update is allowed if the new +version number does not modify the left-most non-zero digit in the major, minor, +patch grouping. In this case, if we ran `cargo update -p time`, cargo should +update us to version `0.1.13` if it is the latest `0.1.z` release, but would not +update us to `0.2.0`. If instead we had specified the version string as `1.0`, +cargo should update to `1.1` if it is the latest `1.y` release, but not `2.0`. +The version `0.0.x` is not considered compatible with any other version. + +[SemVer]: https://semver.org + +Here are some more examples of version requirements and the versions that would +be allowed with them: + +```notrust +1.2.3 := >=1.2.3, <2.0.0 +1.2 := >=1.2.0, <2.0.0 +1 := >=1.0.0, <2.0.0 +0.2.3 := >=0.2.3, <0.3.0 +0.2 := >=0.2.0, <0.3.0 +0.0.3 := >=0.0.3, <0.0.4 +0.0 := >=0.0.0, <0.1.0 +0 := >=0.0.0, <1.0.0 +``` + +This compatibility convention is different from SemVer in the way it treats +versions before 1.0.0. While SemVer says there is no compatibility before +1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z` +and `x > 0`. + +It is possible to further tweak the logic for selecting compatible versions +using special operators, though it shouldn't be necessary most of the time. + +### Caret requirements + +**Caret requirements** are an alternative syntax for the default strategy, +`^1.2.3` is exactly equivalent to `1.2.3`. + +### Tilde requirements + +**Tilde requirements** specify a minimal version with some ability to update. +If you specify a major, minor, and patch version or only a major and minor +version, only patch-level changes are allowed. If you only specify a major +version, then minor- and patch-level changes are allowed. + +`~1.2.3` is an example of a tilde requirement. + +```notrust +~1.2.3 := >=1.2.3, <1.3.0 +~1.2 := >=1.2.0, <1.3.0 +~1 := >=1.0.0, <2.0.0 +``` + +### Wildcard requirements + +**Wildcard requirements** allow for any version where the wildcard is +positioned. + +`*`, `1.*` and `1.2.*` are examples of wildcard requirements. + +```notrust +* := >=0.0.0 +1.* := >=1.0.0, <2.0.0 +1.2.* := >=1.2.0, <1.3.0 +``` + +> **Note**: [crates.io] does not allow bare `*` versions. + +### Comparison requirements + +**Comparison requirements** allow manually specifying a version range or an +exact version to depend on. + +Here are some examples of comparison requirements: + +```notrust +>= 1.2.0 +> 1 +< 2 += 1.2.3 +``` + +### Multiple requirements + +As shown in the examples above, multiple version requirements can be +separated with a comma, e.g., `>= 1.2, < 1.5`. + +### Specifying dependencies from other registries + +To specify a dependency from a registry other than [crates.io], first the +registry must be configured in a `.cargo/config.toml` file. See the [registries +documentation] for more information. In the dependency, set the `registry` key +to the name of the registry to use. + +```toml +[dependencies] +some-crate = { version = "1.0", registry = "my-registry" } +``` + +> **Note**: [crates.io] does not allow packages to be published with +> dependencies on other registries. + +[registries documentation]: registries.md + +### Specifying dependencies from `git` repositories + +To depend on a library located in a `git` repository, the minimum information +you need to specify is the location of the repository with the `git` key: + +```toml +[dependencies] +regex = { git = "https://github.com/rust-lang/regex.git" } +``` + +Cargo will fetch the `git` repository at this location then look for a +`Cargo.toml` for the requested crate anywhere inside the `git` repository +(not necessarily at the root --- for example, specifying a member crate name +of a workspace and setting `git` to the repository containing the workspace). + +Since we haven’t specified any other information, Cargo assumes that +we intend to use the latest commit on the main branch to build our package. +You can combine the `git` key with the `rev`, `tag`, or `branch` keys to +specify something else. Here's an example of specifying that you want to use +the latest commit on a branch named `next`: + +```toml +[dependencies] +regex = { git = "https://github.com/rust-lang/regex.git", branch = "next" } +``` + +Anything that is not a branch or tag falls under `rev`. This can be a commit +hash like `rev = "4c59b707"`, or a named reference exposed by the remote +repository such as `rev = "refs/pull/493/head"`. What references are available +varies by where the repo is hosted; GitHub in particular exposes a reference to +the most recent commit of every pull request as shown, but other git hosts often +provide something equivalent, possibly under a different naming scheme. + +Once a `git` dependency has been added, Cargo will lock that dependency to the +latest commit at the time. New commits will not be pulled down automatically +once the lock is in place. However, they can be pulled down manually with +`cargo update`. + +See [Git Authentication] for help with git authentication for private repos. + +> **Note**: [crates.io] does not allow packages to be published with `git` +> dependencies (`git` [dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative. + +[Git Authentication]: ../appendix/git-authentication.md + +### Specifying path dependencies + +Over time, our `hello_world` package from [the guide](../guide/index.md) has +grown significantly in size! It’s gotten to the point that we probably want to +split out a separate crate for others to use. To do this Cargo supports **path +dependencies** which are typically sub-crates that live within one repository. +Let’s start off by making a new crate inside of our `hello_world` package: + +```console +# inside of hello_world/ +$ cargo new hello_utils +``` + +This will create a new folder `hello_utils` inside of which a `Cargo.toml` and +`src` folder are ready to be configured. In order to tell Cargo about this, open +up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies: + +```toml +[dependencies] +hello_utils = { path = "hello_utils" } +``` + +This tells Cargo that we depend on a crate called `hello_utils` which is found +in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). + +And that’s it! The next `cargo build` will automatically build `hello_utils` and +all of its own dependencies, and others can also start using the crate as well. +However, crates that use dependencies specified with only a path are not +permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we +would need to publish a version of `hello_utils` to [crates.io] +and specify its version in the dependencies line as well: + +```toml +[dependencies] +hello_utils = { path = "hello_utils", version = "0.1.0" } +``` + +> **Note**: [crates.io] does not allow packages to be published with `path` +> dependencies (`path` [dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative. + +### Multiple locations + +It is possible to specify both a registry version and a `git` or `path` +location. The `git` or `path` dependency will be used locally (in which case +the `version` is checked against the local copy), and when published to a +registry like [crates.io], it will use the registry version. Other +combinations are not allowed. Examples: + +```toml +[dependencies] +# Uses `my-bitflags` when used locally, and uses +# version 1.0 from crates.io when published. +bitflags = { path = "my-bitflags", version = "1.0" } + +# Uses the given git repo when used locally, and uses +# version 1.0 from crates.io when published. +smallvec = { git = "https://github.com/servo/rust-smallvec.git", version = "1.0" } + +# N.B. that if a version doesn't match, Cargo will fail to compile! +``` + +One example where this can be useful is when you have split up a library into +multiple packages within the same workspace. You can then use `path` +dependencies to point to the local packages within the workspace to use the +local version during development, and then use the [crates.io] version once it +is published. This is similar to specifying an +[override](overriding-dependencies.md), but only applies to this one +dependency declaration. + +### Platform specific dependencies + +Platform-specific dependencies take the same format, but are listed under a +`target` section. Normally Rust-like [`#[cfg]` +syntax](../../reference/conditional-compilation.html) will be used to define +these sections: + +```toml +[target.'cfg(windows)'.dependencies] +winhttp = "0.4.0" + +[target.'cfg(unix)'.dependencies] +openssl = "1.0.1" + +[target.'cfg(target_arch = "x86")'.dependencies] +native-i686 = { path = "native/i686" } + +[target.'cfg(target_arch = "x86_64")'.dependencies] +native-x86_64 = { path = "native/x86_64" } +``` + +Like with Rust, the syntax here supports the `not`, `any`, and `all` operators +to combine various cfg name/value pairs. + +If you want to know which cfg targets are available on your platform, run +`rustc --print=cfg` from the command line. If you want to know which `cfg` +targets are available for another platform, such as 64-bit Windows, +run `rustc --print=cfg --target=x86_64-pc-windows-msvc`. + +Unlike in your Rust source code, you cannot use +`[target.'cfg(feature = "fancy-feature")'.dependencies]` to add dependencies +based on optional features. Use [the `[features]` section](features.md) +instead: + +```toml +[dependencies] +foo = { version = "1.0", optional = true } +bar = { version = "1.0", optional = true } + +[features] +fancy-feature = ["foo", "bar"] +``` + +The same applies to `cfg(debug_assertions)`, `cfg(test)` and `cfg(proc_macro)`. +These values will not work as expected and will always have the default value +returned by `rustc --print=cfg`. +There is currently no way to add dependencies based on these configuration values. + +In addition to `#[cfg]` syntax, Cargo also supports listing out the full target +the dependencies would apply to: + +```toml +[target.x86_64-pc-windows-gnu.dependencies] +winhttp = "0.4.0" + +[target.i686-unknown-linux-gnu.dependencies] +openssl = "1.0.1" +``` + +#### Custom target specifications + +If you’re using a custom target specification (such as `--target +foo/bar.json`), use the base filename without the `.json` extension: + +```toml +[target.bar.dependencies] +winhttp = "0.4.0" + +[target.my-special-i686-platform.dependencies] +openssl = "1.0.1" +native = { path = "native/i686" } +``` + +> **Note**: Custom target specifications are not usable on the stable channel. + +### Development dependencies + +You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format +is equivalent to `[dependencies]`: + +```toml +[dev-dependencies] +tempdir = "0.3" +``` + +Dev-dependencies are not used when compiling +a package for building, but are used for compiling tests, examples, and +benchmarks. + +These dependencies are *not* propagated to other packages which depend on this +package. + +You can also have target-specific development dependencies by using +`dev-dependencies` in the target section header instead of `dependencies`. For +example: + +```toml +[target.'cfg(unix)'.dev-dependencies] +mio = "0.0.1" +``` + +> **Note**: When a package is published, only dev-dependencies that specify a +> `version` will be included in the published crate. For most use cases, +> dev-dependencies are not needed when published, though some users (like OS +> packagers) may want to run tests within a crate, so providing a `version` if +> possible can still be beneficial. + +### Build dependencies + +You can depend on other Cargo-based crates for use in your build scripts. +Dependencies are declared through the `build-dependencies` section of the +manifest: + +```toml +[build-dependencies] +cc = "1.0.3" +``` + + +You can also have target-specific build dependencies by using +`build-dependencies` in the target section header instead of `dependencies`. For +example: + +```toml +[target.'cfg(unix)'.build-dependencies] +cc = "1.0.3" +``` + +In this case, the dependency will only be built when the host platform matches the +specified target. + +The build script **does not** have access to the dependencies listed +in the `dependencies` or `dev-dependencies` section. Build +dependencies will likewise not be available to the package itself +unless listed under the `dependencies` section as well. A package +itself and its build script are built separately, so their +dependencies need not coincide. Cargo is kept simpler and cleaner by +using independent dependencies for independent purposes. + +### Choosing features + +If a package you depend on offers conditional features, you can +specify which to use: + +```toml +[dependencies.awesome] +version = "1.3.5" +default-features = false # do not include the default features, and optionally + # cherry-pick individual features +features = ["secure-password", "civet"] +``` + +More information about features can be found in the [features +chapter](features.md#dependency-features). + +### Renaming dependencies in `Cargo.toml` + +When writing a `[dependencies]` section in `Cargo.toml` the key you write for a +dependency typically matches up to the name of the crate you import from in the +code. For some projects, though, you may wish to reference the crate with a +different name in the code regardless of how it's published on crates.io. For +example you may wish to: + +* Avoid the need to `use foo as bar` in Rust source. +* Depend on multiple versions of a crate. +* Depend on crates with the same name from different registries. + +To support this Cargo supports a `package` key in the `[dependencies]` section +of which package should be depended on: + +```toml +[package] +name = "mypackage" +version = "0.0.1" + +[dependencies] +foo = "0.1" +bar = { git = "https://github.com/example/project.git", package = "foo" } +baz = { version = "0.1", registry = "custom", package = "foo" } +``` + +In this example, three crates are now available in your Rust code: + +```rust,ignore +extern crate foo; // crates.io +extern crate bar; // git repository +extern crate baz; // registry `custom` +``` + +All three of these crates have the package name of `foo` in their own +`Cargo.toml`, so we're explicitly using the `package` key to inform Cargo that +we want the `foo` package even though we're calling it something else locally. +The `package` key, if not specified, defaults to the name of the dependency +being requested. + +Note that if you have an optional dependency like: + +```toml +[dependencies] +bar = { version = "0.1", package = 'foo', optional = true } +``` + +you're depending on the crate `foo` from crates.io, but your crate has a `bar` +feature instead of a `foo` feature. That is, names of features take after the +name of the dependency, not the package name, when renamed. + +Enabling transitive dependencies works similarly, for example we could add the +following to the above manifest: + +```toml +[features] +log-debug = ['bar/log-debug'] # using 'foo/log-debug' would be an error! +``` + +### Inheriting a dependency from a workspace + +Dependencies can be inherited from a workspace by specifying the +dependency in the workspace's [`[workspace.dependencies]`][workspace.dependencies] table. +After that, add it to the `[dependencies]` table with `workspace = true`. + +Along with the `workspace` key, dependencies can also include these keys: +- [`optional`][optional]: Note that the`[workspace.dependencies]` table is not allowed to specify `optional`. +- [`features`][features]: These are additive with the features declared in the `[workspace.dependencies]` + +Other than `optional` and `features`, inherited dependencies cannot use any other +dependency key (such as `version` or `default-features`). + +Dependencies in the `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, and +`[target."...".dependencies]` sections support the ability to reference the +`[workspace.dependencies]` definition of dependencies. + +```toml +[package] +name = "bar" +version = "0.2.0" + +[dependencies] +regex = { workspace = true, features = ["unicode"] } + +[build-dependencies] +cc.workspace = true + +[dev-dependencies] +rand = { workspace = true, optional = true } +``` + + +[crates.io]: https://crates.io/ +[dev-dependencies]: #development-dependencies +[workspace.dependencies]: workspaces.md#the-dependencies-table +[optional]: features.md#optional-dependencies +[features]: features.md + +<script> +(function() { + var fragments = { + "#overriding-dependencies": "overriding-dependencies.html", + "#testing-a-bugfix": "overriding-dependencies.html#testing-a-bugfix", + "#working-with-an-unpublished-minor-version": "overriding-dependencies.html#working-with-an-unpublished-minor-version", + "#overriding-repository-url": "overriding-dependencies.html#overriding-repository-url", + "#prepublishing-a-breaking-change": "overriding-dependencies.html#prepublishing-a-breaking-change", + "#overriding-with-local-dependencies": "overriding-dependencies.html#paths-overrides", + }; + var target = fragments[window.location.hash]; + if (target) { + var url = window.location.toString(); + var base = url.substring(0, url.lastIndexOf('/')); + window.location.replace(base + "/" + target); + } +})(); +</script> diff --git a/src/doc/src/reference/timings.md b/src/doc/src/reference/timings.md new file mode 100644 index 0000000..9e68633 --- /dev/null +++ b/src/doc/src/reference/timings.md @@ -0,0 +1,51 @@ +# Reporting build timings +The `--timings` option gives some information about how long each compilation +takes, and tracks concurrency information over time. + +```sh +cargo build --timings +``` + +This writes an HTML report in `target/cargo-timings/cargo-timing.html`. This +also writes a copy of the report to the same directory with a timestamp in the +filename, if you want to look at older runs. + +#### Reading the graphs + +There are two graphs in the output. The "unit" graph shows the duration of +each unit over time. A "unit" is a single compiler invocation. There are lines +that show which additional units are "unlocked" when a unit finishes. That is, +it shows the new units that are now allowed to run because their dependencies +are all finished. Hover the mouse over a unit to highlight the lines. This can +help visualize the critical path of dependencies. This may change between runs +because the units may finish in different orders. + +The "codegen" times are highlighted in a lavender color. In some cases, build +pipelining allows units to start when their dependencies are performing code +generation. This information is not always displayed (for example, binary +units do not show when code generation starts). + +The "custom build" units are `build.rs` scripts, which when run are +highlighted in orange. + +The second graph shows Cargo's concurrency over time. The background +indicates CPU usage. The three lines are: +- "Waiting" (red) --- This is the number of units waiting for a CPU slot to + open. +- "Inactive" (blue) --- This is the number of units that are waiting for their + dependencies to finish. +- "Active" (green) --- This is the number of units currently running. + +Note: This does not show the concurrency in the compiler itself. `rustc` +coordinates with Cargo via the "job server" to stay within the concurrency +limit. This currently mostly applies to the code generation phase. + +Tips for addressing compile times: +- Look for slow dependencies. + - Check if they have features that you may wish to consider disabling. + - Consider trying to remove the dependency completely. +- Look for a crate being built multiple times with different versions. Try to + remove the older versions from the dependency graph. +- Split large crates into smaller pieces. +- If there are a large number of crates bottlenecked on a single crate, focus + your attention on improving that one crate to improve parallelism. diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md new file mode 100644 index 0000000..0b21118 --- /dev/null +++ b/src/doc/src/reference/unstable.md @@ -0,0 +1,1464 @@ +## Unstable Features + +Experimental Cargo features are only available on the [nightly channel]. You +are encouraged to experiment with these features to see if they meet your +needs, and if there are any issues or problems. Check the linked tracking +issues listed below for more information on the feature, and click the GitHub +subscribe button if you want future updates. + +After some period of time, if the feature does not have any major concerns, it +can be [stabilized], which will make it available on stable once the current +nightly release reaches the stable channel (anywhere from 6 to 12 weeks). + +There are three different ways that unstable features can be enabled based on +how the feature works: + +* New syntax in `Cargo.toml` requires a `cargo-features` key at the top of + `Cargo.toml`, before any tables. For example: + + ```toml + # This specifies which new Cargo.toml features are enabled. + cargo-features = ["test-dummy-unstable"] + + [package] + name = "my-package" + version = "0.1.0" + im-a-teapot = true # This is a new option enabled by test-dummy-unstable. + ``` + +* New command-line flags, options, and subcommands require the `-Z + unstable-options` CLI option to also be included. For example, the new + `--out-dir` option is only available on nightly: + + ```cargo +nightly build --out-dir=out -Z unstable-options``` + +* `-Z` command-line flags are used to enable new functionality that may not + have an interface, or the interface has not yet been designed, or for more + complex features that affect multiple parts of Cargo. For example, the + [mtime-on-use](#mtime-on-use) feature can be enabled with: + + ```cargo +nightly build -Z mtime-on-use``` + + Run `cargo -Z help` to see a list of flags available. + + Anything which can be configured with a `-Z` flag can also be set in the + cargo [config file] (`.cargo/config.toml`) in the `unstable` table. For + example: + + ```toml + [unstable] + mtime-on-use = true + build-std = ["core", "alloc"] + ``` + +Each new feature described below should explain how to use it. + +[config file]: config.md +[nightly channel]: ../../book/appendix-07-nightly-rust.html +[stabilized]: https://doc.crates.io/contrib/process/unstable.html#stabilization + +### List of unstable features + +* Unstable-specific features + * [-Z allow-features](#allow-features) --- Provides a way to restrict which unstable features are used. +* Build scripts and linking + * [Metabuild](#metabuild) --- Provides declarative build scripts. +* Resolver and features + * [no-index-update](#no-index-update) --- Prevents cargo from updating the index cache. + * [avoid-dev-deps](#avoid-dev-deps) --- Prevents the resolver from including dev-dependencies during resolution. + * [minimal-versions](#minimal-versions) --- Forces the resolver to use the lowest compatible version instead of the highest. + * [public-dependency](#public-dependency) --- Allows dependencies to be classified as either public or private. +* Output behavior + * [out-dir](#out-dir) --- Adds a directory where artifacts are copied to. + * [Different binary name](#different-binary-name) --- Assign a name to the built binary that is separate from the crate name. +* Compile behavior + * [mtime-on-use](#mtime-on-use) --- Updates the last-modified timestamp on every dependency every time it is used, to provide a mechanism to delete unused artifacts. + * [doctest-xcompile](#doctest-xcompile) --- Supports running doctests with the `--target` flag. + * [build-std](#build-std) --- Builds the standard library instead of using pre-built binaries. + * [build-std-features](#build-std-features) --- Sets features to use with the standard library. + * [binary-dep-depinfo](#binary-dep-depinfo) --- Causes the dep-info file to track binary dependencies. + * [panic-abort-tests](#panic-abort-tests) --- Allows running tests with the "abort" panic strategy. + * [keep-going](#keep-going) --- Build as much as possible rather than aborting on the first error. +* rustdoc + * [`doctest-in-workspace`](#doctest-in-workspace) --- Fixes workspace-relative paths when running doctests. + * [rustdoc-map](#rustdoc-map) --- Provides mappings for documentation to link to external sites like [docs.rs](https://docs.rs/). +* `Cargo.toml` extensions + * [Profile `rustflags` option](#profile-rustflags-option) --- Passed directly to rustc. + * [codegen-backend](#codegen-backend) --- Select the codegen backend used by rustc. + * [per-package-target](#per-package-target) --- Sets the `--target` to use for each individual package. + * [artifact dependencies](#artifact-dependencies) --- Allow build artifacts to be included into other build artifacts and build them for different targets. +* Information and metadata + * [Build-plan](#build-plan) --- Emits JSON information on which commands will be run. + * [unit-graph](#unit-graph) --- Emits JSON for Cargo's internal graph structure. + * [`cargo rustc --print`](#rustc---print) --- Calls rustc with `--print` to display information from rustc. +* Configuration + * [config-include](#config-include) --- Adds the ability for config files to include other files. + * [`cargo config`](#cargo-config) --- Adds a new subcommand for viewing config files. +* Registries + * [credential-process](#credential-process) --- Adds support for fetching registry tokens from an external authentication program. + * [`cargo logout`](#cargo-logout) --- Adds the `logout` command to remove the currently saved registry token. + * [publish-timeout](#publish-timeout) --- Controls the timeout between uploading the crate and being available in the index + * [registry-auth](#registry-auth) --- Adds support for authenticated registries, and generate registry authentication tokens using asymmetric cryptography. + +### allow-features + +This permanently-unstable flag makes it so that only a listed set of +unstable features can be used. Specifically, if you pass +`-Zallow-features=foo,bar`, you'll continue to be able to pass `-Zfoo` +and `-Zbar` to `cargo`, but you will be unable to pass `-Zbaz`. You can +pass an empty string (`-Zallow-features=`) to disallow all unstable +features. + +`-Zallow-features` also restricts which unstable features can be passed +to the `cargo-features` entry in `Cargo.toml`. If, for example, you want +to allow + +```toml +cargo-features = ["test-dummy-unstable"] +``` + +where `test-dummy-unstable` is unstable, that features would also be +disallowed by `-Zallow-features=`, and allowed with +`-Zallow-features=test-dummy-unstable`. + +The list of features passed to cargo's `-Zallow-features` is also passed +to any Rust tools that cargo ends up calling (like `rustc` or +`rustdoc`). Thus, if you run `cargo -Zallow-features=`, no unstable +Cargo _or_ Rust features can be used. + +### no-index-update +* Original Issue: [#3479](https://github.com/rust-lang/cargo/issues/3479) +* Tracking Issue: [#7404](https://github.com/rust-lang/cargo/issues/7404) + +The `-Z no-index-update` flag ensures that Cargo does not attempt to update +the registry index. This is intended for tools such as Crater that issue many +Cargo commands, and you want to avoid the network latency for updating the +index each time. + +### mtime-on-use +* Original Issue: [#6477](https://github.com/rust-lang/cargo/pull/6477) +* Cache usage meta tracking issue: [#7150](https://github.com/rust-lang/cargo/issues/7150) + +The `-Z mtime-on-use` flag is an experiment to have Cargo update the mtime of +used files to make it easier for tools like cargo-sweep to detect which files +are stale. For many workflows this needs to be set on *all* invocations of cargo. +To make this more practical setting the `unstable.mtime_on_use` flag in `.cargo/config.toml` +or the corresponding ENV variable will apply the `-Z mtime-on-use` to all +invocations of nightly cargo. (the config flag is ignored by stable) + +### avoid-dev-deps +* Original Issue: [#4988](https://github.com/rust-lang/cargo/issues/4988) +* Tracking Issue: [#5133](https://github.com/rust-lang/cargo/issues/5133) + +When running commands such as `cargo install` or `cargo build`, Cargo +currently requires dev-dependencies to be downloaded, even if they are not +used. The `-Z avoid-dev-deps` flag allows Cargo to avoid downloading +dev-dependencies if they are not needed. The `Cargo.lock` file will not be +generated if dev-dependencies are skipped. + +### minimal-versions +* Original Issue: [#4100](https://github.com/rust-lang/cargo/issues/4100) +* Tracking Issue: [#5657](https://github.com/rust-lang/cargo/issues/5657) + +> Note: It is not recommended to use this feature. Because it enforces minimal +> versions for all transitive dependencies, its usefulness is limited since +> not all external dependencies declare proper lower version bounds. It is +> intended that it will be changed in the future to only enforce minimal +> versions for direct dependencies. + +When a `Cargo.lock` file is generated, the `-Z minimal-versions` flag will +resolve the dependencies to the minimum SemVer version that will satisfy the +requirements (instead of the greatest version). + +The intended use-case of this flag is to check, during continuous integration, +that the versions specified in Cargo.toml are a correct reflection of the +minimum versions that you are actually using. That is, if Cargo.toml says +`foo = "1.0.0"` that you don't accidentally depend on features added only in +`foo 1.5.0`. + +### out-dir +* Original Issue: [#4875](https://github.com/rust-lang/cargo/issues/4875) +* Tracking Issue: [#6790](https://github.com/rust-lang/cargo/issues/6790) + +This feature allows you to specify the directory where artifacts will be +copied to after they are built. Typically artifacts are only written to the +`target/release` or `target/debug` directories. However, determining the +exact filename can be tricky since you need to parse JSON output. The +`--out-dir` flag makes it easier to predictably access the artifacts. Note +that the artifacts are copied, so the originals are still in the `target` +directory. Example: + +```sh +cargo +nightly build --out-dir=out -Z unstable-options +``` + +This can also be specified in `.cargo/config.toml` files. + +```toml +[build] +out-dir = "out" +``` + +### doctest-xcompile +* Tracking Issue: [#7040](https://github.com/rust-lang/cargo/issues/7040) +* Tracking Rustc Issue: [#64245](https://github.com/rust-lang/rust/issues/64245) + +This flag changes `cargo test`'s behavior when handling doctests when +a target is passed. Currently, if a target is passed that is different +from the host cargo will simply skip testing doctests. If this flag is +present, cargo will continue as normal, passing the tests to doctest, +while also passing it a `--target` option, as well as enabling +`-Zunstable-features --enable-per-target-ignores` and passing along +information from `.cargo/config.toml`. See the rustc issue for more information. + +```sh +cargo test --target foo -Zdoctest-xcompile +``` + +#### New `dir-name` attribute + +Some of the paths generated under `target/` have resulted in a de-facto "build +protocol", where `cargo` is invoked as a part of a larger project build. So, to +preserve the existing behavior, there is also a new attribute `dir-name`, which +when left unspecified, defaults to the name of the profile. For example: + +```toml +[profile.release-lto] +inherits = "release" +dir-name = "lto" # Emits to target/lto instead of target/release-lto +lto = true +``` + +### Build-plan +* Tracking Issue: [#5579](https://github.com/rust-lang/cargo/issues/5579) + +The `--build-plan` argument for the `build` command will output JSON with +information about which commands would be run without actually executing +anything. This can be useful when integrating with another build tool. +Example: + +```sh +cargo +nightly build --build-plan -Z unstable-options +``` + +### Metabuild +* Tracking Issue: [rust-lang/rust#49803](https://github.com/rust-lang/rust/issues/49803) +* RFC: [#2196](https://github.com/rust-lang/rfcs/blob/master/text/2196-metabuild.md) + +Metabuild is a feature to have declarative build scripts. Instead of writing +a `build.rs` script, you specify a list of build dependencies in the +`metabuild` key in `Cargo.toml`. A build script is automatically generated +that runs each build dependency in order. Metabuild packages can then read +metadata from `Cargo.toml` to specify their behavior. + +Include `cargo-features` at the top of `Cargo.toml`, a `metabuild` key in the +`package`, list the dependencies in `build-dependencies`, and add any metadata +that the metabuild packages require under `package.metadata`. Example: + +```toml +cargo-features = ["metabuild"] + +[package] +name = "mypackage" +version = "0.0.1" +metabuild = ["foo", "bar"] + +[build-dependencies] +foo = "1.0" +bar = "1.0" + +[package.metadata.foo] +extra-info = "qwerty" +``` + +Metabuild packages should have a public function called `metabuild` that +performs the same actions as a regular `build.rs` script would perform. + +### public-dependency +* Tracking Issue: [#44663](https://github.com/rust-lang/rust/issues/44663) + +The 'public-dependency' feature allows marking dependencies as 'public' +or 'private'. When this feature is enabled, additional information is passed to rustc to allow +the 'exported_private_dependencies' lint to function properly. + +This requires the appropriate key to be set in `cargo-features`: + +```toml +cargo-features = ["public-dependency"] + +[dependencies] +my_dep = { version = "1.2.3", public = true } +private_dep = "2.0.0" # Will be 'private' by default +``` + +### build-std +* Tracking Repository: <https://github.com/rust-lang/wg-cargo-std-aware> + +The `build-std` feature enables Cargo to compile the standard library itself as +part of a crate graph compilation. This feature has also historically been known +as "std-aware Cargo". This feature is still in very early stages of development, +and is also a possible massive feature addition to Cargo. This is a very large +feature to document, even in the minimal form that it exists in today, so if +you're curious to stay up to date you'll want to follow the [tracking +repository](https://github.com/rust-lang/wg-cargo-std-aware) and its set of +issues. + +The functionality implemented today is behind a flag called `-Z build-std`. This +flag indicates that Cargo should compile the standard library from source code +using the same profile as the main build itself. Note that for this to work you +need to have the source code for the standard library available, and at this +time the only supported method of doing so is to add the `rust-src` rust rustup +component: + +```console +$ rustup component add rust-src --toolchain nightly +``` + +It is also required today that the `-Z build-std` flag is combined with the +`--target` flag. Note that you're not forced to do a cross compilation, you're +just forced to pass `--target` in one form or another. + +Usage looks like: + +```console +$ cargo new foo +$ cd foo +$ cargo +nightly run -Z build-std --target x86_64-unknown-linux-gnu + Compiling core v0.0.0 (...) + ... + Compiling foo v0.1.0 (...) + Finished dev [unoptimized + debuginfo] target(s) in 21.00s + Running `target/x86_64-unknown-linux-gnu/debug/foo` +Hello, world! +``` + +Here we recompiled the standard library in debug mode with debug assertions +(like `src/main.rs` is compiled) and everything was linked together at the end. + +Using `-Z build-std` will implicitly compile the stable crates `core`, `std`, +`alloc`, and `proc_macro`. If you're using `cargo test` it will also compile the +`test` crate. If you're working with an environment which does not support some +of these crates, then you can pass an argument to `-Zbuild-std` as well: + +```console +$ cargo +nightly build -Z build-std=core,alloc +``` + +The value here is a comma-separated list of standard library crates to build. + +#### Requirements + +As a summary, a list of requirements today to use `-Z build-std` are: + +* You must install libstd's source code through `rustup component add rust-src` +* You must pass `--target` +* You must use both a nightly Cargo and a nightly rustc +* The `-Z build-std` flag must be passed to all `cargo` invocations. + +#### Reporting bugs and helping out + +The `-Z build-std` feature is in the very early stages of development! This +feature for Cargo has an extremely long history and is very large in scope, and +this is just the beginning. If you'd like to report bugs please either report +them to: + +* Cargo --- <https://github.com/rust-lang/cargo/issues/new> --- for implementation bugs +* The tracking repository --- + <https://github.com/rust-lang/wg-cargo-std-aware/issues/new> --- for larger design + questions. + +Also if you'd like to see a feature that's not yet implemented and/or if +something doesn't quite work the way you'd like it to, feel free to check out +the [issue tracker](https://github.com/rust-lang/wg-cargo-std-aware/issues) of +the tracking repository, and if it's not there please file a new issue! + +### build-std-features +* Tracking Repository: <https://github.com/rust-lang/wg-cargo-std-aware> + +This flag is a sibling to the `-Zbuild-std` feature flag. This will configure +the features enabled for the standard library itself when building the standard +library. The default enabled features, at this time, are `backtrace` and +`panic_unwind`. This flag expects a comma-separated list and, if provided, will +override the default list of features enabled. + +### binary-dep-depinfo +* Tracking rustc issue: [#63012](https://github.com/rust-lang/rust/issues/63012) + +The `-Z binary-dep-depinfo` flag causes Cargo to forward the same flag to +`rustc` which will then cause `rustc` to include the paths of all binary +dependencies in the "dep info" file (with the `.d` extension). Cargo then uses +that information for change-detection (if any binary dependency changes, then +the crate will be rebuilt). The primary use case is for building the compiler +itself, which has implicit dependencies on the standard library that would +otherwise be untracked for change-detection. + +### panic-abort-tests +* Tracking Issue: [#67650](https://github.com/rust-lang/rust/issues/67650) +* Original Pull Request: [#7460](https://github.com/rust-lang/cargo/pull/7460) + +The `-Z panic-abort-tests` flag will enable nightly support to compile test +harness crates with `-Cpanic=abort`. Without this flag Cargo will compile tests, +and everything they depend on, with `-Cpanic=unwind` because it's the only way +`test`-the-crate knows how to operate. As of [rust-lang/rust#64158], however, +the `test` crate supports `-C panic=abort` with a test-per-process, and can help +avoid compiling crate graphs multiple times. + +It's currently unclear how this feature will be stabilized in Cargo, but we'd +like to stabilize it somehow! + +[rust-lang/rust#64158]: https://github.com/rust-lang/rust/pull/64158 + +### keep-going +* Tracking Issue: [#10496](https://github.com/rust-lang/cargo/issues/10496) + +`cargo build --keep-going` (and similarly for `check`, `test` etc) will build as +many crates in the dependency graph as possible, rather than aborting the build +at the first one that fails to build. + +For example if the current package depends on dependencies `fails` and `works`, +one of which fails to build, `cargo check -j1` may or may not build the one that +succeeds (depending on which one of the two builds Cargo picked to run first), +whereas `cargo check -j1 --keep-going` would definitely run both builds, even if +the one run first fails. + +The `-Z unstable-options` command-line option must be used in order to use +`--keep-going` while it is not yet stable: + +```console +cargo check --keep-going -Z unstable-options +``` + +### config-include +* Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723) + +The `include` key in a config file can be used to load another config file. It +takes a string for a path to another file relative to the config file, or a +list of strings. It requires the `-Zconfig-include` command-line option. + +```toml +# .cargo/config +include = '../../some-common-config.toml' +``` + +The config values are first loaded from the include path, and then the config +file's own values are merged on top of it. + +This can be paired with [config-cli](#config-cli) to specify a file to load +from the command-line. Pass a path to a config file as the argument to +`--config`: + +```console +cargo +nightly -Zunstable-options -Zconfig-include --config somefile.toml build +``` + +CLI paths are relative to the current working directory. + +### target-applies-to-host +* Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322) +* Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453) + +Historically, Cargo's behavior for whether the `linker` and `rustflags` +configuration options from environment variables and +[`[target]`](config.md#target) are respected for build scripts, plugins, +and other artifacts that are _always_ built for the host platform has +been somewhat inconsistent. +When `--target` is _not_ passed, Cargo respects the same `linker` and +`rustflags` for build scripts as for all other compile artifacts. When +`--target` _is_ passed, however, Cargo respects `linker` from +[`[target.<host triple>]`](config.md#targettriplelinker), and does not +pick up any `rustflags` configuration. +This dual behavior is confusing, but also makes it difficult to correctly +configure builds where the host triple and the [target triple] happen to +be the same, but artifacts intended to run on the build host should still +be configured differently. + +`-Ztarget-applies-to-host` enables the top-level +`target-applies-to-host` setting in Cargo configuration files which +allows users to opt into different (and more consistent) behavior for +these properties. When `target-applies-to-host` is unset, or set to +`true`, in the configuration file, the existing Cargo behavior is +preserved (though see `-Zhost-config`, which changes that default). When +it is set to `false`, no options from `[target.<host triple>]`, +`RUSTFLAGS`, or `[build]` are respected for host artifacts regardless of +whether `--target` is passed to Cargo. To customize artifacts intended +to be run on the host, use `[host]` ([`host-config`](#host-config)). + +In the future, `target-applies-to-host` may end up defaulting to `false` +to provide more sane and consistent default behavior. + +```toml +# config.toml +target-applies-to-host = false +``` + +```console +cargo +nightly -Ztarget-applies-to-host build --target x86_64-unknown-linux-gnu +``` + +### host-config +* Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322) +* Tracking Issue: [#9452](https://github.com/rust-lang/cargo/issues/9452) + +The `host` key in a config file can be used pass flags to host build targets +such as build scripts that must run on the host system instead of the target +system when cross compiling. It supports both generic and host arch specific +tables. Matching host arch tables take precedence over generic host tables. + +It requires the `-Zhost-config` and `-Ztarget-applies-to-host` +command-line options to be set, and that `target-applies-to-host = +false` is set in the Cargo configuration file. + +```toml +# config.toml +[host] +linker = "/path/to/host/linker" +[host.x86_64-unknown-linux-gnu] +linker = "/path/to/host/arch/linker" +rustflags = ["-Clink-arg=--verbose"] +[target.x86_64-unknown-linux-gnu] +linker = "/path/to/target/linker" +``` + +The generic `host` table above will be entirely ignored when building on a +`x86_64-unknown-linux-gnu` host as the `host.x86_64-unknown-linux-gnu` table +takes precedence. + +Setting `-Zhost-config` changes the default for `target-applies-to-host` to +`false` from `true`. + +```console +cargo +nightly -Ztarget-applies-to-host -Zhost-config build --target x86_64-unknown-linux-gnu +``` + +### unit-graph +* Tracking Issue: [#8002](https://github.com/rust-lang/cargo/issues/8002) + +The `--unit-graph` flag can be passed to any build command (`build`, `check`, +`run`, `test`, `bench`, `doc`, etc.) to emit a JSON object to stdout which +represents Cargo's internal unit graph. Nothing is actually built, and the +command returns immediately after printing. Each "unit" corresponds to an +execution of the compiler. These objects also include which unit each unit +depends on. + +``` +cargo +nightly build --unit-graph -Z unstable-options +``` + +This structure provides a more complete view of the dependency relationship as +Cargo sees it. In particular, the "features" field supports the new feature +resolver where a dependency can be built multiple times with different +features. `cargo metadata` fundamentally cannot represent the relationship of +features between different dependency kinds, and features now depend on which +command is run and which packages and targets are selected. Additionally it +can provide details about intra-package dependencies like build scripts or +tests. + +The following is a description of the JSON structure: + +```javascript +{ + /* Version of the JSON output structure. If any backwards incompatible + changes are made, this value will be increased. + */ + "version": 1, + /* Array of all build units. */ + "units": [ + { + /* An opaque string which indicates the package. + Information about the package can be obtained from `cargo metadata`. + */ + "pkg_id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The Cargo target. See the `cargo metadata` documentation for more + information about these fields. + https://doc.rust-lang.org/cargo/commands/cargo-metadata.html + */ + "target": { + "kind": ["lib"], + "crate_types": ["lib"], + "name": "my-package", + "src_path": "/path/to/my-package/src/lib.rs", + "edition": "2018", + "test": true, + "doctest": true + }, + /* The profile settings for this unit. + These values may not match the profile defined in the manifest. + Units can use modified profile settings. For example, the "panic" + setting can be overridden for tests to force it to "unwind". + */ + "profile": { + /* The profile name these settings are derived from. */ + "name": "dev", + /* The optimization level as a string. */ + "opt_level": "0", + /* The LTO setting as a string. */ + "lto": "false", + /* The codegen units as an integer. + `null` if it should use the compiler's default. + */ + "codegen_units": null, + /* The debug information level as an integer. + `null` if it should use the compiler's default (0). + */ + "debuginfo": 2, + /* Whether or not debug-assertions are enabled. */ + "debug_assertions": true, + /* Whether or not overflow-checks are enabled. */ + "overflow_checks": true, + /* Whether or not rpath is enabled. */ + "rpath": false, + /* Whether or not incremental is enabled. */ + "incremental": true, + /* The panic strategy, "unwind" or "abort". */ + "panic": "unwind" + }, + /* Which platform this target is being built for. + A value of `null` indicates it is for the host. + Otherwise it is a string of the target triple (such as + "x86_64-unknown-linux-gnu"). + */ + "platform": null, + /* The "mode" for this unit. Valid values: + + * "test" --- Build using `rustc` as a test. + * "build" --- Build using `rustc`. + * "check" --- Build using `rustc` in "check" mode. + * "doc" --- Build using `rustdoc`. + * "doctest" --- Test using `rustdoc`. + * "run-custom-build" --- Represents the execution of a build script. + */ + "mode": "build", + /* Array of features enabled on this unit as strings. */ + "features": ["somefeat"], + /* Whether or not this is a standard-library unit, + part of the unstable build-std feature. + If not set, treat as `false`. + */ + "is_std": false, + /* Array of dependencies of this unit. */ + "dependencies": [ + { + /* Index in the "units" array for the dependency. */ + "index": 1, + /* The name that this dependency will be referred as. */ + "extern_crate_name": "unicode_xid", + /* Whether or not this dependency is "public", + part of the unstable public-dependency feature. + If not set, the public-dependency feature is not enabled. + */ + "public": false, + /* Whether or not this dependency is injected into the prelude, + currently used by the build-std feature. + If not set, treat as `false`. + */ + "noprelude": false + } + ] + }, + // ... + ], + /* Array of indices in the "units" array that are the "roots" of the + dependency graph. + */ + "roots": [0], +} +``` + +### Profile `rustflags` option +* Original Issue: [rust-lang/cargo#7878](https://github.com/rust-lang/cargo/issues/7878) +* Tracking Issue: [rust-lang/cargo#10271](https://github.com/rust-lang/cargo/issues/10271) + +This feature provides a new option in the `[profile]` section to specify flags +that are passed directly to rustc. +This can be enabled like so: + +```toml +cargo-features = ["profile-rustflags"] + +[package] +# ... + +[profile.release] +rustflags = [ "-C", "..." ] +``` + +To set this in a profile in Cargo configuration, you need to use either +`-Z profile-rustflags` or `[unstable]` table to enable it. For example, + +```toml +# .cargo/config.toml +[unstable] +profile-rustflags = true + +[profile.release] +rustflags = [ "-C", "..." ] +``` + +### rustdoc-map +* Tracking Issue: [#8296](https://github.com/rust-lang/cargo/issues/8296) + +This feature adds configuration settings that are passed to `rustdoc` so that +it can generate links to dependencies whose documentation is hosted elsewhere +when the dependency is not documented. First, add this to `.cargo/config`: + +```toml +[doc.extern-map.registries] +crates-io = "https://docs.rs/" +``` + +Then, when building documentation, use the following flags to cause links +to dependencies to link to [docs.rs](https://docs.rs/): + +``` +cargo +nightly doc --no-deps -Zrustdoc-map +``` + +The `registries` table contains a mapping of registry name to the URL to link +to. The URL may have the markers `{pkg_name}` and `{version}` which will get +replaced with the corresponding values. If neither are specified, then Cargo +defaults to appending `{pkg_name}/{version}/` to the end of the URL. + +Another config setting is available to redirect standard library links. By +default, rustdoc creates links to <https://doc.rust-lang.org/nightly/>. To +change this behavior, use the `doc.extern-map.std` setting: + +```toml +[doc.extern-map] +std = "local" +``` + +A value of `"local"` means to link to the documentation found in the `rustc` +sysroot. If you are using rustup, this documentation can be installed with +`rustup component add rust-docs`. + +The default value is `"remote"`. + +The value may also take a URL for a custom location. + +### per-package-target +* Tracking Issue: [#9406](https://github.com/rust-lang/cargo/pull/9406) +* Original Pull Request: [#9030](https://github.com/rust-lang/cargo/pull/9030) +* Original Issue: [#7004](https://github.com/rust-lang/cargo/pull/7004) + +The `per-package-target` feature adds two keys to the manifest: +`package.default-target` and `package.forced-target`. The first makes +the package be compiled by default (ie. when no `--target` argument is +passed) for some target. The second one makes the package always be +compiled for the target. + +Example: + +```toml +[package] +forced-target = "wasm32-unknown-unknown" +``` + +In this example, the crate is always built for +`wasm32-unknown-unknown`, for instance because it is going to be used +as a plugin for a main program that runs on the host (or provided on +the command line) target. + +### artifact-dependencies + +* Tracking Issue: [#9096](https://github.com/rust-lang/cargo/pull/9096) +* Original Pull Request: [#9992](https://github.com/rust-lang/cargo/pull/9992) + +Allow Cargo packages to depend on `bin`, `cdylib`, and `staticlib` crates, +and use the artifacts built by those crates at compile time. + +Run `cargo` with `-Z bindeps` to enable this functionality. + +**Example:** use _cdylib_ artifact in build script + +The `Cargo.toml` in the consuming package, building the `bar` library as `cdylib` +for a specific build target… + +```toml +[build-dependencies] +bar = { artifact = "cdylib", version = "1.0", target = "wasm32-unknown-unknown" } +``` + +…along with the build script in `build.rs`. + +```rust +fn main() { + wasm::run_file(std::env::var("CARGO_CDYLIB_FILE_BAR").unwrap()); +} +``` + +**Example:** use _binary_ artifact and its library in a binary + +The `Cargo.toml` in the consuming package, building the `bar` binary for inclusion +as artifact while making it available as library as well… + +```toml +[dependencies] +bar = { artifact = "bin", version = "1.0", lib = true } +``` + +…along with the executable using `main.rs`. + +```rust +fn main() { + bar::init(); + command::run(env!("CARGO_BIN_FILE_BAR")); +} +``` + +### publish-timeout +* Tracking Issue: [11222](https://github.com/rust-lang/cargo/issues/11222) + +The `publish.timeout` key in a config file can be used to control how long +`cargo publish` waits between posting a package to the registry and it being +available in the local index. + +A timeout of `0` prevents any checks from occurring. The current default is +`60` seconds. + +It requires the `-Zpublish-timeout` command-line options to be set. + +```toml +# config.toml +[publish] +timeout = 300 # in seconds +``` + +### registry-auth +* Tracking Issue: [10474](https://github.com/rust-lang/cargo/issues/10474) +* RFC: [#3139](https://github.com/rust-lang/rfcs/pull/3139) + +Enables Cargo to include the authorization token for API requests, crate downloads +and sparse index updates by adding a configuration option to config.json +in the registry index. + +To use this feature, the registry server must include `"auth-required": true` in +`config.json`, and you must pass the `-Z registry-auth` flag on the Cargo command line. + +When using the sparse protocol, Cargo will attempt to fetch the `config.json` file before +fetching any other files. If the server responds with an HTTP 401, then Cargo will assume +that the registry requires authentication and re-attempt the request for `config.json` +with the authentication token included. + +On authentication failure (or missing authentication token) the server MAY include a +`WWW-Authenticate` header with a `Cargo login_url` challenge to indicate where the user +can go to get a token. + +``` +WWW-Authenticate: Cargo login_url="https://test-registry-login/me +``` + +This same flag is also used to enable asymmetric authentication tokens. +* Tracking Issue: [10519](https://github.com/rust-lang/cargo/issues/10519) +* RFC: [#3231](https://github.com/rust-lang/rfcs/pull/3231) + +Add support for Cargo to authenticate the user to registries without sending secrets over the network. + +In [`config.toml`](config.md) and `credentials.toml` files there is a field called `private-key`, which is a private key formatted in the secret [subset of `PASERK`](https://github.com/paseto-standard/paserk/blob/master/types/secret.md) and is used to sign asymmetric tokens + +A keypair can be generated with `cargo login --generate-keypair` which will: +- generate a public/private keypair in the currently recommended fashion. +- save the private key in `credentials.toml`. +- print the public key in [PASERK public](https://github.com/paseto-standard/paserk/blob/master/types/public.md) format. + +It is recommended that the `private-key` be saved in `credentials.toml`. It is also supported in `config.toml`, primarily so that it can be set using the associated environment variable, which is the recommended way to provide it in CI contexts. This setup is what we have for the `token` field for setting a secret token. + +There is also an optional field called `private-key-subject` which is a string chosen by the registry. +This string will be included as part of an asymmetric token and should not be secret. +It is intended for the rare use cases like "cryptographic proof that the central CA server authorized this action". Cargo requires it to be non-whitespace printable ASCII. Registries that need non-ASCII data should base64 encode it. + +Both fields can be set with `cargo login --registry=name --private-key --private-key-subject="subject"` which will prompt you to put in the key value. + +A registry can have at most one of `private-key`, `token`, or `credential-process` set. + +All PASETOs will include `iat`, the current time in ISO 8601 format. Cargo will include the following where appropriate: +- `sub` an optional, non-secret string chosen by the registry that is expected to be claimed with every request. The value will be the `private-key-subject` from the `config.toml` file. +- `mutation` if present, indicates that this request is a mutating operation (or a read-only operation if not present), must be one of the strings `publish`, `yank`, or `unyank`. + - `name` name of the crate related to this request. + - `vers` version string of the crate related to this request. + - `cksum` the SHA256 hash of the crate contents, as a string of 64 lowercase hexadecimal digits, must be present only when `mutation` is equal to `publish` +- `challenge` the challenge string received from a 401/403 from this server this session. Registries that issue challenges must track which challenges have been issued/used and never accept a given challenge more than once within the same validity period (avoiding the need to track every challenge ever issued). + +The "footer" (which is part of the signature) will be a JSON string in UTF-8 and include: +- `url` the RFC 3986 compliant URL where cargo got the config.json file, + - If this is a registry with an HTTP index, then this is the base URL that all index queries are relative to. + - If this is a registry with a GIT index, it is the URL Cargo used to clone the index. +- `kid` the identifier of the private key used to sign the request, using the [PASERK IDs](https://github.com/paseto-standard/paserk/blob/master/operations/ID.md) standard. + +PASETO includes the message that was signed, so the server does not have to reconstruct the exact string from the request in order to check the signature. The server does need to check that the signature is valid for the string in the PASETO and that the contents of that string matches the request. +If a claim should be expected for the request but is missing in the PASETO then the request must be rejected. + +### credential-process +* Tracking Issue: [#8933](https://github.com/rust-lang/cargo/issues/8933) +* RFC: [#2730](https://github.com/rust-lang/rfcs/pull/2730) + +The `credential-process` feature adds a config setting to fetch registry +authentication tokens by calling an external process. + +Token authentication is used by the [`cargo login`], [`cargo publish`], +[`cargo owner`], and [`cargo yank`] commands. Additionally, this feature adds +a new `cargo logout` command. + +To use this feature, you must pass the `-Z credential-process` flag on the +command-line. Additionally, you must remove any current tokens currently saved +in the [`credentials.toml` file] (which can be done with the new `logout` command). + +#### `credential-process` Configuration + +To configure which process to run to fetch the token, specify the process in +the `registry` table in a [config file]: + +```toml +[registry] +credential-process = "/usr/bin/cargo-creds" +``` + +If you want to use a different process for a specific registry, it can be +specified in the `registries` table: + +```toml +[registries.my-registry] +credential-process = "/usr/bin/cargo-creds" +``` + +The value can be a string with spaces separating arguments or it can be a TOML +array of strings. + +Command-line arguments allow special placeholders which will be replaced with +the corresponding value: + +* `{name}` --- The name of the registry. +* `{api_url}` --- The base URL of the registry API endpoints. +* `{action}` --- The authentication action (described below). + +Process names with the prefix `cargo:` are loaded from the `libexec` directory +next to cargo. Several experimental credential wrappers are included with +Cargo, and this provides convenient access to them: + +```toml +[registry] +credential-process = "cargo:macos-keychain" +``` + +The current wrappers are: + +* `cargo:macos-keychain`: Uses the macOS Keychain to store the token. +* `cargo:wincred`: Uses the Windows Credential Manager to store the token. +* `cargo:1password`: Uses the 1password `op` CLI to store the token. You must + install the `op` CLI from the [1password + website](https://1password.com/downloads/command-line/). You must run `op + signin` at least once with the appropriate arguments (such as `op signin + my.1password.com user@example.com`), unless you provide the sign-in-address + and email arguments. The master password will be required on each request + unless the appropriate `OP_SESSION` environment variable is set. It supports + the following command-line arguments: + * `--account`: The account shorthand name to use. + * `--vault`: The vault name to use. + * `--sign-in-address`: The sign-in-address, which is a web address such as `my.1password.com`. + * `--email`: The email address to sign in with. + +A wrapper is available for GNOME +[libsecret](https://wiki.gnome.org/Projects/Libsecret) to store tokens on +Linux systems. Due to build limitations, this wrapper is not available as a +pre-compiled binary. This can be built and installed manually. First, install +libsecret using your system package manager (for example, `sudo apt install +libsecret-1-dev`). Then build and install the wrapper with `cargo install +cargo-credential-gnome-secret`. +In the config, use a path to the binary like this: + +```toml +[registry] +credential-process = "cargo-credential-gnome-secret {action}" +``` + +#### `credential-process` Interface + +There are two different kinds of token processes that Cargo supports. The +simple "basic" kind will only be called by Cargo when it needs a token. This +is intended for simple and easy integration with password managers, that can +often use pre-existing tooling. The more advanced "Cargo" kind supports +different actions passed as a command-line argument. This is intended for more +pleasant integration experience, at the expense of requiring a Cargo-specific +process to glue to the password manager. Cargo will determine which kind is +supported by the `credential-process` definition. If it contains the +`{action}` argument, then it uses the advanced style, otherwise it assumes it +only supports the "basic" kind. + +##### Basic authenticator + +A basic authenticator is a process that returns a token on stdout. Newlines +will be trimmed. The process inherits the user's stdin and stderr. It should +exit 0 on success, and nonzero on error. + +With this form, [`cargo login`] and `cargo logout` are not supported and +return an error if used. + +##### Cargo authenticator + +The protocol between the Cargo and the process is very basic, intended to +ensure the credential process is kept as simple as possible. Cargo will +execute the process with the `{action}` argument indicating which action to +perform: + +* `store` --- Store the given token in secure storage. +* `get` --- Get a token from storage. +* `erase` --- Remove a token from storage. + +The `cargo login` command uses `store` to save a token. Commands that require +authentication, like `cargo publish`, uses `get` to retrieve a token. `cargo +logout` uses the `erase` command to remove a token. + +The process inherits the user's stderr, so the process can display messages. +Some values are passed in via environment variables (see below). The expected +interactions are: + +* `store` --- The token is sent to the process's stdin, terminated by a newline. + The process should store the token keyed off the registry name. If the + process fails, it should exit with a nonzero exit status. + +* `get` --- The process should send the token to its stdout (trailing newline + will be trimmed). The process inherits the user's stdin, should it need to + receive input. + + If the process is unable to fulfill the request, it should exit with a + nonzero exit code. + +* `erase` --- The process should remove the token associated with the registry + name. If the token is not found, the process should exit with a 0 exit + status. + +##### Environment + +The following environment variables will be provided to the executed command: + +* `CARGO` --- Path to the `cargo` binary executing the command. +* `CARGO_REGISTRY_INDEX_URL` --- The URL of the registry index. +* `CARGO_REGISTRY_NAME_OPT` --- Optional name of the registry. Should not be used as a storage key. Not always available. + +#### `cargo logout` + +A new `cargo logout` command has been added to make it easier to remove a +token from storage. This supports both [`credentials.toml` file] tokens and +`credential-process` tokens. + +When used with `credentials.toml` file tokens, it needs the `-Z unstable-options` +command-line option: + +```console +cargo logout -Z unstable-options +``` + +When used with the `credential-process` config, use the `-Z +credential-process` command-line option: + + +```console +cargo logout -Z credential-process +``` + +[`cargo login`]: ../commands/cargo-login.md +[`cargo publish`]: ../commands/cargo-publish.md +[`cargo owner`]: ../commands/cargo-owner.md +[`cargo yank`]: ../commands/cargo-yank.md +[`credentials.toml` file]: config.md#credentials +[crates.io]: https://crates.io/ +[config file]: config.md + +### `cargo config` + +* Original Issue: [#2362](https://github.com/rust-lang/cargo/issues/2362) +* Tracking Issue: [#9301](https://github.com/rust-lang/cargo/issues/9301) + +The `cargo config` subcommand provides a way to display the configuration +files that cargo loads. It currently includes the `get` subcommand which +can take an optional config value to display. + +```console +cargo +nightly -Zunstable-options config get build.rustflags +``` + +If no config value is included, it will display all config values. See the +`--help` output for more options available. + +### `doctest-in-workspace` + +* Tracking Issue: [#9427](https://github.com/rust-lang/cargo/issues/9427) + +The `-Z doctest-in-workspace` flag changes the behavior of the current working +directory used when running doctests. Historically, Cargo has run `rustdoc +--test` relative to the root of the package, with paths relative from that +root. However, this is inconsistent with how `rustc` and `rustdoc` are +normally run in a workspace, where they are run relative to the workspace +root. This inconsistency causes problems in various ways, such as when passing +RUSTDOCFLAGS with relative paths, or dealing with diagnostic output. + +The `-Z doctest-in-workspace` flag causes cargo to switch to running `rustdoc` +from the root of the workspace. It also passes the `--test-run-directory` to +`rustdoc` so that when *running* the tests, they are run from the root of the +package. This preserves backwards compatibility and is consistent with how +normal unittests are run. + +### rustc `--print` + +* Tracking Issue: [#9357](https://github.com/rust-lang/cargo/issues/9357) + +`cargo rustc --print=VAL` forwards the `--print` flag to `rustc` in order to +extract information from `rustc`. This runs `rustc` with the corresponding +[`--print`](https://doc.rust-lang.org/rustc/command-line-arguments.html#--print-print-compiler-information) +flag, and then immediately exits without compiling. Exposing this as a cargo +flag allows cargo to inject the correct target and RUSTFLAGS based on the +current configuration. + +The primary use case is to run `cargo rustc --print=cfg` to get config values +for the appropriate target and influenced by any other RUSTFLAGS. + + +### Different binary name + +* Tracking Issue: [#9778](https://github.com/rust-lang/cargo/issues/9778) +* PR: [#9627](https://github.com/rust-lang/cargo/pull/9627) + +The `different-binary-name` feature allows setting the filename of the binary without having to obey the +restrictions placed on crate names. For example, the crate name must use only `alphanumeric` characters +or `-` or `_`, and cannot be empty. + +The `filename` parameter should **not** include the binary extension, `cargo` will figure out the appropriate +extension and use that for the binary on its own. + +The `filename` parameter is only available in the `[[bin]]` section of the manifest. + +```toml +cargo-features = ["different-binary-name"] + +[package] +name = "foo" +version = "0.0.1" + +[[bin]] +name = "foo" +filename = "007bar" +path = "src/main.rs" +``` + +### scrape-examples + +* RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123) +* Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910) + +The `-Z rustdoc-scrape-examples` flag tells Rustdoc to search crates in the current workspace +for calls to functions. Those call-sites are then included as documentation. You can use the flag +like this: + +``` +cargo doc -Z unstable-options -Z rustdoc-scrape-examples +``` + +By default, Cargo will scrape examples from the example targets of packages being documented. +You can individually enable or disable targets from being scraped with the `doc-scrape-examples` flag, such as: + +```toml +# Enable scraping examples from a library +[lib] +doc-scrape-examples = true + +# Disable scraping examples from an example target +[[example]] +name = "my-example" +doc-scrape-examples = false +``` + +**Note on tests:** enabling `doc-scrape-examples` on test targets will not currently have any effect. Scraping +examples from tests is a work-in-progress. + +**Note on dev-dependencies:** documenting a library does not normally require the crate's dev-dependencies. However, +example targets require dev-deps. For backwards compatibility, `-Z rustdoc-scrape-examples` will *not* introduce a +dev-deps requirement for `cargo doc`. Therefore examples will *not* be scraped from example targets under the +following conditions: + +1. No target being documented requires dev-deps, AND +2. At least one crate with targets being documented has dev-deps, AND +3. The `doc-scrape-examples` parameter is unset or false for all `[[example]]` targets. + +If you want examples to be scraped from example targets, then you must not satisfy one of the above conditions. +For example, you can set `doc-scrape-examples` to true for one example target, and that signals to Cargo that +you are ok with dev-deps being build for `cargo doc`. + + +### check-cfg + +* RFC: [#3013](https://github.com/rust-lang/rfcs/pull/3013) +* Tracking Issue: [#10554](https://github.com/rust-lang/cargo/issues/10554) + +`-Z check-cfg` command line enables compile time checking of name and values in `#[cfg]`, `cfg!`, +`#[link]` and `#[cfg_attr]` with the `rustc` and `rustdoc` unstable `--check-cfg` command line. + +It's values are: + - `features`: enables features checking via `--check-cfg=values(feature, ...)`. + Note than this command line options will probably become the default when stabilizing. + - `names`: enables well known names checking via `--check-cfg=names()`. + - `values`: enables well known values checking via `--check-cfg=values()`. + - `output`: enable the use of `rustc-check-cfg` in build script. + +For instance: + +``` +cargo check -Z unstable-options -Z check-cfg=features +cargo check -Z unstable-options -Z check-cfg=names +cargo check -Z unstable-options -Z check-cfg=values +cargo check -Z unstable-options -Z check-cfg=features,names,values +``` + +Or for `output`: + +```rust,no_run +// build.rs +println!("cargo:rustc-check-cfg=names(foo, bar)"); +``` + +``` +cargo check -Z unstable-options -Z check-cfg=output +``` + +### `cargo:rustc-check-cfg=CHECK_CFG` + +The `rustc-check-cfg` instruction tells Cargo to pass the given value to the +`--check-cfg` flag to the compiler. This may be used for compile-time +detection of unexpected conditional compilation name and/or values. + +This can only be used in combination with `-Zcheck-cfg=output` otherwise it is ignored +with a warning. + +If you want to integrate with Cargo features, use `-Zcheck-cfg=features` instead of +trying to do it manually with this option. + +### codegen-backend + +The `codegen-backend` feature makes it possible to select the codegen backend used by rustc using a profile. + +Example: + +```toml +[package] +name = "foo" + +[dependencies] +serde = "1.0.117" + +[profile.dev.package.foo] +codegen-backend = "cranelift" +``` + +To set this in a profile in Cargo configuration, you need to use either +`-Z codegen-backend` or `[unstable]` table to enable it. For example, + +```toml +# .cargo/config.toml +[unstable] +codegen-backend = true + +[profile.dev.package.foo] +codegen-backend = "cranelift" +``` + +## Stabilized and removed features + +### Compile progress + +The compile-progress feature has been stabilized in the 1.30 release. +Progress bars are now enabled by default. +See [`term.progress`](config.md#termprogresswhen) for more information about +controlling this feature. + +### Edition + +Specifying the `edition` in `Cargo.toml` has been stabilized in the 1.31 release. +See [the edition field](manifest.md#the-edition-field) for more information +about specifying this field. + +### rename-dependency + +Specifying renamed dependencies in `Cargo.toml` has been stabilized in the 1.31 release. +See [renaming dependencies](specifying-dependencies.md#renaming-dependencies-in-cargotoml) +for more information about renaming dependencies. + +### Alternate Registries + +Support for alternate registries has been stabilized in the 1.34 release. +See the [Registries chapter](registries.md) for more information about alternate registries. + +### Offline Mode + +The offline feature has been stabilized in the 1.36 release. +See the [`--offline` flag](../commands/cargo.md#option-cargo---offline) for +more information on using the offline mode. + +### publish-lockfile + +The `publish-lockfile` feature has been removed in the 1.37 release. +The `Cargo.lock` file is always included when a package is published if the +package contains a binary target. `cargo install` requires the `--locked` flag +to use the `Cargo.lock` file. +See [`cargo package`](../commands/cargo-package.md) and +[`cargo install`](../commands/cargo-install.md) for more information. + +### default-run + +The `default-run` feature has been stabilized in the 1.37 release. +See [the `default-run` field](manifest.md#the-default-run-field) for more +information about specifying the default target to run. + +### cache-messages + +Compiler message caching has been stabilized in the 1.40 release. +Compiler warnings are now cached by default and will be replayed automatically +when re-running Cargo. + +### install-upgrade + +The `install-upgrade` feature has been stabilized in the 1.41 release. +[`cargo install`] will now automatically upgrade packages if they appear to be +out-of-date. See the [`cargo install`] documentation for more information. + +[`cargo install`]: ../commands/cargo-install.md + +### Profile Overrides + +Profile overrides have been stabilized in the 1.41 release. +See [Profile Overrides](profiles.md#overrides) for more information on using +overrides. + +### Config Profiles + +Specifying profiles in Cargo config files and environment variables has been +stabilized in the 1.43 release. +See the [config `[profile]` table](config.md#profile) for more information +about specifying [profiles](profiles.md) in config files. + +### crate-versions + +The `-Z crate-versions` flag has been stabilized in the 1.47 release. +The crate version is now automatically included in the +[`cargo doc`](../commands/cargo-doc.md) documentation sidebar. + +### Features + +The `-Z features` flag has been stabilized in the 1.51 release. +See [feature resolver version 2](features.md#feature-resolver-version-2) +for more information on using the new feature resolver. + +### package-features + +The `-Z package-features` flag has been stabilized in the 1.51 release. +See the [resolver version 2 command-line flags](features.md#resolver-version-2-command-line-flags) +for more information on using the features CLI options. + +### Resolver + +The `resolver` feature in `Cargo.toml` has been stabilized in the 1.51 release. +See the [resolver versions](resolver.md#resolver-versions) for more +information about specifying resolvers. + +### extra-link-arg + +The `extra-link-arg` feature to specify additional linker arguments in build +scripts has been stabilized in the 1.56 release. See the [build script +documentation](build-scripts.md#outputs-of-the-build-script) for more +information on specifying extra linker arguments. + +### configurable-env + +The `configurable-env` feature to specify environment variables in Cargo +configuration has been stabilized in the 1.56 release. See the [config +documentation](config.html#env) for more information about configuring +environment variables. + +### rust-version + +The `rust-version` field in `Cargo.toml` has been stabilized in the 1.56 release. +See the [rust-version field](manifest.html#the-rust-version-field) for more +information on using the `rust-version` field and the `--ignore-rust-version` option. + +### patch-in-config + +The `-Z patch-in-config` flag, and the corresponding support for +`[patch]` section in Cargo configuration files has been stabilized in +the 1.56 release. See the [patch field](config.html#patch) for more +information. + +### edition 2021 + +The 2021 edition has been stabilized in the 1.56 release. +See the [`edition` field](manifest.md#the-edition-field) for more information on setting the edition. +See [`cargo fix --edition`](../commands/cargo-fix.md) and [The Edition Guide](../../edition-guide/index.html) for more information on migrating existing projects. + + +### Custom named profiles + +Custom named profiles have been stabilized in the 1.57 release. See the +[profiles chapter](profiles.md#custom-profiles) for more information. + +### Profile `strip` option + +The profile `strip` option has been stabilized in the 1.59 release. See the +[profiles chapter](profiles.md#strip) for more information. + +### Future incompat report + +Support for generating a future-incompat report has been stabilized +in the 1.59 release. See the [future incompat report chapter](future-incompat-report.md) +for more information. + +### Namespaced features + +Namespaced features has been stabilized in the 1.60 release. +See the [Features chapter](features.md#optional-dependencies) for more information. + +### Weak dependency features + +Weak dependency features has been stabilized in the 1.60 release. +See the [Features chapter](features.md#dependency-features) for more information. + +### timings + +The `-Ztimings` option has been stabilized as `--timings` in the 1.60 release. +(`--timings=html` and the machine-readable `--timings=json` output remain +unstable and require `-Zunstable-options`.) + +### config-cli + +The `--config` CLI option has been stabilized in the 1.63 release. See +the [config documentation](config.html#command-line-overrides) for more +information. + +### multitarget + +The `-Z multitarget` option has been stabilized in the 1.64 release. +See [`build.target`](config.md#buildtarget) for more information about +setting the default [target platform triples][target triple]. + +### crate-type + +The `--crate-type` flag for `cargo rustc` has been stabilized in the 1.64 +release. See the [`cargo rustc` documentation](../commands/cargo-rustc.md) +for more information. + + +### Workspace Inheritance + +Workspace Inheritance has been stabilized in the 1.64 release. +See [workspace.package](workspaces.md#the-package-table), +[workspace.dependencies](workspaces.md#the-dependencies-table), +and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace) +for more information. + +### terminal-width + +The `-Z terminal-width` option has been stabilized in the 1.68 release. +The terminal width is always passed to the compiler when running from a +terminal where Cargo can automatically detect the width. + +### sparse-registry + +Sparse registry support has been stabilized in the 1.68 release. +See [Registry Protocols](registries.md#registry-protocols) for more information. + +[target triple]: ../appendix/glossary.md#target '"target" (glossary)' diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md new file mode 100644 index 0000000..21f8f08 --- /dev/null +++ b/src/doc/src/reference/workspaces.md @@ -0,0 +1,255 @@ +## Workspaces + +A *workspace* is a collection of one or more packages, called *workspace +members*, that are managed together. + +The key points of workspaces are: + +* Common commands can run across all workspace members, like `cargo check --workspace`. +* All packages share a common [`Cargo.lock`] file which resides in the + *workspace root*. +* All packages share a common [output directory], which defaults to a + directory named `target` in the *workspace root*. +* Sharing package metadata, like with [`workspace.package`](#the-package-table). +* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles] + sections in `Cargo.toml` are only recognized in the *root* manifest, and + ignored in member crates' manifests. + +In the `Cargo.toml`, the `[workspace]` table supports the following sections: + +* [`[workspace]`](#the-workspace-section) --- Defines a workspace. + * [`resolver`](resolver.md#resolver-versions) --- Sets the dependency resolver to use. + * [`members`](#the-members-and-exclude-fields) --- Packages to include in the workspace. + * [`exclude`](#the-members-and-exclude-fields) --- Packages to exclude from the workspace. + * [`default-members`](#the-default-members-field) --- Packages to operate on when a specific package wasn't selected. + * [`package`](#the-package-table) --- Keys for inheriting in packages. + * [`dependencies`](#the-dependencies-table) --- Keys for inheriting in package dependencies. + * [`metadata`](#the-metadata-table) --- Extra settings for external tools. +* [`[patch]`](overriding-dependencies.md#the-patch-section) --- Override dependencies. +* [`[replace]`](overriding-dependencies.md#the-replace-section) --- Override dependencies (deprecated). +* [`[profile]`](profiles.md) --- Compiler settings and optimizations. + +### The `[workspace]` section + +To create a workspace, you add the `[workspace]` table to a `Cargo.toml`: +```toml +[workspace] +# ... +``` + +At minimum, a workspace has to have a member, either with a root package or as +a virtual manifest. + +#### Root package + +If the [`[workspace]` section](#the-workspace-section) is added to a +`Cargo.toml` that already defines a `[package]`, the package is +the *root package* of the workspace. The *workspace root* is the directory +where the workspace's `Cargo.toml` is located. + +```toml +[workspace] + +[package] +name = "hello_world" # the name of the package +version = "0.1.0" # the current version, obeying semver +authors = ["Alice <a@example.com>", "Bob <b@example.com>"] +``` + +<a id="virtual-manifest"></a> +#### Virtual workspace + +Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section +but without a [`[package]` section][package]. This is called a *virtual +manifest*. This is typically useful when there isn't a "primary" package, or +you want to keep all the packages organized in separate directories. + +```toml +# [PROJECT_DIR]/Cargo.toml +[workspace] +members = ["hello_world"] +``` + +```toml +# [PROJECT_DIR]/hello_world/Cargo.toml +[package] +name = "hello_world" # the name of the package +version = "0.1.0" # the current version, obeying semver +authors = ["Alice <a@example.com>", "Bob <b@example.com>"] +``` + +### The `members` and `exclude` fields + +The `members` and `exclude` fields define which packages are members of +the workspace: + +```toml +[workspace] +members = ["member1", "path/to/member2", "crates/*"] +exclude = ["crates/foo", "path/to/other"] +``` + +All [`path` dependencies] residing in the workspace directory automatically +become members. Additional members can be listed with the `members` key, which +should be an array of strings containing directories with `Cargo.toml` files. + +The `members` list also supports [globs] to match multiple paths, using +typical filename glob patterns like `*` and `?`. + +The `exclude` key can be used to prevent paths from being included in a +workspace. This can be useful if some path dependencies aren't desired to be +in the workspace at all, or using a glob pattern and you want to remove a +directory. + +When inside a subdirectory within the workspace, Cargo will automatically +search the parent directories for a `Cargo.toml` file with a `[workspace]` +definition to determine which workspace to use. The [`package.workspace`] +manifest key can be used in member crates to point at a workspace's root to +override this automatic search. The manual setting can be useful if the member +is not inside a subdirectory of the workspace root. + +#### Package selection + +In a workspace, package-related Cargo commands like [`cargo build`] can use +the `-p` / `--package` or `--workspace` command-line flags to determine which +packages to operate on. If neither of those flags are specified, Cargo will +use the package in the current working directory. If the current directory is +a [virtual workspace](#virtual-workspace), it will apply to all members (as if +`--workspace` were specified on the command-line). See also +[`default-members`](#the-default-members-field). + +### The `default-members` field + +The optional `default-members` key can be specified to set the members to +operate on when in the workspace root and the package selection flags are not +used: + +```toml +[workspace] +members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] +default-members = ["path/to/member2", "path/to/member3/foo"] +``` + +When specified, `default-members` must expand to a subset of `members`. + +### The `package` table + +The `workspace.package` table is where you define keys that can be +inherited by members of a workspace. These keys can be inherited by +defining them in the member package with `{key}.workspace = true`. + +Keys that are supported: + +| | | +|----------------|-----------------| +| `authors` | `categories` | +| `description` | `documentation` | +| `edition` | `exclude` | +| `homepage` | `include` | +| `keywords` | `license` | +| `license-file` | `publish` | +| `readme` | `repository` | +| `rust-version` | `version` | + +- `license-file` and `readme` are relative to the workspace root +- `include` and `exclude` are relative to your package root + +Example: +```toml +# [PROJECT_DIR]/Cargo.toml +[workspace] +members = ["bar"] + +[workspace.package] +version = "1.2.3" +authors = ["Nice Folks"] +description = "A short description of my package" +documentation = "https://example.com/bar" +``` + +```toml +# [PROJECT_DIR]/bar/Cargo.toml +[package] +name = "bar" +version.workspace = true +authors.workspace = true +description.workspace = true +documentation.workspace = true +``` + +### The `dependencies` table + +The `workspace.dependencies` table is where you define dependencies to be +inherited by members of a workspace. + +Specifying a workspace dependency is similar to [package dependencies][specifying-dependencies] except: +- Dependencies from this table cannot be declared as `optional` +- [`features`][features] declared in this table are additive with the `features` from `[dependencies]` + +You can then [inherit the workspace dependency as a package dependency][inheriting-a-dependency-from-a-workspace] + +Example: +```toml +# [PROJECT_DIR]/Cargo.toml +[workspace] +members = ["bar"] + +[workspace.dependencies] +cc = "1.0.73" +rand = "0.8.5" +regex = { version = "1.6.0", default-features = false, features = ["std"] } +``` + +```toml +# [PROJECT_DIR]/bar/Cargo.toml +[package] +name = "bar" +version = "0.2.0" + +[dependencies] +regex = { workspace = true, features = ["unicode"] } + +[build-dependencies] +cc.workspace = true + +[dev-dependencies] +rand.workspace = true +``` + +### The `metadata` table + +The `workspace.metadata` table is ignored by Cargo and will not be warned +about. This section can be used for tools that would like to store workspace +configuration in `Cargo.toml`. For example: + +```toml +[workspace] +members = ["member1", "member2"] + +[workspace.metadata.webcontents] +root = "path/to/webproject" +tool = ["npm", "run", "build"] +# ... +``` + +There is a similar set of tables at the package level at +[`package.metadata`][package-metadata]. While cargo does not specify a +format for the content of either of these tables, it is suggested that +external tools may wish to use them in a consistent fashion, such as referring +to the data in `workspace.metadata` if data is missing from `package.metadata`, +if that makes sense for the tool in question. + +[package]: manifest.md#the-package-section +[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md +[package-metadata]: manifest.md#the-metadata-table +[output directory]: ../guide/build-cache.md +[patch]: overriding-dependencies.md#the-patch-section +[replace]: overriding-dependencies.md#the-replace-section +[profiles]: profiles.md +[`path` dependencies]: specifying-dependencies.md#specifying-path-dependencies +[`package.workspace`]: manifest.md#the-workspace-field +[globs]: https://docs.rs/glob/0.3.0/glob/struct.Pattern.html +[`cargo build`]: ../commands/cargo-build.md +[specifying-dependencies]: specifying-dependencies.md +[features]: features.md +[inheriting-a-dependency-from-a-workspace]: specifying-dependencies.md#inheriting-a-dependency-from-a-workspace diff --git a/src/doc/theme/favicon.png b/src/doc/theme/favicon.png Binary files differnew file mode 100644 index 0000000..47c8f62 --- /dev/null +++ b/src/doc/theme/favicon.png diff --git a/src/doc/theme/head.hbs b/src/doc/theme/head.hbs new file mode 100644 index 0000000..062417e --- /dev/null +++ b/src/doc/theme/head.hbs @@ -0,0 +1,5 @@ +<style> + dd { + margin-bottom: 1em; + } +</style> |
