From 31538550a97a4db7d8dbd9f27712693f176325be Mon Sep 17 00:00:00 2001 From: Enyium <123484196+Enyium@users.noreply.github.com> Date: Tue, 7 Feb 2023 01:40:29 +0100 Subject: [PATCH] Ensure em dashes are recognizable in markup. --- src/doc/contrib/src/architecture/codebase.md | 52 ++-- src/doc/contrib/src/architecture/packages.md | 16 +- src/doc/contrib/src/issues.md | 10 +- src/doc/contrib/src/tests/writing.md | 16 +- src/doc/man/cargo-add.md | 2 +- src/doc/man/cargo-bench.md | 4 +- src/doc/man/cargo-build.md | 2 +- src/doc/man/cargo-check.md | 2 +- src/doc/man/cargo-clean.md | 2 +- src/doc/man/cargo-doc.md | 2 +- src/doc/man/cargo-fetch.md | 2 +- src/doc/man/cargo-fix.md | 2 +- src/doc/man/cargo-generate-lockfile.md | 2 +- src/doc/man/cargo-help.md | 2 +- src/doc/man/cargo-init.md | 2 +- src/doc/man/cargo-install.md | 2 +- src/doc/man/cargo-locate-project.md | 2 +- src/doc/man/cargo-login.md | 2 +- src/doc/man/cargo-metadata.md | 2 +- src/doc/man/cargo-new.md | 2 +- src/doc/man/cargo-owner.md | 2 +- src/doc/man/cargo-package.md | 2 +- src/doc/man/cargo-pkgid.md | 2 +- src/doc/man/cargo-publish.md | 2 +- src/doc/man/cargo-remove.md | 2 +- src/doc/man/cargo-report.md | 4 +- src/doc/man/cargo-run.md | 2 +- src/doc/man/cargo-rustc.md | 8 +- src/doc/man/cargo-rustdoc.md | 2 +- src/doc/man/cargo-search.md | 2 +- src/doc/man/cargo-test.md | 6 +- src/doc/man/cargo-tree.md | 36 +-- src/doc/man/cargo-uninstall.md | 2 +- src/doc/man/cargo-update.md | 2 +- src/doc/man/cargo-vendor.md | 2 +- src/doc/man/cargo-verify-project.md | 2 +- src/doc/man/cargo-version.md | 2 +- src/doc/man/cargo-yank.md | 2 +- src/doc/man/cargo.md | 2 +- src/doc/src/appendix/glossary.md | 24 +- src/doc/src/commands/cargo-add.md | 2 +- src/doc/src/commands/cargo-bench.md | 4 +- src/doc/src/commands/cargo-build.md | 2 +- src/doc/src/commands/cargo-check.md | 2 +- src/doc/src/commands/cargo-clean.md | 2 +- src/doc/src/commands/cargo-doc.md | 2 +- src/doc/src/commands/cargo-fetch.md | 2 +- src/doc/src/commands/cargo-fix.md | 2 +- .../src/commands/cargo-generate-lockfile.md | 2 +- src/doc/src/commands/cargo-help.md | 2 +- src/doc/src/commands/cargo-init.md | 2 +- src/doc/src/commands/cargo-install.md | 2 +- src/doc/src/commands/cargo-locate-project.md | 2 +- src/doc/src/commands/cargo-login.md | 2 +- src/doc/src/commands/cargo-metadata.md | 2 +- src/doc/src/commands/cargo-new.md | 2 +- src/doc/src/commands/cargo-owner.md | 2 +- src/doc/src/commands/cargo-package.md | 2 +- src/doc/src/commands/cargo-pkgid.md | 2 +- src/doc/src/commands/cargo-publish.md | 2 +- src/doc/src/commands/cargo-remove.md | 2 +- src/doc/src/commands/cargo-report.md | 4 +- src/doc/src/commands/cargo-run.md | 2 +- src/doc/src/commands/cargo-rustc.md | 8 +- src/doc/src/commands/cargo-rustdoc.md | 2 +- src/doc/src/commands/cargo-search.md | 2 +- src/doc/src/commands/cargo-test.md | 6 +- src/doc/src/commands/cargo-tree.md | 36 +-- src/doc/src/commands/cargo-uninstall.md | 2 +- src/doc/src/commands/cargo-update.md | 2 +- src/doc/src/commands/cargo-vendor.md | 2 +- src/doc/src/commands/cargo-verify-project.md | 2 +- src/doc/src/commands/cargo-version.md | 2 +- src/doc/src/commands/cargo-yank.md | 2 +- src/doc/src/commands/cargo.md | 2 +- src/doc/src/index.md | 6 +- .../src/reference/build-script-examples.md | 10 +- src/doc/src/reference/build-scripts.md | 32 +-- .../src/reference/environment-variables.md | 240 +++++++++--------- src/doc/src/reference/features.md | 2 +- src/doc/src/reference/manifest.md | 90 +++---- src/doc/src/reference/profiles.md | 8 +- src/doc/src/reference/resolver.md | 2 +- src/doc/src/reference/semver.md | 6 +- src/doc/src/reference/source-replacement.md | 4 +- .../src/reference/specifying-dependencies.md | 4 +- src/doc/src/reference/timings.md | 6 +- src/doc/src/reference/unstable.md | 102 ++++---- src/doc/src/reference/workspaces.md | 22 +- 89 files changed, 444 insertions(+), 444 deletions(-) diff --git a/src/doc/contrib/src/architecture/codebase.md b/src/doc/contrib/src/architecture/codebase.md index 7e3b077fa92b..45c6e0e2f1d0 100644 --- a/src/doc/contrib/src/architecture/codebase.md +++ b/src/doc/contrib/src/architecture/codebase.md @@ -3,73 +3,73 @@ 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 + --- 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 + --- 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 + --- 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. + --- 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`. + --- 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 + --- 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 + --- 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 + --- 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. + --- 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. + --- 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 + --- 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. + --- 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. + --- 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. + --- 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. + --- 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. + --- A collection of independent crates used by Cargo. ## Extra crates @@ -77,32 +77,32 @@ 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. + --- 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 + --- 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 + --- 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 + --- 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. + --- 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 + --- 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. +* [`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 +* [`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 + --- This is a dedicated package that defines tests for the [dependency resolver](../architecture/packages.md#resolver). diff --git a/src/doc/contrib/src/architecture/packages.md b/src/doc/contrib/src/architecture/packages.md index dc7deefbb8d8..626714bf4689 100644 --- a/src/doc/contrib/src/architecture/packages.md +++ b/src/doc/contrib/src/architecture/packages.md @@ -16,27 +16,27 @@ actually compiled by `rustc`. 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 +* [`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 + * [`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 + * [`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 +* [`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 +* [`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. diff --git a/src/doc/contrib/src/issues.md b/src/doc/contrib/src/issues.md index 30e2d8316f2b..8fc69544c618 100644 --- a/src/doc/contrib/src/issues.md +++ b/src/doc/contrib/src/issues.md @@ -26,11 +26,11 @@ 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. +* [`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 diff --git a/src/doc/contrib/src/tests/writing.md b/src/doc/contrib/src/tests/writing.md index 51fc6a74e531..b08d8b925419 100644 --- a/src/doc/contrib/src/tests/writing.md +++ b/src/doc/contrib/src/tests/writing.md @@ -77,34 +77,34 @@ They are listed in parentheses separated with commas, such as: The options it supports are: -* `nightly` — This will cause the test to be ignored if not running on the nightly toolchain. +* `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). +* `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). +* `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. +* `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. +* `>=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. +* `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. +* `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. +* `ignore_windows="reason"` --- Indicates that the test should be ignored on windows for the given reason. #### Testing Nightly Features diff --git a/src/doc/man/cargo-add.md b/src/doc/man/cargo-add.md index cca9fb5b47f0..07f8fd225d71 100644 --- a/src/doc/man/cargo-add.md +++ b/src/doc/man/cargo-add.md @@ -4,7 +4,7 @@ ## NAME -cargo-add - Add dependencies to a Cargo.toml manifest file +cargo-add --- Add dependencies to a Cargo.toml manifest file ## SYNOPSIS diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index 1155ac50b92c..32c98dadaebe 100644 --- a/src/doc/man/cargo-bench.md +++ b/src/doc/man/cargo-bench.md @@ -5,7 +5,7 @@ ## NAME -cargo-bench - Execute benchmarks of a package +cargo-bench --- Execute benchmarks of a package ## SYNOPSIS @@ -69,7 +69,7 @@ debugger. 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 +- lib --- used to link with binaries and benchmarks - bins (only if benchmark targets are built and required features are available) - lib as a benchmark diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md index 3b71ae6a3171..98614444323c 100644 --- a/src/doc/man/cargo-build.md +++ b/src/doc/man/cargo-build.md @@ -4,7 +4,7 @@ ## NAME -cargo-build - Compile the current package +cargo-build --- Compile the current package ## SYNOPSIS diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md index 44a3d0fdc4d9..055adff0d087 100644 --- a/src/doc/man/cargo-check.md +++ b/src/doc/man/cargo-check.md @@ -4,7 +4,7 @@ ## NAME -cargo-check - Check the current package +cargo-check --- Check the current package ## SYNOPSIS diff --git a/src/doc/man/cargo-clean.md b/src/doc/man/cargo-clean.md index be1fa1fce454..3222f7bb04b3 100644 --- a/src/doc/man/cargo-clean.md +++ b/src/doc/man/cargo-clean.md @@ -4,7 +4,7 @@ ## NAME -cargo-clean - Remove generated artifacts +cargo-clean --- Remove generated artifacts ## SYNOPSIS diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md index f8f517d9ae70..9d5b77648935 100644 --- a/src/doc/man/cargo-doc.md +++ b/src/doc/man/cargo-doc.md @@ -4,7 +4,7 @@ ## NAME -cargo-doc - Build a package's documentation +cargo-doc --- Build a package's documentation ## SYNOPSIS diff --git a/src/doc/man/cargo-fetch.md b/src/doc/man/cargo-fetch.md index 69ce103cae30..c31166a9b51c 100644 --- a/src/doc/man/cargo-fetch.md +++ b/src/doc/man/cargo-fetch.md @@ -5,7 +5,7 @@ ## NAME -cargo-fetch - Fetch dependencies of a package from the network +cargo-fetch --- Fetch dependencies of a package from the network ## SYNOPSIS diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md index e78ae34fd2e0..64fe299446c6 100644 --- a/src/doc/man/cargo-fix.md +++ b/src/doc/man/cargo-fix.md @@ -4,7 +4,7 @@ ## NAME -cargo-fix - Automatically fix lint warnings reported by rustc +cargo-fix --- Automatically fix lint warnings reported by rustc ## SYNOPSIS diff --git a/src/doc/man/cargo-generate-lockfile.md b/src/doc/man/cargo-generate-lockfile.md index a2b963cef440..3a2f52b39449 100644 --- a/src/doc/man/cargo-generate-lockfile.md +++ b/src/doc/man/cargo-generate-lockfile.md @@ -2,7 +2,7 @@ ## NAME -cargo-generate-lockfile - Generate the lockfile for a package +cargo-generate-lockfile --- Generate the lockfile for a package ## SYNOPSIS diff --git a/src/doc/man/cargo-help.md b/src/doc/man/cargo-help.md index edd8bc0cb1a0..4a5a8f51575c 100644 --- a/src/doc/man/cargo-help.md +++ b/src/doc/man/cargo-help.md @@ -2,7 +2,7 @@ ## NAME -cargo-help - Get help for a Cargo command +cargo-help --- Get help for a Cargo command ## SYNOPSIS diff --git a/src/doc/man/cargo-init.md b/src/doc/man/cargo-init.md index bdb5a82702e6..cd8e623ca1ca 100644 --- a/src/doc/man/cargo-init.md +++ b/src/doc/man/cargo-init.md @@ -2,7 +2,7 @@ ## NAME -cargo-init - Create a new Cargo package in an existing directory +cargo-init --- Create a new Cargo package in an existing directory ## SYNOPSIS diff --git a/src/doc/man/cargo-install.md b/src/doc/man/cargo-install.md index 118e3efdf038..56922bfc0c23 100644 --- a/src/doc/man/cargo-install.md +++ b/src/doc/man/cargo-install.md @@ -4,7 +4,7 @@ ## NAME -cargo-install - Build and install a Rust binary +cargo-install --- Build and install a Rust binary ## SYNOPSIS diff --git a/src/doc/man/cargo-locate-project.md b/src/doc/man/cargo-locate-project.md index 87cf9919f528..4ebf36d7d7c6 100644 --- a/src/doc/man/cargo-locate-project.md +++ b/src/doc/man/cargo-locate-project.md @@ -2,7 +2,7 @@ ## NAME -cargo-locate-project - Print a JSON representation of a Cargo.toml file's location +cargo-locate-project --- Print a JSON representation of a Cargo.toml file's location ## SYNOPSIS diff --git a/src/doc/man/cargo-login.md b/src/doc/man/cargo-login.md index 0e361ab74a04..11c663c46c6d 100644 --- a/src/doc/man/cargo-login.md +++ b/src/doc/man/cargo-login.md @@ -2,7 +2,7 @@ ## NAME -cargo-login - Save an API token from the registry locally +cargo-login --- Save an API token from the registry locally ## SYNOPSIS diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index 5197f03c2002..4f9032d56cca 100644 --- a/src/doc/man/cargo-metadata.md +++ b/src/doc/man/cargo-metadata.md @@ -2,7 +2,7 @@ ## NAME -cargo-metadata - Machine-readable metadata about the current package +cargo-metadata --- Machine-readable metadata about the current package ## SYNOPSIS diff --git a/src/doc/man/cargo-new.md b/src/doc/man/cargo-new.md index d0ca91812243..ea6182ac37dc 100644 --- a/src/doc/man/cargo-new.md +++ b/src/doc/man/cargo-new.md @@ -2,7 +2,7 @@ ## NAME -cargo-new - Create a new Cargo package +cargo-new --- Create a new Cargo package ## SYNOPSIS diff --git a/src/doc/man/cargo-owner.md b/src/doc/man/cargo-owner.md index 3787a4de0456..327916968874 100644 --- a/src/doc/man/cargo-owner.md +++ b/src/doc/man/cargo-owner.md @@ -2,7 +2,7 @@ ## NAME -cargo-owner - Manage the owners of a crate on the registry +cargo-owner --- Manage the owners of a crate on the registry ## SYNOPSIS diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md index d7f35c6234c8..2000353cc473 100644 --- a/src/doc/man/cargo-package.md +++ b/src/doc/man/cargo-package.md @@ -5,7 +5,7 @@ ## NAME -cargo-package - Assemble the local package into a distributable tarball +cargo-package --- Assemble the local package into a distributable tarball ## SYNOPSIS diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md index 761eede1dce7..47ed133f9b53 100644 --- a/src/doc/man/cargo-pkgid.md +++ b/src/doc/man/cargo-pkgid.md @@ -2,7 +2,7 @@ ## NAME -cargo-pkgid - Print a fully qualified package specification +cargo-pkgid --- Print a fully qualified package specification ## SYNOPSIS diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md index 560e3c104728..4ccb5b5298a8 100644 --- a/src/doc/man/cargo-publish.md +++ b/src/doc/man/cargo-publish.md @@ -4,7 +4,7 @@ ## NAME -cargo-publish - Upload a package to the registry +cargo-publish --- Upload a package to the registry ## SYNOPSIS diff --git a/src/doc/man/cargo-remove.md b/src/doc/man/cargo-remove.md index b0150c1414eb..0722e6e53de2 100644 --- a/src/doc/man/cargo-remove.md +++ b/src/doc/man/cargo-remove.md @@ -4,7 +4,7 @@ ## NAME -cargo-remove - Remove dependencies from a Cargo.toml manifest file +cargo-remove --- Remove dependencies from a Cargo.toml manifest file ## SYNOPSIS diff --git a/src/doc/man/cargo-report.md b/src/doc/man/cargo-report.md index a505a014a33d..ba33617dbb0b 100644 --- a/src/doc/man/cargo-report.md +++ b/src/doc/man/cargo-report.md @@ -2,7 +2,7 @@ ## NAME -cargo-report - Generate and display various kinds of reports +cargo-report --- Generate and display various kinds of reports ## SYNOPSIS @@ -10,7 +10,7 @@ cargo-report - Generate and display various kinds of reports ### DESCRIPTION -Displays a report of the given _type_ - currently, only `future-incompat` is supported +Displays a report of the given _type_ --- currently, only `future-incompat` is supported ## OPTIONS diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md index 4ec09f58da14..4b6b935242e2 100644 --- a/src/doc/man/cargo-run.md +++ b/src/doc/man/cargo-run.md @@ -3,7 +3,7 @@ ## NAME -cargo-run - Run the current package +cargo-run --- Run the current package ## SYNOPSIS diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md index 3ce5c193ab08..f3b37234c0ce 100644 --- a/src/doc/man/cargo-rustc.md +++ b/src/doc/man/cargo-rustc.md @@ -4,7 +4,7 @@ ## NAME -cargo-rustc - Compile the current package, and pass extra options to the compiler +cargo-rustc --- Compile the current package, and pass extra options to the compiler ## SYNOPSIS @@ -55,13 +55,13 @@ 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 +* `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, +* `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, +* `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. diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md index 6c38780f3244..23be579e9c63 100644 --- a/src/doc/man/cargo-rustdoc.md +++ b/src/doc/man/cargo-rustdoc.md @@ -4,7 +4,7 @@ ## NAME -cargo-rustdoc - Build a package's documentation, using specified custom flags +cargo-rustdoc --- Build a package's documentation, using specified custom flags ## SYNOPSIS diff --git a/src/doc/man/cargo-search.md b/src/doc/man/cargo-search.md index 5c7bcac3c2f3..f3d87cb12784 100644 --- a/src/doc/man/cargo-search.md +++ b/src/doc/man/cargo-search.md @@ -2,7 +2,7 @@ ## NAME -cargo-search - Search packages in crates.io +cargo-search --- Search packages in crates.io ## SYNOPSIS diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index 7419b5323979..0b6da16ca5ee 100644 --- a/src/doc/man/cargo-test.md +++ b/src/doc/man/cargo-test.md @@ -5,7 +5,7 @@ ## NAME -cargo-test - Execute unit and integration tests of a package +cargo-test --- Execute unit and integration tests of a package ## SYNOPSIS @@ -70,10 +70,10 @@ on writing doc tests. 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 +- 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 +- examples --- to ensure they compile - lib as a unit test - bins as unit tests - integration tests diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md index 51b1d9e0e14d..3e1da20df254 100644 --- a/src/doc/man/cargo-tree.md +++ b/src/doc/man/cargo-tree.md @@ -4,7 +4,7 @@ ## NAME -cargo-tree - Display a tree visualization of a dependency graph +cargo-tree --- Display a tree visualization of a dependency graph ## SYNOPSIS @@ -119,16 +119,16 @@ only one instance is built. {{#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 +- `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. +- `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. @@ -158,19 +158,19 @@ 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. +- `{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. +- `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}} diff --git a/src/doc/man/cargo-uninstall.md b/src/doc/man/cargo-uninstall.md index 73c50c7a1def..b2ebd097fc3a 100644 --- a/src/doc/man/cargo-uninstall.md +++ b/src/doc/man/cargo-uninstall.md @@ -2,7 +2,7 @@ ## NAME -cargo-uninstall - Remove a Rust binary +cargo-uninstall --- Remove a Rust binary ## SYNOPSIS diff --git a/src/doc/man/cargo-update.md b/src/doc/man/cargo-update.md index 54aa90ae8467..e91606a6a096 100644 --- a/src/doc/man/cargo-update.md +++ b/src/doc/man/cargo-update.md @@ -2,7 +2,7 @@ ## NAME -cargo-update - Update dependencies as recorded in the local lock file +cargo-update --- Update dependencies as recorded in the local lock file ## SYNOPSIS diff --git a/src/doc/man/cargo-vendor.md b/src/doc/man/cargo-vendor.md index 9fd977951e75..b30d0d8dd22b 100644 --- a/src/doc/man/cargo-vendor.md +++ b/src/doc/man/cargo-vendor.md @@ -2,7 +2,7 @@ ## NAME -cargo-vendor - Vendor all dependencies locally +cargo-vendor --- Vendor all dependencies locally ## SYNOPSIS diff --git a/src/doc/man/cargo-verify-project.md b/src/doc/man/cargo-verify-project.md index 99b749087b71..8b334fb14c58 100644 --- a/src/doc/man/cargo-verify-project.md +++ b/src/doc/man/cargo-verify-project.md @@ -2,7 +2,7 @@ ## NAME -cargo-verify-project - Check correctness of crate manifest +cargo-verify-project --- Check correctness of crate manifest ## SYNOPSIS diff --git a/src/doc/man/cargo-version.md b/src/doc/man/cargo-version.md index c6e4535323d0..9bbadc9ea501 100644 --- a/src/doc/man/cargo-version.md +++ b/src/doc/man/cargo-version.md @@ -2,7 +2,7 @@ ## NAME -cargo-version - Show version information +cargo-version --- Show version information ## SYNOPSIS diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md index 3b9185d6a65f..8ad28ef243f2 100644 --- a/src/doc/man/cargo-yank.md +++ b/src/doc/man/cargo-yank.md @@ -2,7 +2,7 @@ ## NAME -cargo-yank - Remove a pushed crate from the index +cargo-yank --- Remove a pushed crate from the index ## SYNOPSIS diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md index 9f2c622da085..2d71fc4d75cd 100644 --- a/src/doc/man/cargo.md +++ b/src/doc/man/cargo.md @@ -2,7 +2,7 @@ ## NAME -cargo - The Rust package manager +cargo --- The Rust package manager ## SYNOPSIS diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index 9ac0561e972b..143736851b56 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -107,7 +107,7 @@ 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 +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 @@ -162,14 +162,14 @@ 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 +- **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 +- **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 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 +- **Git source** --- Packages located in a git repository (such as a [git dependency] or [git source]). See [Source Replacement] for more information. @@ -182,21 +182,21 @@ See [package ID specification](#package). The meaning of the term *target* depends on the context: -- **Cargo Target** — Cargo [*packages*](#package) consist of *targets* which +- **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 +- **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 +- **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 +- **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 @@ -221,11 +221,11 @@ The meaning of the term *target* depends on the context: 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 +* **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 +* **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 diff --git a/src/doc/src/commands/cargo-add.md b/src/doc/src/commands/cargo-add.md index 3655384de8f1..a7bc7a965d34 100644 --- a/src/doc/src/commands/cargo-add.md +++ b/src/doc/src/commands/cargo-add.md @@ -4,7 +4,7 @@ ## NAME -cargo-add - Add dependencies to a Cargo.toml manifest file +cargo-add --- Add dependencies to a Cargo.toml manifest file ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index b0ecf2159b74..da71326bdf0c 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -5,7 +5,7 @@ ## NAME -cargo-bench - Execute benchmarks of a package +cargo-bench --- Execute benchmarks of a package ## SYNOPSIS @@ -126,7 +126,7 @@ single quotes or double quotes around each pattern. 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 +- lib --- used to link with binaries and benchmarks - bins (only if benchmark targets are built and required features are available) - lib as a benchmark diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 5e1fdd039a4f..b40958b60b60 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -4,7 +4,7 @@ ## NAME -cargo-build - Compile the current package +cargo-build --- Compile the current package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 82ba76ee39ff..cc15c257658f 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -4,7 +4,7 @@ ## NAME -cargo-check - Check the current package +cargo-check --- Check the current package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md index c7cd8fe52744..cfa8495ff829 100644 --- a/src/doc/src/commands/cargo-clean.md +++ b/src/doc/src/commands/cargo-clean.md @@ -4,7 +4,7 @@ ## NAME -cargo-clean - Remove generated artifacts +cargo-clean --- Remove generated artifacts ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 9258705b7488..f779aa3da657 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -4,7 +4,7 @@ ## NAME -cargo-doc - Build a package's documentation +cargo-doc --- Build a package's documentation ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md index 93e8aba3f260..e5977e93f0fa 100644 --- a/src/doc/src/commands/cargo-fetch.md +++ b/src/doc/src/commands/cargo-fetch.md @@ -5,7 +5,7 @@ ## NAME -cargo-fetch - Fetch dependencies of a package from the network +cargo-fetch --- Fetch dependencies of a package from the network ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index dccffd579ae9..4ca71c3bbe84 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -4,7 +4,7 @@ ## NAME -cargo-fix - Automatically fix lint warnings reported by rustc +cargo-fix --- Automatically fix lint warnings reported by rustc ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-generate-lockfile.md b/src/doc/src/commands/cargo-generate-lockfile.md index 9712cf663295..f603f73a4c0f 100644 --- a/src/doc/src/commands/cargo-generate-lockfile.md +++ b/src/doc/src/commands/cargo-generate-lockfile.md @@ -2,7 +2,7 @@ ## NAME -cargo-generate-lockfile - Generate the lockfile for a package +cargo-generate-lockfile --- Generate the lockfile for a package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md index a3bffb1674cb..db5cb342abf9 100644 --- a/src/doc/src/commands/cargo-help.md +++ b/src/doc/src/commands/cargo-help.md @@ -2,7 +2,7 @@ ## NAME -cargo-help - Get help for a Cargo command +cargo-help --- Get help for a Cargo command ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-init.md b/src/doc/src/commands/cargo-init.md index d2317c399ed5..2ab001631efe 100644 --- a/src/doc/src/commands/cargo-init.md +++ b/src/doc/src/commands/cargo-init.md @@ -2,7 +2,7 @@ ## NAME -cargo-init - Create a new Cargo package in an existing directory +cargo-init --- Create a new Cargo package in an existing directory ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index f1450a9333bd..9f31dde51c48 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -4,7 +4,7 @@ ## NAME -cargo-install - Build and install a Rust binary +cargo-install --- Build and install a Rust binary ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-locate-project.md b/src/doc/src/commands/cargo-locate-project.md index 3e42f3f073d4..5ac47b9b094d 100644 --- a/src/doc/src/commands/cargo-locate-project.md +++ b/src/doc/src/commands/cargo-locate-project.md @@ -2,7 +2,7 @@ ## NAME -cargo-locate-project - Print a JSON representation of a Cargo.toml file's location +cargo-locate-project --- Print a JSON representation of a Cargo.toml file's location ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-login.md b/src/doc/src/commands/cargo-login.md index 35fab6763d0d..96573fe502db 100644 --- a/src/doc/src/commands/cargo-login.md +++ b/src/doc/src/commands/cargo-login.md @@ -2,7 +2,7 @@ ## NAME -cargo-login - Save an API token from the registry locally +cargo-login --- Save an API token from the registry locally ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index 4bac638fdaac..d06959cb81be 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -2,7 +2,7 @@ ## NAME -cargo-metadata - Machine-readable metadata about the current package +cargo-metadata --- Machine-readable metadata about the current package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-new.md b/src/doc/src/commands/cargo-new.md index 0f4f8e7f3c38..d51309485f02 100644 --- a/src/doc/src/commands/cargo-new.md +++ b/src/doc/src/commands/cargo-new.md @@ -2,7 +2,7 @@ ## NAME -cargo-new - Create a new Cargo package +cargo-new --- Create a new Cargo package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-owner.md b/src/doc/src/commands/cargo-owner.md index 73df3cd99024..f6f493c52d71 100644 --- a/src/doc/src/commands/cargo-owner.md +++ b/src/doc/src/commands/cargo-owner.md @@ -2,7 +2,7 @@ ## NAME -cargo-owner - Manage the owners of a crate on the registry +cargo-owner --- Manage the owners of a crate on the registry ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index a58614c67892..5deb137d7a2a 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -5,7 +5,7 @@ ## NAME -cargo-package - Assemble the local package into a distributable tarball +cargo-package --- Assemble the local package into a distributable tarball ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md index 873881d8b577..420277fbf12f 100644 --- a/src/doc/src/commands/cargo-pkgid.md +++ b/src/doc/src/commands/cargo-pkgid.md @@ -2,7 +2,7 @@ ## NAME -cargo-pkgid - Print a fully qualified package specification +cargo-pkgid --- Print a fully qualified package specification ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md index a308c4dca05b..21e02e4b2ef8 100644 --- a/src/doc/src/commands/cargo-publish.md +++ b/src/doc/src/commands/cargo-publish.md @@ -4,7 +4,7 @@ ## NAME -cargo-publish - Upload a package to the registry +cargo-publish --- Upload a package to the registry ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-remove.md b/src/doc/src/commands/cargo-remove.md index 0a0024f5e838..429c22c2b021 100644 --- a/src/doc/src/commands/cargo-remove.md +++ b/src/doc/src/commands/cargo-remove.md @@ -4,7 +4,7 @@ ## NAME -cargo-remove - Remove dependencies from a Cargo.toml manifest file +cargo-remove --- Remove dependencies from a Cargo.toml manifest file ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-report.md b/src/doc/src/commands/cargo-report.md index 5df2303e6afc..c0eaa4b4234a 100644 --- a/src/doc/src/commands/cargo-report.md +++ b/src/doc/src/commands/cargo-report.md @@ -2,7 +2,7 @@ ## NAME -cargo-report - Generate and display various kinds of reports +cargo-report --- Generate and display various kinds of reports ## SYNOPSIS @@ -10,7 +10,7 @@ cargo-report - Generate and display various kinds of reports ### DESCRIPTION -Displays a report of the given _type_ - currently, only `future-incompat` is supported +Displays a report of the given _type_ --- currently, only `future-incompat` is supported ## OPTIONS diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 43fcc026b84d..cf8e349e822d 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -3,7 +3,7 @@ ## NAME -cargo-run - Run the current package +cargo-run --- Run the current package ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 606ce7785163..c5aeec37f17e 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -4,7 +4,7 @@ ## NAME -cargo-rustc - Compile the current package, and pass extra options to the compiler +cargo-rustc --- Compile the current package, and pass extra options to the compiler ## SYNOPSIS @@ -190,13 +190,13 @@ See also the --profile option for choosing a specific profile by na
Build with the given profile.

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

See the the reference for more details on profiles.

diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index c8b6ecf97e5e..e1512361dff9 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -4,7 +4,7 @@ ## NAME -cargo-rustdoc - Build a package's documentation, using specified custom flags +cargo-rustdoc --- Build a package's documentation, using specified custom flags ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-search.md b/src/doc/src/commands/cargo-search.md index 78dfa290f8df..94a42e694988 100644 --- a/src/doc/src/commands/cargo-search.md +++ b/src/doc/src/commands/cargo-search.md @@ -2,7 +2,7 @@ ## NAME -cargo-search - Search packages in crates.io +cargo-search --- Search packages in crates.io ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 69e9a5ae4e9d..b154d48be916 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -5,7 +5,7 @@ ## NAME -cargo-test - Execute unit and integration tests of a package +cargo-test --- Execute unit and integration tests of a package ## SYNOPSIS @@ -127,10 +127,10 @@ single quotes or double quotes around each pattern. 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 +- 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 +- examples --- to ensure they compile - lib as a unit test - bins as unit tests - integration tests diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md index 9b1fde0eb118..34f3cf6648f4 100644 --- a/src/doc/src/commands/cargo-tree.md +++ b/src/doc/src/commands/cargo-tree.md @@ -4,7 +4,7 @@ ## NAME -cargo-tree - Display a tree visualization of a dependency graph +cargo-tree --- Display a tree visualization of a dependency graph ## SYNOPSIS @@ -120,16 +120,16 @@ only one instance is built.
--edges kinds
The dependency kinds to display. Takes a comma separated list of values:

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

@@ -158,20 +158,20 @@ The default is the host platform. Use the value all to include

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

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

diff --git a/src/doc/src/commands/cargo-uninstall.md b/src/doc/src/commands/cargo-uninstall.md index 5d2561a19c9c..766c0ce7edca 100644 --- a/src/doc/src/commands/cargo-uninstall.md +++ b/src/doc/src/commands/cargo-uninstall.md @@ -2,7 +2,7 @@ ## NAME -cargo-uninstall - Remove a Rust binary +cargo-uninstall --- Remove a Rust binary ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md index cbea81b3b9a7..a51970ec2d58 100644 --- a/src/doc/src/commands/cargo-update.md +++ b/src/doc/src/commands/cargo-update.md @@ -2,7 +2,7 @@ ## NAME -cargo-update - Update dependencies as recorded in the local lock file +cargo-update --- Update dependencies as recorded in the local lock file ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-vendor.md b/src/doc/src/commands/cargo-vendor.md index 194107265da9..5111ddb188dc 100644 --- a/src/doc/src/commands/cargo-vendor.md +++ b/src/doc/src/commands/cargo-vendor.md @@ -2,7 +2,7 @@ ## NAME -cargo-vendor - Vendor all dependencies locally +cargo-vendor --- Vendor all dependencies locally ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-verify-project.md b/src/doc/src/commands/cargo-verify-project.md index 2e44fedac210..a0616574b0fc 100644 --- a/src/doc/src/commands/cargo-verify-project.md +++ b/src/doc/src/commands/cargo-verify-project.md @@ -2,7 +2,7 @@ ## NAME -cargo-verify-project - Check correctness of crate manifest +cargo-verify-project --- Check correctness of crate manifest ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-version.md b/src/doc/src/commands/cargo-version.md index 1ceacf81113a..e9e12a05f792 100644 --- a/src/doc/src/commands/cargo-version.md +++ b/src/doc/src/commands/cargo-version.md @@ -2,7 +2,7 @@ ## NAME -cargo-version - Show version information +cargo-version --- Show version information ## SYNOPSIS diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md index ec68e7ca9f35..93ade449b228 100644 --- a/src/doc/src/commands/cargo-yank.md +++ b/src/doc/src/commands/cargo-yank.md @@ -2,7 +2,7 @@ ## NAME -cargo-yank - Remove a pushed crate from the index +cargo-yank --- Remove a pushed crate from the index ## SYNOPSIS diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index 683133838f85..7c3fb23fdb73 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -2,7 +2,7 @@ ## NAME -cargo - The Rust package manager +cargo --- The Rust package manager ## SYNOPSIS diff --git a/src/doc/src/index.md b/src/doc/src/index.md index 7085149295ab..223600c8b3db 100644 --- a/src/doc/src/index.md +++ b/src/doc/src/index.md @@ -35,9 +35,9 @@ The commands will let you interact with Cargo using its command-line interface. * [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 +* [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)' diff --git a/src/doc/src/reference/build-script-examples.md b/src/doc/src/reference/build-script-examples.md index bf49aeb1b74a..5e8fae5bbd80 100644 --- a/src/doc/src/reference/build-script-examples.md +++ b/src/doc/src/reference/build-script-examples.md @@ -7,15 +7,15 @@ 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 +* [`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 +* [`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. +* [`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 + [`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. diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 0385ec5cb50e..00023b6c2bb6 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -99,36 +99,36 @@ 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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`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 +* [`cargo:rustc-flags=FLAGS`](#rustc-flags) --- Passes certain flags to the compiler. -* [`cargo:rustc-cfg=KEY[="VALUE"]`](#rustc-cfg) — Enables compile-time `cfg` +* [`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 +* [`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 +* [`cargo:warning=MESSAGE`](#cargo-warning) --- Displays a warning on the terminal. -* [`cargo:KEY=VALUE`](#the-links-manifest-key) — Metadata, used by `links` +* [`cargo:KEY=VALUE`](#the-links-manifest-key) --- Metadata, used by `links` scripts. diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 1675b3770c42..7647a6e42517 100644 --- a/src/doc/src/reference/environment-variables.md +++ b/src/doc/src/reference/environment-variables.md @@ -9,73 +9,73 @@ with them: 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. +* `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 +* `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, +* `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 +* `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 +* `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 +* `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 +* `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` --- 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` +* `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` +* `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 +* `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` +* `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 +* `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 +* `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 +* `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 +* `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 +* `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`, +* `RUSTFMT` --- Instead of running `rustfmt`, [`cargo fmt`](https://github.com/rust-lang/rustfmt) will execute this specified `rustfmt` instance instead. @@ -85,56 +85,56 @@ 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_` — 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__BUILD_OVERRIDE_` — Override build script profile, see [`profile..build-override`]. -* `CARGO_PROFILE__CODEGEN_UNITS` — Set code generation units, see [`profile..codegen-units`]. -* `CARGO_PROFILE__DEBUG` — What kind of debug info to include, see [`profile..debug`]. -* `CARGO_PROFILE__DEBUG_ASSERTIONS` — Enable/disable debug assertions, see [`profile..debug-assertions`]. -* `CARGO_PROFILE__INCREMENTAL` — Enable/disable incremental compilation, see [`profile..incremental`]. -* `CARGO_PROFILE__LTO` — Link-time optimization, see [`profile..lto`]. -* `CARGO_PROFILE__OVERFLOW_CHECKS` — Enable/disable overflow checks, see [`profile..overflow-checks`]. -* `CARGO_PROFILE__OPT_LEVEL` — Set the optimization level, see [`profile..opt-level`]. -* `CARGO_PROFILE__PANIC` — The panic strategy to use, see [`profile..panic`]. -* `CARGO_PROFILE__RPATH` — The rpath linking option, see [`profile..rpath`]. -* `CARGO_PROFILE__SPLIT_DEBUGINFO` — Controls debug file output behavior, see [`profile..split-debuginfo`]. -* `CARGO_REGISTRIES__INDEX` — URL of a registry index, see [`registries..index`]. -* `CARGO_REGISTRIES__TOKEN` — Authentication token of a registry, see [`registries..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__LINKER` — The linker to use, see [`target..linker`]. The triple must be [converted to uppercase and underscores](config.md#environment-variables). -* `CARGO_TARGET__RUNNER` — The executable runner, see [`target..runner`]. -* `CARGO_TARGET__RUSTFLAGS` — Extra `rustc` flags for a target, see [`target..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_ALIAS_` --- 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__BUILD_OVERRIDE_` --- Override build script profile, see [`profile..build-override`]. +* `CARGO_PROFILE__CODEGEN_UNITS` --- Set code generation units, see [`profile..codegen-units`]. +* `CARGO_PROFILE__DEBUG` --- What kind of debug info to include, see [`profile..debug`]. +* `CARGO_PROFILE__DEBUG_ASSERTIONS` --- Enable/disable debug assertions, see [`profile..debug-assertions`]. +* `CARGO_PROFILE__INCREMENTAL` --- Enable/disable incremental compilation, see [`profile..incremental`]. +* `CARGO_PROFILE__LTO` --- Link-time optimization, see [`profile..lto`]. +* `CARGO_PROFILE__OVERFLOW_CHECKS` --- Enable/disable overflow checks, see [`profile..overflow-checks`]. +* `CARGO_PROFILE__OPT_LEVEL` --- Set the optimization level, see [`profile..opt-level`]. +* `CARGO_PROFILE__PANIC` --- The panic strategy to use, see [`profile..panic`]. +* `CARGO_PROFILE__RPATH` --- The rpath linking option, see [`profile..rpath`]. +* `CARGO_PROFILE__SPLIT_DEBUGINFO` --- Controls debug file output behavior, see [`profile..split-debuginfo`]. +* `CARGO_REGISTRIES__INDEX` --- URL of a registry index, see [`registries..index`]. +* `CARGO_REGISTRIES__TOKEN` --- Authentication token of a registry, see [`registries..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__LINKER` --- The linker to use, see [`target..linker`]. The triple must be [converted to uppercase and underscores](config.md#environment-variables). +* `CARGO_TARGET__RUNNER` --- The executable runner, see [`target..runner`]. +* `CARGO_TARGET__RUSTFLAGS` --- Extra `rustc` flags for a target, see [`target..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 @@ -214,42 +214,42 @@ let version = env!("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. +* `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 (if it is a binary). 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 +* `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 (if it is a binary). 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_` — The absolute path to a binary target's executable. +* `CARGO_BIN_EXE_` --- 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 `` 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 +* `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. +* `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 @@ -299,14 +299,14 @@ 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 +* `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] +* `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 @@ -315,11 +315,11 @@ let out_dir = env::var("OUT_DIR").unwrap(); 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_` — For each activated feature of the package being +* `CARGO_FEATURE_` --- For each activated feature of the package being built, this environment variable will be present where `` is the name of the feature uppercased and having `-` translated to `_`. -* `CARGO_CFG_` — For each [configuration option][configuration] of the +* `CARGO_CFG_` --- For each [configuration option][configuration] of the package being built, this environment variable will contain the value of the configuration, where `` is the name of the configuration uppercased and having `-` translated to `_`. Boolean configurations are present if they are @@ -328,24 +328,24 @@ let out_dir = env::var("OUT_DIR").unwrap(); 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 + * `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 +* `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 +* `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 @@ -353,33 +353,33 @@ let out_dir = env::var("OUT_DIR").unwrap(); -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 +* `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 +* `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__` — For more information about this set of environment +* `DEP__` --- 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 +* `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. +* `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 +* `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 +* `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, +* `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_` - The package information variables, with the same names and values as are [provided during crate building][variables set for crates]. +* `CARGO_PKG_` --- 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 @@ -408,6 +408,6 @@ let out_dir = env::var("OUT_DIR").unwrap(); 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. +* `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/features.md b/src/doc/src/reference/features.md index cc86698d5902..40eb32c411d3 100644 --- a/src/doc/src/reference/features.md +++ b/src/doc/src/reference/features.md @@ -518,4 +518,4 @@ source and inspect it. 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. +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/manifest.md b/src/doc/src/reference/manifest.md index dc351a023108..954cfe674c9f 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -6,52 +6,52 @@ the `cargo locate-project` section for more detail on how cargo finds the manife 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. +* [`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. + * [`[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. + * [`[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. ### The `[package]` section @@ -116,7 +116,7 @@ breaking change. #### 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 +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. diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md index 5cc2a6f7f57c..56c8538f80b1 100644 --- a/src/doc/src/reference/profiles.md +++ b/src/doc/src/reference/profiles.md @@ -431,11 +431,11 @@ opt-level = 3 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 +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`. +4. `[profile.dev]` --- Settings in `Cargo.toml`. 5. Default values built-in to Cargo. Overrides cannot specify the `panic`, `lto`, or `rpath` settings. diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md index 1e78223dd22b..af02d6cf28b3 100644 --- a/src/doc/src/reference/resolver.md +++ b/src/doc/src/reference/resolver.md @@ -44,7 +44,7 @@ As a quick refresher, the dependencies is: Requirement | Example | Equivalence | Description ---|--------|--|------------- +------------|---------|-------------|------------- Caret | `1.2.3` or `^1.2.3` | >=1.2.3, <2.0.0 | Any SemVer-compatible version of at least the given value. Tilde | `~1.2` | >=1.2.0, <1.3.0 | Minimum version, with restricted compatibility range. Wildcard | `1.*` | >=1.0.0, <2.0.0 | Any version in the `*` position. diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md index 36482ff6e651..b7274c259cba 100644 --- a/src/doc/src/reference/semver.md +++ b/src/doc/src/reference/semver.md @@ -1197,9 +1197,9 @@ However, library authors should be cautious about introducing new warnings and m 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. +* [`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. diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md index 8edcd0fb90eb..b8bcdc7ae2be 100644 --- a/src/doc/src/reference/source-replacement.md +++ b/src/doc/src/reference/source-replacement.md @@ -8,11 +8,11 @@ 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 +* 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 +* 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 diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 45b537607d3b..8d9eac308b8a 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -2,7 +2,7 @@ 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, +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 @@ -136,7 +136,7 @@ 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 +(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 diff --git a/src/doc/src/reference/timings.md b/src/doc/src/reference/timings.md index 459794c455b4..9e6863306f48 100644 --- a/src/doc/src/reference/timings.md +++ b/src/doc/src/reference/timings.md @@ -30,11 +30,11 @@ 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 +- "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 +- "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. +- "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 diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 71c839ebb989..0b21118a88e5 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -60,45 +60,45 @@ Each new feature described below should explain how to use it. ### List of unstable features * Unstable-specific features - * [-Z allow-features](#allow-features) — Provides a way to restrict which unstable features are used. + * [-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. + * [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. + * [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. + * [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. + * [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/). + * [`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. + * [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. + * [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. + * [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. + * [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 @@ -362,9 +362,9 @@ 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 - - for implementation bugs -* The tracking repository - - - for larger design +* Cargo --- --- for implementation bugs +* The tracking repository --- + --- for larger design questions. Also if you'd like to see a feature that's not yet implemented and/or if @@ -620,12 +620,12 @@ The following is a description of the JSON structure: "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. + * "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. */ @@ -926,9 +926,9 @@ 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). +* `{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 @@ -999,9 +999,9 @@ 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. +* `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 @@ -1011,18 +1011,18 @@ 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. +* `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 +* `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 +* `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. @@ -1030,9 +1030,9 @@ interactions are: 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` --- 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` diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 004839eac7d5..fed53eb0da9b 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -17,17 +17,17 @@ The key points of workspaces are: 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. +* [`[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