diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index 143736851b5..9186b51c3bc 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -1,25 +1,25 @@ # Glossary -### Artifact +## Artifact An *artifact* is the file or set of files created as a result of the compilation process. This includes linkable libraries, executable binaries, and generated documentation. -### Cargo +## Cargo *Cargo* is the Rust [*package manager*](#package-manager), and the primary topic of this book. -### Cargo.lock +## Cargo.lock See [*lock file*](#lock-file). -### Cargo.toml +## Cargo.toml See [*manifest*](#manifest). -### Crate +## Crate A Rust *crate* is either a library or an executable program, referred to as either a *library crate* or a *binary crate*, respectively. @@ -32,14 +32,14 @@ compressed package fetched from a [registry](#registry). The source code for a given crate may be subdivided into [*modules*](#module). -### Edition +## Edition A *Rust edition* is a developmental landmark of the Rust language. The [edition of a package][edition-field] is specified in the `Cargo.toml` [manifest](#manifest), and individual targets can specify which edition they use. See the [Edition Guide] for more information. -### Feature +## Feature The meaning of *feature* depends on the context: @@ -58,19 +58,19 @@ The meaning of *feature* depends on the context: - CPU targets have [*target features*][target-feature] which specify capabilities of a CPU. -### Index +## Index The *index* is the searchable list of [*crates*](#crate) in a [*registry*](#registry). -### Lock file +## Lock file The `Cargo.lock` *lock file* is a file that captures the exact version of every dependency used in a [*workspace*](#workspace) or [*package*](#package). It is automatically generated by Cargo. See [Cargo.toml vs Cargo.lock]. -### Manifest +## Manifest A [*manifest*][manifest] is a description of a [package](#package) or a [workspace](#workspace) in a file named `Cargo.toml`. @@ -78,12 +78,12 @@ A [*manifest*][manifest] is a description of a [package](#package) or a A [*virtual manifest*][virtual] is a `Cargo.toml` file that only describes a workspace, and does not include a package. -### Member +## Member A *member* is a [*package*](#package) that belongs to a [*workspace*](#workspace). -### Module +## Module Rust's module system is used to organize code into logical units called *modules*, which provide isolated namespaces within the code. @@ -98,7 +98,7 @@ A [`Cargo.toml`](#manifest) file is primarily concerned with the which they depend. Nevertheless, you will see the term "module" often when working with Rust, so you should understand its relationship to a given crate. -### Package +## Package A *package* is a collection of source files and a `Cargo.toml` [*manifest*](#manifest) file which describes the package. A package has a name @@ -123,7 +123,7 @@ Larger projects may involve multiple packages, in which case Cargo [*workspaces*](#workspace) can be used to manage common dependencies and other related metadata between the packages. -### Package manager +## Package manager Broadly speaking, a *package manager* is a program (or collection of related programs) in a software ecosystem that automates the process of obtaining, @@ -139,15 +139,15 @@ downloads your Rust [package](#package)’s dependencies packages, makes distributable packages, and (optionally) uploads them to [crates.io][], the Rust community’s [*package registry*](#registry). -### Package registry +## Package registry See [*registry*](#registry). -### Project +## Project Another name for a [package](#package). -### Registry +## Registry A *registry* is a service that contains a collection of downloadable [*crates*](#crate) that can be installed or used as dependencies for a @@ -156,7 +156,7 @@ A *registry* is a service that contains a collection of downloadable contains a list of all crates, and tells Cargo how to download the crates that are needed. -### Source +## Source A *source* is a provider that contains [*crates*](#crate) that may be included as dependencies for a [*package*](#package). There are several kinds of @@ -174,11 +174,11 @@ sources: See [Source Replacement] for more information. -### Spec +## Spec See [package ID specification](#package). -### Target +## Target The meaning of the term *target* depends on the context: @@ -216,7 +216,7 @@ The meaning of the term *target* depends on the context: Some parameters may be omitted. Run `rustc --print target-list` for a list of supported targets. -### Test Targets +## Test Targets Cargo *test targets* generate binaries which help verify proper operation and correctness of code. There are two types of test artifacts: @@ -232,7 +232,7 @@ correctness of code. There are two types of test artifacts: `Cargo.toml` [*manifest*](#manifest). It is intended to only test the public API of a library, or execute a binary to verify its operation. -### Workspace +## Workspace A [*workspace*][workspace] is a collection of one or more [*packages*](#package) that share common dependency resolution (with a shared diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md index f8a758babe0..9d4a982d047 100644 --- a/src/doc/src/faq.md +++ b/src/doc/src/faq.md @@ -1,6 +1,6 @@ -## Frequently Asked Questions +# Frequently Asked Questions -### Is the plan to use GitHub as a package repository? +## Is the plan to use GitHub as a package repository? No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with [npmjs.com][1] and [rubygems.org][3]. @@ -9,7 +9,7 @@ We plan to support git repositories as a source of packages forever, because they can be used for early development and temporary patches, even when people use the registry as the primary source of packages. -### Why build crates.io rather than use GitHub as a registry? +## Why build crates.io rather than use GitHub as a registry? We think that it’s very important to support multiple ways to download packages, including downloading from GitHub and copying packages into @@ -43,7 +43,7 @@ languages include: down fast. Also remember that not everybody has a high-speed, low-latency Internet connection. -### Will Cargo work with C code (or other languages)? +## Will Cargo work with C code (or other languages)? Yes! @@ -56,7 +56,7 @@ Our solution: Cargo allows a package to [specify a script](reference/build-scrip implement platform-specific configuration and refactor out common build functionality among packages. -### Can Cargo be used inside of `make` (or `ninja`, or ...) +## Can Cargo be used inside of `make` (or `ninja`, or ...) Indeed. While we intend Cargo to be useful as a standalone way to compile Rust packages at the top-level, we know that some people will @@ -68,7 +68,7 @@ have some work to do on those fronts, but using Cargo in the context of conventional scripts is something we designed for from the beginning and will continue to prioritize. -### Does Cargo handle multi-platform packages or cross-compilation? +## Does Cargo handle multi-platform packages or cross-compilation? Rust itself provides facilities for configuring sections of code based on the platform. Cargo also supports [platform-specific @@ -80,7 +80,7 @@ configuration in `Cargo.toml` in the future. In the longer-term, we’re looking at ways to conveniently cross-compile packages using Cargo. -### Does Cargo support environments, like `production` or `test`? +## Does Cargo support environments, like `production` or `test`? We support environments through the use of [profiles] to support: @@ -92,7 +92,7 @@ We support environments through the use of [profiles] to support: * environment-specific `#[cfg]` * a `cargo test` command -### Does Cargo work on Windows? +## Does Cargo work on Windows? Yes! @@ -102,7 +102,7 @@ issue][cargo-issues]. [cargo-issues]: https://github.com/rust-lang/cargo/issues -### Why have `Cargo.lock` in version control? +## Why have `Cargo.lock` in version control? While [`cargo new`] defaults to tracking `Cargo.lock` in version control, whether you do is dependent on the needs of your package. @@ -144,7 +144,7 @@ see [Verifying Latest Dependencies](guide/continuous-integration.md#verifying-la [`cargo add`]: commands/cargo-add.md [`cargo install`]: commands/cargo-install.md -### Can libraries use `*` as a version for their dependencies? +## Can libraries use `*` as a version for their dependencies? **As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries) with wildcard dependency constraints.** @@ -154,7 +154,7 @@ of `*` says “This will work with every version ever”, which is never going to be true. Libraries should always specify the range that they do work with, even if it’s something as general as “every 1.x.y version”. -### Why `Cargo.toml`? +## Why `Cargo.toml`? As one of the most frequent interactions with Cargo, the question of why the configuration file is named `Cargo.toml` arises from time to time. The leading @@ -172,7 +172,7 @@ but others were accidentally forgotten. [crates.io]: https://crates.io/ -### How can Cargo work offline? +## How can Cargo work offline? Cargo is often used in situations with limited or no network access such as airplanes, CI environments, or embedded in large production deployments. Users @@ -216,7 +216,7 @@ replacement][replace]. [`cargo fetch`]: commands/cargo-fetch.md [offline config]: reference/config.md#netoffline -### Why is Cargo rebuilding my code? +## Why is Cargo rebuilding my code? Cargo is responsible for incrementally compiling crates in your project. This means that if you type `cargo build` twice the second one shouldn't rebuild your @@ -274,7 +274,7 @@ If after trying to debug your issue, however, you're still running into problems then feel free to [open an issue](https://github.com/rust-lang/cargo/issues/new)! -### What does "version conflict" mean and how to resolve it? +## What does "version conflict" mean and how to resolve it? > failed to select a version for `x` which could resolve this conflict diff --git a/src/doc/src/getting-started/first-steps.md b/src/doc/src/getting-started/first-steps.md index 15bb4bdc7ab..e8ed21d1571 100644 --- a/src/doc/src/getting-started/first-steps.md +++ b/src/doc/src/getting-started/first-steps.md @@ -1,4 +1,4 @@ -## First Steps with Cargo +# First Steps with Cargo This section provides a quick sense for the `cargo` command line tool. We demonstrate its ability to generate a new [***package***][def-package] for us, @@ -73,7 +73,7 @@ $ cargo run Hello, world! ``` -### Going further +## Going further For more details on using Cargo, check out the [Cargo Guide](../guide/index.md) diff --git a/src/doc/src/getting-started/index.md b/src/doc/src/getting-started/index.md index 710e9943bfe..30eca72ef8e 100644 --- a/src/doc/src/getting-started/index.md +++ b/src/doc/src/getting-started/index.md @@ -1,4 +1,4 @@ -## Getting Started +# Getting Started To get started with Cargo, install Cargo (and Rust) and set up your first [*crate*][def-crate]. diff --git a/src/doc/src/getting-started/installation.md b/src/doc/src/getting-started/installation.md index 7cccf9ee5ae..21ba2fd4c23 100644 --- a/src/doc/src/getting-started/installation.md +++ b/src/doc/src/getting-started/installation.md @@ -1,6 +1,6 @@ -## Installation +# Installation -### Install Rust and Cargo +## Install Rust and Cargo The easiest way to get Cargo is to install the current stable release of [Rust] by using [rustup]. Installing Rust using `rustup` will also install `cargo`. @@ -27,7 +27,7 @@ channels for Rust and Cargo. For other installation options and information, visit the [install][install-rust] page of the Rust website. -### Build and Install Cargo from Source +## Build and Install Cargo from Source Alternatively, you can [build Cargo from source][compiling-from-source]. diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index a79b41dbaa1..d351fc15893 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -1,4 +1,4 @@ -## Build cache +# Build cache Cargo stores the output of a build into the "target" directory. By default, this is the directory named `target` in the root of your @@ -63,7 +63,7 @@ Directory | Description target/debug/incremental/ | `rustc` [incremental output], a cache used to speed up subsequent builds. target/debug/build/ | Output from [build scripts]. -### Dep-info files +## Dep-info files Next to each compiled artifact is a file called a "dep info" file with a `.d` suffix. This file is a Makefile-like syntax that indicates all of the file @@ -77,7 +77,7 @@ re-executed. The paths in the file are absolute by default. See the /path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs ``` -### Shared cache +## Shared cache A third party tool, [sccache], can be used to share built dependencies across different workspaces. diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md index 9e6740f1040..33e3f00a146 100644 --- a/src/doc/src/guide/cargo-home.md +++ b/src/doc/src/guide/cargo-home.md @@ -1,4 +1,4 @@ -## Cargo Home +# Cargo Home The "Cargo home" functions as a download and source cache. When building a [crate][def-crate], Cargo stores downloaded build dependencies in the Cargo home. diff --git a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md index e6f6e135dd4..21f52dca119 100644 --- a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md +++ b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md @@ -1,4 +1,4 @@ -## Cargo.toml vs Cargo.lock +# Cargo.toml vs Cargo.lock `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk about them, here’s a summary: diff --git a/src/doc/src/guide/continuous-integration.md b/src/doc/src/guide/continuous-integration.md index 13f6c30abbb..e2ec3bc25e2 100644 --- a/src/doc/src/guide/continuous-integration.md +++ b/src/doc/src/guide/continuous-integration.md @@ -1,10 +1,10 @@ -## Continuous Integration +# Continuous Integration -### Getting Started +## Getting Started A basic CI will build and test your projects: -### GitHub Actions +## GitHub Actions To test your package on GitHub Actions, here is a sample `.github/workflows/ci.yml` file: @@ -38,7 +38,7 @@ jobs: This will test all three release channels (note a failure in any toolchain version will fail the entire job). You can also click `"Actions" > "new workflow"` in the GitHub UI and select Rust to add the [default configuration](https://github.com/actions/starter-workflows/blob/main/ci/rust.yml) to your repo. See [GitHub Actions documentation](https://docs.github.com/en/actions) for more information. -### GitLab CI +## GitLab CI To test your package on GitLab CI, here is a sample `.gitlab-ci.yml` file: @@ -67,7 +67,7 @@ breakage in nightly will not fail your overall build. Please see the [GitLab CI documentation](https://docs.gitlab.com/ce/ci/yaml/index.html) for more information. -### builds.sr.ht +## builds.sr.ht To test your package on sr.ht, here is a sample `.build.yml` file. Be sure to change `` and `` to the repo to clone and @@ -105,7 +105,7 @@ channel, but any breakage in nightly will not fail your overall build. Please see the [builds.sr.ht documentation](https://man.sr.ht/builds.sr.ht/) for more information. -### Verifying Latest Dependencies +## Verifying Latest Dependencies When [specifying dependencies](../reference/specifying-dependencies.md) in `Cargo.toml`, they generally match a range of versions. diff --git a/src/doc/src/guide/creating-a-new-project.md b/src/doc/src/guide/creating-a-new-project.md index e0daefc6b0b..49fbc088032 100644 --- a/src/doc/src/guide/creating-a-new-project.md +++ b/src/doc/src/guide/creating-a-new-project.md @@ -1,4 +1,4 @@ -## Creating a New Package +# Creating a New Package To start a new [package][def-package] with Cargo, use `cargo new`: diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md index 94419f15b7a..cbb3ba115d0 100644 --- a/src/doc/src/guide/dependencies.md +++ b/src/doc/src/guide/dependencies.md @@ -1,4 +1,4 @@ -## Dependencies +# Dependencies [crates.io] is the Rust community's central [*package registry*][def-package-registry] that serves as a location to discover and download @@ -9,7 +9,7 @@ To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. [crates.io]: https://crates.io/ -### Adding a dependency +## Adding a dependency If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that, then list the [crate][def-crate] name and version that you would like to diff --git a/src/doc/src/guide/index.md b/src/doc/src/guide/index.md index fe6d86a3921..00fe2320cc2 100644 --- a/src/doc/src/guide/index.md +++ b/src/doc/src/guide/index.md @@ -1,4 +1,4 @@ -## Cargo Guide +# Cargo Guide This guide will give you all that you need to know about how to use Cargo to develop Rust packages. diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md index a3ce3f8a704..c4360af019c 100644 --- a/src/doc/src/guide/project-layout.md +++ b/src/doc/src/guide/project-layout.md @@ -1,4 +1,4 @@ -## Package Layout +# Package Layout Cargo uses conventions for file placement to make it easy to dive into a new Cargo [package][def-package]: diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md index 402e8e35c95..0148c912063 100644 --- a/src/doc/src/guide/tests.md +++ b/src/doc/src/guide/tests.md @@ -1,4 +1,4 @@ -## Tests +# Tests Cargo can run your tests with the `cargo test` command. Cargo looks for tests to run in two places: in each of your `src` files and any tests in `tests/`. diff --git a/src/doc/src/guide/why-cargo-exists.md b/src/doc/src/guide/why-cargo-exists.md index 02b222f0181..2081944f7ab 100644 --- a/src/doc/src/guide/why-cargo-exists.md +++ b/src/doc/src/guide/why-cargo-exists.md @@ -1,6 +1,6 @@ -## Why Cargo Exists +# Why Cargo Exists -### Preliminaries +## Preliminaries In Rust, as you may know, a library or executable program is called a [*crate*][def-crate]. Crates are compiled using the Rust compiler, @@ -31,7 +31,7 @@ involved with performing the above tasks by introducing a higher-level ["*package*"][def-package] abstraction and by using a [*package manager*][def-package-manager]. -### Enter: Cargo +## Enter: Cargo *Cargo* is the Rust package manager. It is a tool that allows Rust [*packages*][def-package] to declare their various dependencies and ensure diff --git a/src/doc/src/guide/working-on-an-existing-project.md b/src/doc/src/guide/working-on-an-existing-project.md index f9c26cd90b4..446248530ce 100644 --- a/src/doc/src/guide/working-on-an-existing-project.md +++ b/src/doc/src/guide/working-on-an-existing-project.md @@ -1,4 +1,4 @@ -## Working on an Existing Cargo Package +# Working on an Existing Cargo Package If you download an existing [package][def-package] that uses Cargo, it’s really easy to get going. diff --git a/src/doc/src/index.md b/src/doc/src/index.md index 223600c8b3d..a7b01c60b6b 100644 --- a/src/doc/src/index.md +++ b/src/doc/src/index.md @@ -7,8 +7,7 @@ dependencies, compiles your packages, makes distributable packages, and uploads [crates.io], the Rust community’s [*package registry*][def-package-registry]. You can contribute to this book on [GitHub]. - -### Sections +## Sections **[Getting Started](getting-started/index.md)** diff --git a/src/doc/src/reference/build-script-examples.md b/src/doc/src/reference/build-script-examples.md index 5e8fae5bbd8..e55d4704dc1 100644 --- a/src/doc/src/reference/build-script-examples.md +++ b/src/doc/src/reference/build-script-examples.md @@ -1,4 +1,4 @@ -## Build Script Examples +# Build Script Examples The following sections illustrate some examples of writing build scripts. @@ -22,7 +22,7 @@ available. The following is a sample of some popular crates[^†]: [^†]: This list is not an endorsement. Evaluate your dependencies to see which is right for your project. -### Code generation +## Code generation Some Cargo packages need to have code generated just before they are compiled for various reasons. Here we’ll walk through a simple example which generates a @@ -120,7 +120,7 @@ from the build script itself. [concat-macro]: ../../std/macro.concat.html [env-macro]: ../../std/macro.env.html -### Building a native library +## Building a native library Sometimes it’s necessary to build some native C or C++ code as part of a package. This is another excellent use case of leveraging the build script to @@ -268,7 +268,7 @@ dependency purely for the build process and not for the crate itself at runtime. [`cc` crate]: https://crates.io/crates/cc -### Linking to system libraries +## Linking to system libraries This example demonstrates how to link a system library and how the build script is used to support this use case. @@ -363,7 +363,7 @@ source][libz-source] for a more complete example. [`pkg-config` crate]: https://crates.io/crates/pkg-config [libz-source]: https://github.com/rust-lang/libz-sys -### Using another `sys` crate +## Using another `sys` crate When using the `links` key, crates may set metadata that can be read by other crates that depend on it. This provides a mechanism to communicate information @@ -424,7 +424,7 @@ already installed. // … rest of code that makes use of zlib. ``` -### Conditional compilation +## Conditional compilation A build script may emit [`rustc-cfg` instructions] which can enable conditions that can be checked at compile time. In this example, we'll take a look at how diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index e7560812bd4..451850388ce 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -1,4 +1,4 @@ -## Build Scripts +# Build Scripts Some packages need to compile third-party non-Rust code, for example C libraries. Other packages need to link to C libraries which can either be @@ -37,7 +37,7 @@ scripts. > Note: The [`package.build` manifest key](manifest.md#the-build-field) can be > used to change the name of the build script, or disable it entirely. -### Life Cycle of a Build Script +## Life Cycle of a Build Script Just before a package is built, Cargo will compile a build script into an executable (if it has not already been built). It will then run the script, @@ -57,7 +57,7 @@ will be compiled. Scripts should exit with a non-zero exit code to halt the build if there is an error, in which case the build script's output will be displayed on the terminal. -### Inputs to the Build Script +## Inputs to the Build Script When the build script is run, there are a number of inputs to the build script, all passed in the form of [environment variables][build-env]. @@ -67,7 +67,7 @@ the source directory of the build script’s package. [build-env]: environment-variables.md#environment-variables-cargo-sets-for-build-scripts -### Outputs of the Build Script +## Outputs of the Build Script Build scripts may save any output files or intermediate artifacts in the directory specified in the [`OUT_DIR` environment variable][build-env]. Scripts @@ -132,7 +132,7 @@ one detailed below. scripts. -#### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg} +### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg} The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building supported targets @@ -142,7 +142,7 @@ linker script. [link-arg]: ../../rustc/codegen-options/index.md#link-arg -#### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin} +### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin} The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building @@ -150,7 +150,7 @@ the binary target with name `BIN`. Its usage is highly platform specific. It is to set a linker script or other linker options. -#### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins} +### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins} The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a @@ -158,7 +158,7 @@ binary target. Its usage is highly platform specific. It is useful to set a linker script or other linker options. -#### `cargo:rustc-link-lib=LIB` {#rustc-link-lib} +### `cargo:rustc-link-lib=LIB` {#rustc-link-lib} The `rustc-link-lib` instruction tells Cargo to link the given library using the compiler's [`-l` flag][option-link]. This is typically used to link a @@ -183,26 +183,26 @@ The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the [FFI]: ../../nomicon/ffi.md -#### `cargo:rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests} +### `cargo:rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests} The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a tests target. -#### `cargo:rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples} +### `cargo:rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples} The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples target. -#### `cargo:rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches} +### `cargo:rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches} The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark target. -#### `cargo:rustc-link-search=[KIND=]PATH` {#rustc-link-search} +### `cargo:rustc-link-search=[KIND=]PATH` {#rustc-link-search} The `rustc-link-search` instruction tells Cargo to pass the [`-L` flag][option-search] to the compiler to add a directory to the library search @@ -220,14 +220,14 @@ is fine). [option-search]: ../../rustc/command-line-arguments.md#option-l-search-path -#### `cargo:rustc-flags=FLAGS` {#rustc-flags} +### `cargo:rustc-flags=FLAGS` {#rustc-flags} The `rustc-flags` instruction tells Cargo to pass the given space-separated flags to the compiler. This only allows the `-l` and `-L` flags, and is equivalent to using [`rustc-link-lib`](#rustc-link-lib) and [`rustc-link-search`](#rustc-link-search). -#### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg} +### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg} The `rustc-cfg` instruction tells Cargo to pass the given value to the [`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time @@ -248,7 +248,7 @@ identifier, the value should be a string. [conditional compilation]: ../../reference/conditional-compilation.md [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg -#### `cargo:rustc-env=VAR=VALUE` {#rustc-env} +### `cargo:rustc-env=VAR=VALUE` {#rustc-env} The `rustc-env` instruction tells Cargo to set the given environment variable when compiling the package. The value can be then retrieved by the [`env!` @@ -268,7 +268,7 @@ Cargo][env-cargo]. [env-macro]: ../../std/macro.env.html [env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates -#### `cargo:rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg} +### `cargo:rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg} The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a @@ -276,7 +276,7 @@ link-arg=FLAG` option][link-arg] to the compiler, but only when building a to set the shared library version or the runtime-path. -#### `cargo:warning=MESSAGE` {#cargo-warning} +### `cargo:warning=MESSAGE` {#cargo-warning} The `warning` instruction tells Cargo to display a warning after the build script has finished running. Warnings are only shown for `path` dependencies @@ -284,7 +284,7 @@ script has finished running. Warnings are only shown for `path` dependencies out in [crates.io] crates are not emitted by default. The `-vv` "very verbose" flag may be used to have Cargo display warnings for all crates. -### Build Dependencies +## Build Dependencies Build scripts are also allowed to have dependencies on other Cargo-based crates. Dependencies are declared through the `build-dependencies` section of the @@ -306,7 +306,7 @@ attempt to reuse a dependency if it is shared between build dependencies and normal dependencies. However, this is not always possible, for example when cross-compiling, so keep that in consideration of the impact on compile time. -### Change Detection +## Change Detection When rebuilding a package, Cargo does not necessarily know if the build script needs to be run again. By default, it takes a conservative approach of always @@ -321,7 +321,7 @@ FAQ](../faq.md#why-is-cargo-rebuilding-my-code). [`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields -#### `cargo:rerun-if-changed=PATH` {#rerun-if-changed} +### `cargo:rerun-if-changed=PATH` {#rerun-if-changed} The `rerun-if-changed` instruction tells Cargo to re-run the build script if the file at the given path has changed. Currently, Cargo only uses the @@ -340,7 +340,7 @@ automatically handles whether or not the script itself needs to be recompiled, and of course the script will be re-run after it has been recompiled. Otherwise, specifying `build.rs` is redundant and unnecessary. -#### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed} +### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed} The `rerun-if-env-changed` instruction tells Cargo to re-run the build script if the value of an environment variable of the given name has changed. @@ -352,7 +352,7 @@ environment variables in use are those received by `cargo` invocations, not those received by the executable of the build script. -### The `links` Manifest Key +## The `links` Manifest Key The `package.links` key may be set in the `Cargo.toml` manifest to declare that the package links with the given native library. The purpose of this @@ -390,7 +390,7 @@ dependents. [using-another-sys]: build-script-examples.md#using-another-sys-crate -### `*-sys` Packages +## `*-sys` Packages Some Cargo packages that link to system libraries have a naming convention of having a `-sys` suffix. Any package named `foo-sys` should provide two major @@ -423,7 +423,7 @@ example, the [`git2` crate] provides a high-level interface to the [`git2` crate]: https://crates.io/crates/git2 [`libgit2-sys` crate]: https://crates.io/crates/libgit2-sys -### Overriding Build Scripts +## Overriding Build Scripts If a manifest contains a `links` key, then Cargo supports overriding the build script specified with a custom library. The purpose of this functionality is to @@ -451,7 +451,7 @@ be used instead. The `warning`, `rerun-if-changed`, and `rerun-if-env-changed` keys should not be used and will be ignored. -### Jobserver +## Jobserver Cargo and `rustc` use the [jobserver protocol], developed for GNU make, to coordinate concurrency across processes. It is essentially a semaphore that diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md index 7aea15109f2..ef29a520fc5 100644 --- a/src/doc/src/reference/cargo-targets.md +++ b/src/doc/src/reference/cargo-targets.md @@ -1,4 +1,4 @@ -## Cargo Targets +# Cargo Targets Cargo packages consist of *targets* which correspond to source files which can be compiled into a crate. Packages can have [library](#library), @@ -10,7 +10,7 @@ by the [directory layout][package layout] of the source files. See [Configuring a target](#configuring-a-target) below for details on configuring the settings for a target. -### Library +## Library The library target defines a "library" that can be used and linked by other libraries and executables. The filename defaults to `src/lib.rs`, and the name @@ -25,7 +25,7 @@ crate-type = ["cdylib"] bench = false ``` -### Binaries +## Binaries Binary targets are executable programs that can be run after being compiled. The default binary filename is `src/main.rs`, which defaults to the name of @@ -52,7 +52,7 @@ name = "frobnicator" required-features = ["frobnicate"] ``` -### Examples +## Examples Files located under the [`examples` directory][package layout] are example uses of the functionality provided by the library. When compiled, they are @@ -81,7 +81,7 @@ default to protect them from bit-rotting. Set [the `test` field](#the-test-field) to `true` if you have `#[test]` functions in the example that you want to run with [`cargo test`]. -### Tests +## Tests There are two styles of tests within a Cargo project: @@ -108,7 +108,7 @@ strategy. [libtest harness]: ../../rustc/tests/index.html [cargo-test-documentation-tests]: ../commands/cargo-test.md#documentation-tests -#### Integration tests +### Integration tests Files located under the [`tests` directory][package layout] are integration tests. When you run [`cargo test`], Cargo will compile each of these files as @@ -140,7 +140,7 @@ executable. [environment variable]: environment-variables.md#environment-variables-cargo-sets-for-crates [`env` macro]: ../../std/macro.env.html -### Benchmarks +## Benchmarks Benchmarks provide a way to test the performance of your code using the [`cargo bench`] command. They follow the same structure as [tests](#tests), @@ -163,7 +163,7 @@ Similarly to tests: > may help with running benchmarks on the stable channel, such as > [Criterion](https://crates.io/crates/criterion). -### Configuring a target +## Configuring a target All of the `[lib]`, `[[bin]]`, `[[example]]`, `[[test]]`, and `[[bench]]` sections in `Cargo.toml` support similar configuration for specifying how a @@ -192,7 +192,7 @@ crate-type = ["lib"] # The crate types to generate. required-features = [] # Features required to build this target (N/A for lib). ``` -#### The `name` field +### The `name` field The `name` field specifies the name of the target, which corresponds to the filename of the artifact that will be generated. For a library, this is the @@ -205,7 +205,7 @@ directory or file name. This is required for all targets except `[lib]`. -#### The `path` field +### The `path` field The `path` field specifies where the source for the crate is located, relative to the `Cargo.toml` file. @@ -213,7 +213,7 @@ to the `Cargo.toml` file. If not specified, the [inferred path](#target-auto-discovery) is used based on the target name. -#### The `test` field +### The `test` field The `test` field indicates whether or not the target is tested by default by [`cargo test`]. The default is `true` for lib, bins, and tests. @@ -223,19 +223,19 @@ The `test` field indicates whether or not the target is tested by default by > true` for an example will also build it as a test and run any > [`#[test]`][test-attribute] functions defined in the example. -#### The `doctest` field +### The `doctest` field The `doctest` field indicates whether or not [documentation examples] are tested by default by [`cargo test`]. This is only relevant for libraries, it has no effect on other sections. The default is `true` for the library. -#### The `bench` field +### The `bench` field The `bench` field indicates whether or not the target is benchmarked by default by [`cargo bench`]. The default is `true` for lib, bins, and benchmarks. -#### The `doc` field +### The `doc` field The `doc` field indicates whether or not the target is included in the documentation generated by [`cargo doc`] by default. The default is `true` for @@ -244,17 +244,17 @@ libraries and binaries. > **Note**: The binary will be skipped if its name is the same as the lib > target. -#### The `plugin` field +### The `plugin` field This field is used for `rustc` plugins, which are being deprecated. -#### The `proc-macro` field +### The `proc-macro` field The `proc-macro` field indicates that the library is a [procedural macro] ([reference][proc-macro-reference]). This is only valid for the `[lib]` target. -#### The `harness` field +### The `harness` field The `harness` field indicates that the [`--test` flag] will be passed to `rustc` which will automatically include the libtest library which is the @@ -268,7 +268,7 @@ to run tests and benchmarks. Tests have the [`cfg(test)` conditional expression][cfg-test] enabled whether or not the harness is enabled. -#### The `edition` field +### The `edition` field The `edition` field defines the [Rust edition] the target will use. If not specified, it defaults to the [`edition` field][package-edition] for the @@ -276,7 +276,7 @@ specified, it defaults to the [`edition` field][package-edition] for the advanced scenarios such as incrementally transitioning a large package to a new edition. -#### The `crate-type` field +### The `crate-type` field The `crate-type` field defines the [crate types] that will be generated by the target. It is an array of strings, allowing you to specify multiple crate @@ -294,7 +294,7 @@ The available options are `bin`, `lib`, `rlib`, `dylib`, `cdylib`, `staticlib`, and `proc-macro`. You can read more about the different crate types in the [Rust Reference Manual][crate types]. -#### The `required-features` field +### The `required-features` field The `required-features` field specifies which [features] the target needs in order to be built. If any of the required features are not enabled, the @@ -314,7 +314,7 @@ required-features = ["postgres", "tools"] ``` -### Target auto-discovery +## Target auto-discovery By default, Cargo automatically determines the targets to build based on the [layout of the files][package layout] on the filesystem. The target diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index fd04ae08fb2..6d0dba29c91 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -1,10 +1,10 @@ -## Configuration +# Configuration This document explains how Cargo’s configuration system works, as well as available keys or configuration. For configuration of a package through its manifest, see the [manifest format](manifest.md). -### Hierarchical structure +## Hierarchical structure Cargo allows local configuration for a particular package as well as global configuration. It looks for configuration files in the current directory and @@ -44,7 +44,7 @@ those configuration files if it is invoked from the workspace root > and is the preferred form. If both files exist, Cargo will use the file > without the extension. -### Configuration format +## Configuration format Configuration files are written in the [TOML format][toml] (like the manifest), with simple key-value pairs inside of sections (tables). The @@ -184,7 +184,7 @@ progress.when = 'auto' # whether cargo shows progress bar progress.width = 80 # width of progress bar ``` -### Environment variables +## Environment variables Cargo can also be configured through environment variables in addition to the TOML configuration files. For each configuration key of the form `foo.bar` the @@ -203,7 +203,7 @@ supported due to [technical issues](https://github.com/rust-lang/cargo/issues/54 In addition to the system above, Cargo recognizes a few other specific [environment variables][env]. -### Command-line overrides +## Command-line overrides Cargo also accepts arbitrary configuration overrides through the `--config` command-line option. The argument should be in TOML syntax of @@ -243,7 +243,7 @@ configuration files that Cargo should use for a specific invocation. Options from configuration files loaded this way follow the same precedence rules as other options specified directly with `--config`. -### Config-relative paths +## Config-relative paths Paths in config files may be absolute, relative, or a bare name without any path separators. Paths for executables without a path separator will use the `PATH` environment variable to search for the executable. @@ -280,7 +280,7 @@ runner = "foo" # Searches `PATH` for `foo`. directory = "vendor" ``` -### Executable paths with arguments +## Executable paths with arguments Some Cargo commands invoke external programs, which can be configured as a path and some number of arguments. @@ -294,7 +294,7 @@ run, they will be passed after the last specified argument in the value of an option of this format. If the specified program does not have path separators, Cargo will search `PATH` for its executable. -### Credentials +## Credentials Configuration values with sensitive information are stored in the `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated @@ -325,14 +325,14 @@ all capital letters. > extension by default. However, for backward compatibility reason, when both > files exist, Cargo will read and write the file without the extension. -### Configuration keys +## Configuration keys This section documents all configuration keys. The description for keys with variable parts are annotated with angled brackets like `target.` where the `` part can be any [target triple] like `target.x86_64-pc-windows-msvc`. -#### `paths` +### `paths` * Type: array of strings (paths) * Default: none * Environment: not supported @@ -341,7 +341,7 @@ An array of paths to local packages which are to be used as overrides for dependencies. For more information see the [Overriding Dependencies guide](overriding-dependencies.md#paths-overrides). -#### `[alias]` +### `[alias]` * Type: string or array of strings * Default: see below * Environment: `CARGO_ALIAS_` @@ -373,11 +373,11 @@ rr = "run --release" recursive_example = "rr --example recursions" ``` -#### `[build]` +### `[build]` The `[build]` table controls build-time operations and compiler settings. -##### `build.jobs` +#### `build.jobs` * Type: integer or string * Default: number of logical CPUs * Environment: `CARGO_BUILD_JOBS` @@ -389,14 +389,14 @@ the value back to defaults. Can be overridden with the `--jobs` CLI option. -##### `build.rustc` +#### `build.rustc` * Type: string (program path) * Default: "rustc" * Environment: `CARGO_BUILD_RUSTC` or `RUSTC` Sets the executable to use for `rustc`. -##### `build.rustc-wrapper` +#### `build.rustc-wrapper` * Type: string (program path) * Default: none * Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER` @@ -405,7 +405,7 @@ Sets a wrapper to execute instead of `rustc`. The first argument passed to the wrapper is the path to the actual executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise). -##### `build.rustc-workspace-wrapper` +#### `build.rustc-workspace-wrapper` * Type: string (program path) * Default: none * Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER` @@ -415,14 +415,14 @@ The first argument passed to the wrapper is the path to the actual executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise). It affects the filename hash so that artifacts produced by the wrapper are cached separately. -##### `build.rustdoc` +#### `build.rustdoc` * Type: string (program path) * Default: "rustdoc" * Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC` Sets the executable to use for `rustdoc`. -##### `build.target` +#### `build.target` * Type: string or array of strings * Default: host platform * Environment: `CARGO_BUILD_TARGET` @@ -442,7 +442,7 @@ Can be overridden with the `--target` CLI option. target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"] ``` -##### `build.target-dir` +#### `build.target-dir` * Type: string (path) * Default: "target" * Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR` @@ -452,7 +452,7 @@ is a directory named `target` located at the root of the workspace. Can be overridden with the `--target-dir` CLI option. -##### `build.rustflags` +#### `build.rustflags` * Type: string or array of strings * Default: none * Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS` @@ -489,7 +489,7 @@ appropriate profile setting. > flags you specify. This is an area where Cargo may not always be backwards > compatible. -##### `build.rustdocflags` +#### `build.rustdocflags` * Type: string or array of strings * Default: none * Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS` @@ -506,7 +506,7 @@ order, with the first one being used: Additional flags may also be passed with the [`cargo rustdoc`] command. -##### `build.incremental` +#### `build.incremental` * Type: bool * Default: from profile * Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL` @@ -519,7 +519,7 @@ The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable incremental compilation for all profiles, or `0` to disable it. This env var overrides the config setting. -##### `build.dep-info-basedir` +#### `build.dep-info-basedir` * Type: string (path) * Default: none * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` @@ -533,15 +533,15 @@ The setting itself is a config-relative path. So, for example, a value of `"."` would strip all paths starting with the parent directory of the `.cargo` directory. -##### `build.pipelining` +#### `build.pipelining` This option is deprecated and unused. Cargo always has pipelining enabled. -#### `[doc]` +### `[doc]` The `[doc]` table defines options for the [`cargo doc`] command. -##### `doc.browser` +#### `doc.browser` * Type: string or array of strings ([program path with args]) * Default: `BROWSER` environment variable, or, if that is missing, @@ -551,19 +551,19 @@ This option sets the browser to be used by [`cargo doc`], overriding the `BROWSER` environment variable when opening documentation with the `--open` option. -#### `[cargo-new]` +### `[cargo-new]` The `[cargo-new]` table defines defaults for the [`cargo new`] command. -##### `cargo-new.name` +#### `cargo-new.name` This option is deprecated and unused. -##### `cargo-new.email` +#### `cargo-new.email` This option is deprecated and unused. -##### `cargo-new.vcs` +#### `cargo-new.vcs` * Type: string * Default: "git" or "none" * Environment: `CARGO_CARGO_NEW_VCS` @@ -611,12 +611,12 @@ Controls how often we display a notification to the terminal when a future incom * `always` (default): Always display a notification when a command (e.g. `cargo build`) produces a future incompat report * `never`: Never display a notification -#### `[http]` +### `[http]` The `[http]` table defines settings for HTTP behavior. This includes fetching crate dependencies and accessing remote git repositories. -##### `http.debug` +#### `http.debug` * Type: boolean * Default: false * Environment: `CARGO_HTTP_DEBUG` @@ -629,7 +629,7 @@ Be wary when posting logs from this output in a public location. The output may include headers with authentication tokens which you don't want to leak! Be sure to review logs before posting them. -##### `http.proxy` +#### `http.proxy` * Type: string * Default: none * Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy` @@ -640,14 +640,14 @@ setting in your global git configuration. If none of those are set, the `HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS requests, and `http_proxy` sets it for HTTP requests. -##### `http.timeout` +#### `http.timeout` * Type: integer * Default: 30 * Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT` Sets the timeout for each HTTP request, in seconds. -##### `http.cainfo` +#### `http.cainfo` * Type: string (path) * Default: none * Environment: `CARGO_HTTP_CAINFO` @@ -655,7 +655,7 @@ Sets the timeout for each HTTP request, in seconds. Path to a Certificate Authority (CA) bundle file, used to verify TLS certificates. If not specified, Cargo attempts to use the system certificates. -##### `http.check-revoke` +#### `http.check-revoke` * Type: boolean * Default: true (Windows) false (all others) * Environment: `CARGO_HTTP_CHECK_REVOKE` @@ -663,7 +663,7 @@ certificates. If not specified, Cargo attempts to use the system certificates. This determines whether or not TLS certificate revocation checks should be performed. This only works on Windows. -##### `http.ssl-version` +#### `http.ssl-version` * Type: string or min/max table * Default: none * Environment: `CARGO_HTTP_SSL_VERSION` @@ -679,7 +679,7 @@ range of TLS versions to use. The default is a minimum version of "tlsv1.0" and a max of the newest version supported on your platform, typically "tlsv1.3". -##### `http.low-speed-limit` +#### `http.low-speed-limit` * Type: integer * Default: 10 * Environment: `CARGO_HTTP_LOW_SPEED_LIMIT` @@ -689,7 +689,7 @@ transfer speed in bytes per second is below the given value for [`http.timeout`](#httptimeout) seconds (default 30 seconds), then the connection is considered too slow and Cargo will abort and retry. -##### `http.multiplexing` +#### `http.multiplexing` * Type: boolean * Default: true * Environment: `CARGO_HTTP_MULTIPLEXING` @@ -699,7 +699,7 @@ This allows multiple requests to use the same connection, usually improving performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1 without pipelining. -##### `http.user-agent` +#### `http.user-agent` * Type: string * Default: Cargo's version * Environment: `CARGO_HTTP_USER_AGENT` @@ -707,11 +707,11 @@ without pipelining. Specifies a custom user-agent header to use. The default if not specified is a string that includes Cargo's version. -#### `[install]` +### `[install]` The `[install]` table defines defaults for the [`cargo install`] command. -##### `install.root` +#### `install.root` * Type: string (path) * Default: Cargo's home directory * Environment: `CARGO_INSTALL_ROOT` @@ -727,18 +727,18 @@ your home directory). Can be overridden with the `--root` command-line option. -#### `[net]` +### `[net]` The `[net]` table controls networking configuration. -##### `net.retry` +#### `net.retry` * Type: integer * Default: 3 * Environment: `CARGO_NET_RETRY` Number of times to retry possibly spurious network errors. -##### `net.git-fetch-with-cli` +#### `net.git-fetch-with-cli` * Type: boolean * Default: false * Environment: `CARGO_NET_GIT_FETCH_WITH_CLI` @@ -752,7 +752,7 @@ requirements that Cargo does not support. See [Git Authentication](../appendix/git-authentication.md) for more information about setting up git authentication. -##### `net.offline` +#### `net.offline` * Type: boolean * Default: false * Environment: `CARGO_NET_OFFLINE` @@ -763,11 +763,11 @@ needed, and generate an error if it encounters a network error. Can be overridden with the `--offline` command-line option. -##### `net.ssh` +#### `net.ssh` The `[net.ssh]` table contains settings for SSH connections. -##### `net.ssh.known-hosts` +#### `net.ssh.known-hosts` * Type: array of strings * Default: see description * Environment: not supported @@ -798,7 +798,7 @@ for more details. [github-keys]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints -#### `[patch]` +### `[patch]` Just as you can override dependencies using [`[patch]` in `Cargo.toml`](overriding-dependencies.md#the-patch-section), you can @@ -823,7 +823,7 @@ lowest precedence. Relative `path` dependencies in such a `[patch]` section are resolved relative to the configuration file they appear in. -#### `[profile]` +### `[profile]` The `[profile]` table can be used to globally change profile settings, and override settings specified in `Cargo.toml`. It has the same syntax and @@ -832,91 +832,91 @@ details about the options. [Profiles chapter]: profiles.md -##### `[profile..build-override]` +#### `[profile..build-override]` * Environment: `CARGO_PROFILE__BUILD_OVERRIDE_` The build-override table overrides settings for build scripts, proc macros, and their dependencies. It has the same keys as a normal profile. See the [overrides section](profiles.md#overrides) for more details. -##### `[profile..package.]` +#### `[profile..package.]` * Environment: not supported The package table overrides settings for specific packages. It has the same keys as a normal profile, minus the `panic`, `lto`, and `rpath` settings. See the [overrides section](profiles.md#overrides) for more details. -##### `profile..codegen-units` +#### `profile..codegen-units` * Type: integer * Default: See profile docs. * Environment: `CARGO_PROFILE__CODEGEN_UNITS` See [codegen-units](profiles.md#codegen-units). -##### `profile..debug` +#### `profile..debug` * Type: integer or boolean * Default: See profile docs. * Environment: `CARGO_PROFILE__DEBUG` See [debug](profiles.md#debug). -##### `profile..split-debuginfo` +#### `profile..split-debuginfo` * Type: string * Default: See profile docs. * Environment: `CARGO_PROFILE__SPLIT_DEBUGINFO` See [split-debuginfo](profiles.md#split-debuginfo). -##### `profile..debug-assertions` +#### `profile..debug-assertions` * Type: boolean * Default: See profile docs. * Environment: `CARGO_PROFILE__DEBUG_ASSERTIONS` See [debug-assertions](profiles.md#debug-assertions). -##### `profile..incremental` +#### `profile..incremental` * Type: boolean * Default: See profile docs. * Environment: `CARGO_PROFILE__INCREMENTAL` See [incremental](profiles.md#incremental). -##### `profile..lto` +#### `profile..lto` * Type: string or boolean * Default: See profile docs. * Environment: `CARGO_PROFILE__LTO` See [lto](profiles.md#lto). -##### `profile..overflow-checks` +#### `profile..overflow-checks` * Type: boolean * Default: See profile docs. * Environment: `CARGO_PROFILE__OVERFLOW_CHECKS` See [overflow-checks](profiles.md#overflow-checks). -##### `profile..opt-level` +#### `profile..opt-level` * Type: integer or string * Default: See profile docs. * Environment: `CARGO_PROFILE__OPT_LEVEL` See [opt-level](profiles.md#opt-level). -##### `profile..panic` +#### `profile..panic` * Type: string * default: See profile docs. * Environment: `CARGO_PROFILE__PANIC` See [panic](profiles.md#panic). -##### `profile..rpath` +#### `profile..rpath` * Type: boolean * default: See profile docs. * Environment: `CARGO_PROFILE__RPATH` See [rpath](profiles.md#rpath). -##### `profile..strip` +#### `profile..strip` * Type: string * default: See profile docs. * Environment: `CARGO_PROFILE__STRIP` @@ -924,19 +924,19 @@ See [rpath](profiles.md#rpath). See [strip](profiles.md#strip). -#### `[registries]` +### `[registries]` The `[registries]` table is used for specifying additional [registries]. It consists of a sub-table for each named registry. -##### `registries..index` +#### `registries..index` * Type: string (url) * Default: none * Environment: `CARGO_REGISTRIES__INDEX` Specifies the URL of the index for the registry. -##### `registries..token` +#### `registries..token` * Type: string * Default: none * Environment: `CARGO_REGISTRIES__TOKEN` @@ -947,7 +947,7 @@ commands like [`cargo publish`] that require authentication. Can be overridden with the `--token` command-line option. -##### `registries.crates-io.protocol` +#### `registries.crates-io.protocol` * Type: string * Default: `sparse` * Environment: `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` @@ -961,16 +961,16 @@ This can result in a significant performance improvement for resolving new depen More information about registry protocols may be found in the [Registries chapter](registries.md). -#### `[registry]` +### `[registry]` The `[registry]` table controls the default registry used when one is not specified. -##### `registry.index` +#### `registry.index` This value is no longer accepted and should not be used. -##### `registry.default` +#### `registry.default` * Type: string * Default: `"crates-io"` * Environment: `CARGO_REGISTRY_DEFAULT` @@ -980,7 +980,7 @@ by default for registry commands like [`cargo publish`]. Can be overridden with the `--registry` command-line option. -##### `registry.token` +#### `registry.token` * Type: string * Default: none * Environment: `CARGO_REGISTRY_TOKEN` @@ -991,49 +991,49 @@ commands like [`cargo publish`] that require authentication. Can be overridden with the `--token` command-line option. -#### `[source]` +### `[source]` The `[source]` table defines the registry sources available. See [Source Replacement] for more information. It consists of a sub-table for each named source. A source should only define one kind (directory, registry, local-registry, or git). -##### `source..replace-with` +#### `source..replace-with` * Type: string * Default: none * Environment: not supported If set, replace this source with the given named source or named registry. -##### `source..directory` +#### `source..directory` * Type: string (path) * Default: none * Environment: not supported Sets the path to a directory to use as a directory source. -##### `source..registry` +#### `source..registry` * Type: string (url) * Default: none * Environment: not supported Sets the URL to use for a registry source. -##### `source..local-registry` +#### `source..local-registry` * Type: string (path) * Default: none * Environment: not supported Sets the path to a directory to use as a local registry source. -##### `source..git` +#### `source..git` * Type: string (url) * Default: none * Environment: not supported Sets the URL to use for a git repository source. -##### `source..branch` +#### `source..branch` * Type: string * Default: none * Environment: not supported @@ -1042,7 +1042,7 @@ Sets the branch name to use for a git repository. If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. -##### `source..tag` +#### `source..tag` * Type: string * Default: none * Environment: not supported @@ -1051,7 +1051,7 @@ Sets the tag name to use for a git repository. If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. -##### `source..rev` +#### `source..rev` * Type: string * Default: none * Environment: not supported @@ -1061,7 +1061,7 @@ Sets the [revision] to use for a git repository. If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. -#### `[target]` +### `[target]` The `[target]` table is used for specifying settings for specific platform targets. It consists of a sub-table which is either a [platform triple][target triple] @@ -1087,11 +1087,11 @@ to view), values set by [build scripts], and extra `--cfg` flags passed to If using a target spec JSON file, the [``] value is the filename stem. For example `--target foo/bar.json` would match `[target.bar]`. -##### `target..ar` +#### `target..ar` This option is deprecated and unused. -##### `target..linker` +#### `target..linker` * Type: string (program path) * Default: none * Environment: `CARGO_TARGET__LINKER` @@ -1099,13 +1099,13 @@ This option is deprecated and unused. Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the [``] is being compiled for. By default, the linker is not overridden. -##### `target..linker` +#### `target..linker` This is similar to the [target linker](#targettriplelinker), but using a [`cfg()` expression]. If both a [``] and `` runner match, the `` will take precedence. It is an error if more than one `` runner matches the current target. -##### `target..runner` +#### `target..runner` * Type: string or array of strings ([program path with args]) * Default: none * Environment: `CARGO_TARGET__RUNNER` @@ -1115,14 +1115,14 @@ executed by invoking the specified runner with the actual executable passed as an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] commands. By default, compiled executables are executed directly. -##### `target..runner` +#### `target..runner` This is similar to the [target runner](#targettriplerunner), but using a [`cfg()` expression]. If both a [``] and `` runner match, the `` will take precedence. It is an error if more than one `` runner matches the current target. -##### `target..rustflags` +#### `target..rustflags` * Type: string or array of strings * Default: none * Environment: `CARGO_TARGET__RUSTFLAGS` @@ -1133,13 +1133,13 @@ The value may be an array of strings or a space-separated string. See [`build.rustflags`](#buildrustflags) for more details on the different ways to specific extra flags. -##### `target..rustflags` +#### `target..rustflags` This is similar to the [target rustflags](#targettriplerustflags), but using a [`cfg()` expression]. If several `` and [``] entries match the current target, the flags are joined together. -##### `target..` +#### `target..` The links sub-table provides a way to [override a build script]. When specified, the build script for the given `links` library will not be @@ -1157,11 +1157,11 @@ metadata_key1 = "value" metadata_key2 = "value" ``` -#### `[term]` +### `[term]` The `[term]` table controls terminal output and interaction. -##### `term.quiet` +#### `term.quiet` * Type: boolean * Default: false * Environment: `CARGO_TERM_QUIET` @@ -1171,7 +1171,7 @@ Controls whether or not log messages are displayed by Cargo. Specifying the `--quiet` flag will override and force quiet output. Specifying the `--verbose` flag will override and disable quiet output. -##### `term.verbose` +#### `term.verbose` * Type: boolean * Default: false * Environment: `CARGO_TERM_VERBOSE` @@ -1181,7 +1181,7 @@ Controls whether or not extra detailed messages are displayed by Cargo. Specifying the `--quiet` flag will override and disable verbose output. Specifying the `--verbose` flag will override and force verbose output. -##### `term.color` +#### `term.color` * Type: string * Default: "auto" * Environment: `CARGO_TERM_COLOR` @@ -1195,7 +1195,7 @@ Controls whether or not colored output is used in the terminal. Possible values: Can be overridden with the `--color` command-line option. -##### `term.progress.when` +#### `term.progress.when` * Type: string * Default: "auto" * Environment: `CARGO_TERM_PROGRESS_WHEN` @@ -1206,7 +1206,7 @@ Controls whether or not progress bar is shown in the terminal. Possible values: * `always`: Always show progress bar. * `never`: Never show progress bar. -##### `term.progress.width` +#### `term.progress.width` * Type: integer * Default: none * Environment: `CARGO_TERM_PROGRESS_WIDTH` diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 25881d1388d..4572fe2ee52 100644 --- a/src/doc/src/reference/environment-variables.md +++ b/src/doc/src/reference/environment-variables.md @@ -1,10 +1,10 @@ -## Environment Variables +# Environment Variables Cargo sets and reads a number of environment variables which your code can detect or override. Here is a list of the variables Cargo sets, organized by when it interacts with them: -### Environment variables Cargo reads +## Environment variables Cargo reads You can override these environment variables to change Cargo's behavior on your system: @@ -79,7 +79,7 @@ system: [`cargo fmt`](https://github.com/rust-lang/rustfmt) will execute this specified `rustfmt` instance instead. -#### Configuration environment variables +### Configuration environment variables Cargo reads environment variables for some configuration values. See the [configuration chapter][config-env] for more details. @@ -200,7 +200,7 @@ In summary, the supported environment variables are: [`term.progress.when`]: config.md#termprogresswhen [`term.progress.width`]: config.md#termprogresswidth -### Environment variables Cargo sets for crates +## Environment variables Cargo sets for crates Cargo exposes these environment variables to your crate when it is compiled. Note that this applies for running binaries with `cargo run` and `cargo test` @@ -266,7 +266,7 @@ corresponding environment variable is set to the empty string, `""`. [integration test]: cargo-targets.md#integration-tests [`env` macro]: ../../std/macro.env.html -#### Dynamic library paths +### Dynamic library paths Cargo also sets the dynamic library path when compiling and running binaries with commands like `cargo run` and `cargo test`. This helps with locating @@ -294,7 +294,7 @@ Cargo includes the following paths: * The rustc sysroot library path. This generally is not important to most users. -### Environment variables Cargo sets for build scripts +## Environment variables Cargo sets for build scripts Cargo sets several environment variables when build scripts are run. Because these variables are not yet set when the build script is compiled, the above example using `env!` won't work @@ -411,7 +411,7 @@ let out_dir = env::var("OUT_DIR").unwrap(); [`dev`]: profiles.md#dev [`release`]: profiles.md#release -### Environment variables Cargo sets for 3rd party subcommands +## Environment variables Cargo sets for 3rd party subcommands Cargo exposes this environment variable to 3rd party subcommands (ie. programs named `cargo-foobar` placed in `$PATH`): diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md index b2f37ca0be3..e835ea3ee50 100644 --- a/src/doc/src/reference/external-tools.md +++ b/src/doc/src/reference/external-tools.md @@ -1,4 +1,4 @@ -## External tools +# External tools One of the goals of Cargo is simple integration with third-party tools, like IDEs and other build systems. To make integration easier, Cargo has several @@ -13,7 +13,7 @@ facilities: * support for custom subcommands. -### Information about package structure +## Information about package structure You can use [`cargo metadata`] command to get information about package structure and dependencies. See the [`cargo metadata`] documentation @@ -29,7 +29,7 @@ output. [cargo_metadata]: https://crates.io/crates/cargo_metadata [`cargo metadata`]: ../commands/cargo-metadata.md -### JSON messages +## JSON messages When passing `--message-format=json`, Cargo will output the following information during the build: @@ -54,7 +54,7 @@ messages. [build command documentation]: ../commands/cargo-build.md [cargo_metadata]: https://crates.io/crates/cargo_metadata -#### Compiler messages +### Compiler messages The "compiler-message" message includes output from the compiler, such as warnings and errors. See the [rustc JSON chapter](../../rustc/json.md) for @@ -125,7 +125,7 @@ structure: } ``` -#### Artifact messages +### Artifact messages For every compilation step, a "compiler-artifact" message is emitted with the following structure: @@ -192,7 +192,7 @@ following structure: ``` -#### Build script output +### Build script output The "build-script-executed" message includes the parsed output of a build script. Note that this is emitted even if the build script is not run; it will @@ -233,7 +233,7 @@ may be found in [the chapter on build scripts](build-scripts.md). } ``` -#### Build finished +### Build finished The "build-finished" message is emitted at the end of the build. @@ -257,7 +257,7 @@ executed by `cargo run`). > so additional test-specific JSON messages may begin arriving after the > "build-finished" message if that is enabled. -### Custom subcommands +## Custom subcommands Cargo is designed to be extensible with new subcommands without having to modify Cargo itself. This is achieved by translating a cargo invocation of the form diff --git a/src/doc/src/reference/features-examples.md b/src/doc/src/reference/features-examples.md index ac9636fcbe7..810288dda54 100644 --- a/src/doc/src/reference/features-examples.md +++ b/src/doc/src/reference/features-examples.md @@ -1,8 +1,8 @@ -## Features Examples +# Features Examples The following illustrates some real-world examples of features in action. -### Minimizing build times and file sizes +## Minimizing build times and file sizes Some packages use features so that if the features are not enabled, it reduces the size of the crate and reduces compile time. Some examples are: @@ -30,7 +30,7 @@ the size of the crate and reduces compile time. Some examples are: [`web-sys`]: https://crates.io/crates/web-sys [web-sys-features]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/crates/web-sys/Cargo.toml#L32-L1395 -### Extending behavior +## Extending behavior The [`serde_json`] package has a [`preserve_order` feature][serde_json-preserve_order] which [changes the behavior][serde_json-code] of JSON maps to preserve the @@ -47,7 +47,7 @@ usually builds with the feature off. [serde_json-code]: https://github.com/serde-rs/json/blob/v1.0.60/src/map.rs#L23-L26 [`indexmap`]: https://crates.io/crates/indexmap -### `no_std` support +## `no_std` support Some packages want to support both [`no_std`] and `std` environments. This is useful for supporting embedded and resource-constrained platforms, but still @@ -71,7 +71,7 @@ to conditionally enable extra functionality that requires `std`. [wasm-bindgen-cfg1]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L270-L273 [wasm-bindgen-cfg2]: https://github.com/rustwasm/wasm-bindgen/blob/0.2.69/src/lib.rs#L67-L75 -### Re-exporting dependency features +## Re-exporting dependency features It can be convenient to re-export the features from a dependency. This allows the user depending on the crate to control those features without needing to @@ -83,7 +83,7 @@ but they can still access the features it contains. [regex-re-export]: https://github.com/rust-lang/regex/blob/1.4.2/Cargo.toml#L65-L89 [regex_syntax-features]: https://github.com/rust-lang/regex/blob/1.4.2/regex-syntax/Cargo.toml#L17-L32 -### Vendoring of C libraries +## Vendoring of C libraries Some packages provide bindings to common C libraries (sometimes referred to as ["sys" crates][sys]). Sometimes these packages give you the choice to use the @@ -111,7 +111,7 @@ static-curl setting. [curl-sys-macos]: https://github.com/alexcrichton/curl-rust/blob/0.4.34/curl-sys/Cargo.toml#L52 [curl-sys-macos-code]: https://github.com/alexcrichton/curl-rust/blob/0.4.34/curl-sys/build.rs#L15-L20 -### Feature precedence +## Feature precedence Some packages may have mutually-exclusive features. One option to handle this is to prefer one feature over another. The [`log`] package is an example. It @@ -126,7 +126,7 @@ levels will be preferred over the lower levels. [log-cfg-if]: https://github.com/rust-lang/log/blob/0.4.11/src/lib.rs#L1422-L1448 [`cfg-if`]: https://crates.io/crates/cfg-if -### Proc-macro companion package +## Proc-macro companion package Some packages have a proc-macro that is intimately tied with it. However, not all users will need to use the proc-macro. By making the proc-macro an @@ -145,7 +145,7 @@ requirement][serde-equals] to ensure they stay in sync. [serde-derive]: https://github.com/serde-rs/serde/blob/v1.0.118/serde/Cargo.toml#L34-L35 [serde-equals]: https://github.com/serde-rs/serde/blob/v1.0.118/serde/Cargo.toml#L17 -### Nightly-only features +## Nightly-only features Some packages want to experiment with APIs or language features that are only available on the Rust [nightly channel]. However, they may not want to require @@ -172,7 +172,7 @@ which relies on a dependency that only builds on the nightly channel. [`rand`]: https://crates.io/crates/rand [rand-simd_support]: https://github.com/rust-random/rand/blob/0.7.3/Cargo.toml#L40 -### Experimental features +## Experimental features Some packages have new functionality that they may want to experiment with, without having to commit to the stability of those APIs. The features are diff --git a/src/doc/src/reference/features.md b/src/doc/src/reference/features.md index 40eb32c411d..9e521049cda 100644 --- a/src/doc/src/reference/features.md +++ b/src/doc/src/reference/features.md @@ -1,4 +1,4 @@ -## Features +# Features Cargo "features" provide a mechanism to express [conditional compilation] and [optional dependencies](#optional-dependencies). A package defines a set of @@ -13,7 +13,7 @@ be used. [conditional compilation]: ../../reference/conditional-compilation.md [Features Examples]: features-examples.md -### The `[features]` section +## The `[features]` section Features are defined in the `[features]` table in `Cargo.toml`. Each feature specifies an array of other features or optional dependencies that it enables. @@ -68,7 +68,7 @@ includes most letters), and additionally allows starting with `_` or digits [`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute [`cfg` macro]: ../../std/macro.cfg.html -### The `default` feature +## The `default` feature By default, all features are disabled unless explicitly enabled. This can be changed by specifying the `default` feature: @@ -105,7 +105,7 @@ enables the listed features. This behavior can be changed by: > change](#semver-compatibility) to remove a feature from the default set, so > you should be confident that you will keep those features. -### Optional dependencies +## Optional dependencies Dependencies can be marked "optional", which means they will not be compiled by default. For example, let's say that our 2D image processing library uses @@ -164,7 +164,7 @@ our crate. [platform-specific dependencies]: specifying-dependencies.md#platform-specific-dependencies -### Dependency features +## Dependency features Features of dependencies can be enabled within the dependency declaration. The `features` key indicates which features to enable: @@ -226,7 +226,7 @@ dependency. It will also enable the `serde` feature for the `rgb` dependency, but only if something else has enabled the `rgb` dependency. -### Command-line feature options +## Command-line feature options The following command-line flags can be used to control which features are enabled: @@ -246,7 +246,7 @@ enabled: [workspace]: workspaces.md -### Feature unification +## Feature unification Features are unique to the package that defines them. Enabling a feature on a package does not enable a feature of the same name on other packages. @@ -291,7 +291,7 @@ pub fn function_that_requires_std() { [`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute [features section]: resolver.md#features -#### Mutually exclusive features +### Mutually exclusive features There are rare cases where features may be mutually incompatible with one another. This should be avoided if at all possible, because it requires @@ -318,7 +318,7 @@ Instead of using mutually exclusive features, consider some other options: [`cfg-if`]: https://crates.io/crates/cfg-if [feature-precedence]: features-examples.md#feature-precedence -#### Inspecting resolved features +### Inspecting resolved features In complex dependency graphs, it can sometimes be difficult to understand how different features get enabled on various packages. The [`cargo tree`] command @@ -338,7 +338,7 @@ enabled. Some options to try: [`cargo tree`]: ../commands/cargo-tree.md -### Feature resolver version 2 +## Feature resolver version 2 A different feature resolver can be specified with the `resolver` field in `Cargo.toml`, like this: @@ -386,7 +386,7 @@ the resolved features. For build dependencies, this is not necessary if you are cross-compiling with the `--target` flag because build dependencies are always built separately from normal dependencies in that scenario. -#### Resolver version 2 command-line flags +### Resolver version 2 command-line flags The `resolver = "2"` setting also changes the behavior of the `--features` and `--no-default-features` [command-line options](#command-line-feature-options). @@ -419,7 +419,7 @@ version "2", it will disable the default features for all workspace members. [dev-dependencies]: specifying-dependencies.md#development-dependencies [resolver-v2]: resolver.md#feature-resolver-version-2 -### Build scripts +## Build scripts [Build scripts] can detect which features are enabled on the package by inspecting the `CARGO_FEATURE_` environment variable, where `` is @@ -427,7 +427,7 @@ the feature name converted to uppercase and `-` converted to `_`. [build scripts]: build-scripts.md -### Required features +## Required features The [`required-features` field] can be used to disable specific [Cargo targets] if a feature is not enabled. See the linked documentation for more @@ -436,7 +436,7 @@ details. [`required-features` field]: cargo-targets.md#the-required-features-field [Cargo targets]: cargo-targets.md -### SemVer compatibility +## SemVer compatibility Enabling a feature should not introduce a SemVer-incompatible change. For example, the feature shouldn't change an existing API in a way that could @@ -466,7 +466,7 @@ See the links for caveats and examples. [cargo-remove-opt-dep]: semver.md#cargo-remove-opt-dep [cargo-feature-remove-another]: semver.md#cargo-feature-remove-another -### Feature documentation and discovery +## Feature documentation and discovery You are encouraged to document which features are available in your package. This can be done by adding [doc comments] at the top of `lib.rs`. As an @@ -501,7 +501,7 @@ control which features are enabled when the documentation is built. See [`doc_cfg`]: ../../unstable-book/language-features/doc-cfg.html [`syn` documentation]: https://docs.rs/syn/1.0.54/syn/#modules -#### Discovering features +### Discovering features When features are documented in the library API, this can make it easier for your users to discover which features are available and what they do. If the @@ -514,7 +514,7 @@ source and inspect it. [`cargo vendor`]: ../commands/cargo-vendor.md [cargo-clone-crate]: https://crates.io/crates/cargo-clone-crate -### Feature combinations +## Feature combinations Because features are a form of conditional compilation, they require an exponential number of configurations and test cases to be 100% covered. By default, tests, docs, and other tooling such as [Clippy](https://github.com/rust-lang/rust-clippy) will only run with the default set of features. diff --git a/src/doc/src/reference/future-incompat-report.md b/src/doc/src/reference/future-incompat-report.md index b72f117572a..ab394572f06 100644 --- a/src/doc/src/reference/future-incompat-report.md +++ b/src/doc/src/reference/future-incompat-report.md @@ -1,4 +1,4 @@ -### Future incompat report +# Future incompat report Cargo checks for future-incompatible warnings in all dependencies. These are warnings for changes that may become hard errors in the future, causing the dependency to diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index b931306c206..afff4fa89a4 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -1,4 +1,4 @@ -## Cargo Reference +# Cargo Reference The reference covers the details of various areas of Cargo. diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 5f9d29ff6e3..8329be0cc5b 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -1,4 +1,4 @@ -## The Manifest Format +# The Manifest Format The `Cargo.toml` file for each package is called its *manifest*. It is written in the [TOML] format. It contains metadata that is needed to compile the package. Checkout @@ -53,7 +53,7 @@ Every manifest file consists of the following sections: * [`[profile]`](profiles.md) --- Compiler settings and optimizations. * [`[workspace]`](workspaces.md) --- The workspace definition. -### The `[package]` section +## The `[package]` section The first section in a `Cargo.toml` is `[package]`. @@ -69,7 +69,7 @@ The only fields required by Cargo are [`name`](#the-name-field) and require additional fields. See the notes below and [the publishing chapter][publishing] for requirements for publishing to [crates.io]. -#### The `name` field +### The `name` field The package name is an identifier used to refer to the package. It is used when listed as a dependency in another package, and as the default name of @@ -88,7 +88,7 @@ a keyword. [crates.io] imposes even more restrictions, such as: [alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric -#### The `version` field +### The `version` field Cargo bakes in the concept of [Semantic Versioning](https://semver.org/), so make sure you follow some basic rules: @@ -111,7 +111,7 @@ breaking change. [Resolver]: resolver.md [SemVer compatibility]: semver.md -#### The `authors` field +### 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 @@ -133,7 +133,7 @@ user interface. > field cannot be changed or removed in already-published versions of a > package. -#### The `edition` field +### The `edition` field The `edition` key is an optional key that affects which [Rust Edition] your package is compiled with. Setting the `edition` key in `[package]` will affect all @@ -155,7 +155,7 @@ assumed for backwards compatibility. Note that all manifests created with [`cargo new`] will not use this historical fallback because they will have `edition` explicitly specified to a newer value. -#### The `rust-version` field +### The `rust-version` field The `rust-version` field is an optional key that tells cargo what version of the Rust language and compiler your package can be compiled with. If the currently @@ -182,7 +182,7 @@ The `rust-version` may be ignored using the `--ignore-rust-version` option. Setting the `rust-version` key in `[package]` will affect all targets/crates in the package, including test suites, benchmarks, binaries, examples, etc. -#### The `description` field +### The `description` field The description is a short blurb about the package. [crates.io] will display this with your package. This should be plain text (not Markdown). @@ -195,7 +195,7 @@ description = "A short description of my package" > **Note**: [crates.io] requires the `description` to be set. -#### The `documentation` field +### The `documentation` field The `documentation` field specifies a URL to a website hosting the crate's documentation. If no URL is specified in the manifest file, [crates.io] will @@ -210,7 +210,7 @@ documentation = "https://docs.rs/bitflags" [docs.rs queue]: https://docs.rs/releases/queue -#### The `readme` field +### The `readme` field The `readme` field should be the path to a file in the package root (relative to this `Cargo.toml`) that contains general information about the package. @@ -229,7 +229,7 @@ file will be used. You can suppress this behavior by setting this field to `false`. If the field is set to `true`, a default value of `README.md` will be assumed. -#### The `homepage` field +### The `homepage` field The `homepage` field should be a URL to a site that is the home page for your package. @@ -240,7 +240,7 @@ package. homepage = "https://serde.rs/" ``` -#### The `repository` field +### The `repository` field The `repository` field should be a URL to the source repository for your package. @@ -251,7 +251,7 @@ package. repository = "https://github.com/rust-lang/cargo/" ``` -#### The `license` and `license-file` fields +### The `license` and `license-file` fields The `license` field contains the name of the software license that the package is released under. The `license-file` field contains the path to a file @@ -293,7 +293,7 @@ license-file = "LICENSE.txt" [^slash]: Previously multiple licenses could be separated with a `/`, but that usage is deprecated. -#### The `keywords` field +### The `keywords` field The `keywords` field is an array of strings that describe this package. This can help when searching for the package on a registry, and you may choose any @@ -309,7 +309,7 @@ keywords = ["gamedev", "graphics"] > ASCII text, start with a letter, and only contain letters, numbers, `_` or > `-`, and have at most 20 characters. -#### The `categories` field +### The `categories` field The `categories` field is an array of strings of the categories this package belongs to. @@ -322,7 +322,7 @@ categories = ["command-line-utilities", "development-tools::cargo-plugins"] > match one of the strings available at , and > must match exactly. -#### The `workspace` field +### The `workspace` field The `workspace` field can be used to configure the workspace that this package will be a member of. If not specified this will be inferred as the first @@ -342,7 +342,7 @@ table defined. That is, a crate cannot both be a root crate in a workspace For more information, see the [workspaces chapter](workspaces.md). -#### The `build` field +### The `build` field The `build` field specifies a file in the package root which is a [build script] for building native code. More information can be found in the [build @@ -361,7 +361,7 @@ The default is `"build.rs"`, which loads the script from a file named specify a path to a different file or `build = false` to disable automatic detection of the build script. -#### The `links` field +### The `links` field The `links` field specifies the name of a native library that is being linked to. More information can be found in the [`links`][links] section of the build @@ -378,7 +378,7 @@ on Linux) may specify: links = "git2" ``` -#### The `exclude` and `include` fields +### The `exclude` and `include` fields The `exclude` and `include` fields can be used to explicitly specify which files are included when packaging a project to be [published][publishing], @@ -467,7 +467,7 @@ if any of those files change. [gitignore]: https://git-scm.com/docs/gitignore -#### The `publish` field +### The `publish` field The `publish` field can be used to prevent a package from being published to a package registry (like *crates.io*) by mistake, for instance to keep a package @@ -491,7 +491,7 @@ publish = ["some-registry-name"] If publish array contains a single registry, `cargo publish` command will use it when `--registry` flag is not specified. -#### The `metadata` table +### The `metadata` table Cargo by default will warn about unused keys in `Cargo.toml` to assist in detecting typos and such. The `package.metadata` table, however, is completely @@ -519,7 +519,7 @@ if that makes sense for the tool in question. [workspace-metadata]: workspaces.md#the-metadata-table -#### The `default-run` field +### The `default-run` field The `default-run` field in the `[package]` section of the manifest can be used to specify a default binary picked by [`cargo run`]. For example, when there is @@ -530,7 +530,7 @@ both `src/bin/a.rs` and `src/bin/b.rs`: default-run = "a" ``` -### The `[badges]` section +## The `[badges]` section The `[badges]` section is for specifying status badges that can be displayed on a registry website when the package is published. @@ -565,13 +565,13 @@ on a registry website when the package is published. maintenance = { status = "..." } ``` -### Dependency sections +## Dependency sections See the [specifying dependencies page](specifying-dependencies.md) for information on the `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, and target-specific `[target.*.dependencies]` sections. -### The `[profile.*]` sections +## The `[profile.*]` sections The `[profile]` tables provide a way to customize compiler settings such as optimizations and debug settings. See [the Profiles chapter](profiles.md) for diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md index d5efac45209..6d80df198d8 100644 --- a/src/doc/src/reference/overriding-dependencies.md +++ b/src/doc/src/reference/overriding-dependencies.md @@ -1,4 +1,4 @@ -## Overriding Dependencies +# Overriding Dependencies The desire to override a dependency can arise through a number of scenarios. Most of them, however, boil down to the ability to work with a crate before @@ -37,7 +37,7 @@ on the different ways to override a dependency. > can be used to override the source for a single dependency declaration in a > local package. -### Testing a bugfix +## Testing a bugfix Let's say you're working with the [`uuid` crate] but while you're working on it you discover a bug. You are, however, quite enterprising so you decide to also @@ -113,7 +113,7 @@ uuid = { git = 'https://github.com/uuid-rs/uuid.git' } [uuid-repository]: https://github.com/uuid-rs/uuid -### Working with an unpublished minor version +## Working with an unpublished minor version Let's now shift gears a bit from bug fixes to adding features. While working on `my-library` you discover that a whole new feature is needed in the `uuid` @@ -171,7 +171,7 @@ if necessary. Here, though, the new `uuid` crate applies to *both* our dependenc one version for this entire crate graph, 1.0.1, and it'll be pulled from the git repository. -#### Overriding repository URL +### Overriding repository URL In case the dependency you want to override isn't loaded from `crates.io`, you'll have to change a bit how you use `[patch]`. For example, if the @@ -184,7 +184,7 @@ my-library = { path = "../my-library/path" } And that's it! -### Prepublishing a breaking change +## Prepublishing a breaking change Let's take a look at working with a new major version of a crate, typically accompanied with breaking changes. Sticking with our previous crates, this @@ -224,7 +224,7 @@ the `my-library` crate will use the `2.0.0` version of `uuid`. This will allow y to gradually roll out breaking changes to a crate through a dependency graph without being forced to update everything all at once. -### Using `[patch]` with multiple versions +## Using `[patch]` with multiple versions You can patch in multiple versions of the same crate with the `package` key used to rename dependencies. For example let's say that the `serde` crate has @@ -248,7 +248,7 @@ Note that when using the `package` key the `serde2` identifier here is actually ignored. We simply need a unique name which doesn't conflict with other patched crates. -### The `[patch]` section +## The `[patch]` section The `[patch]` section of `Cargo.toml` can be used to override dependencies with other copies. The syntax is similar to the @@ -295,7 +295,7 @@ Cargo only looks at the patch settings in the `Cargo.toml` manifest at the root of the workspace. Patch settings defined in dependencies will be ignored. -### The `[replace]` section +## The `[replace]` section > **Note**: `[replace]` is deprecated. You should use the > [`[patch]`](#the-patch-section) table instead. @@ -321,7 +321,7 @@ Cargo only looks at the replace settings in the `Cargo.toml` manifest at the root of the workspace. Replace settings defined in dependencies will be ignored. -### `paths` overrides +## `paths` overrides Sometimes you're only temporarily working on a crate and you don't want to have to modify `Cargo.toml` like with the `[patch]` section above. For this use diff --git a/src/doc/src/reference/pkgid-spec.md b/src/doc/src/reference/pkgid-spec.md index 6c11b4b3d58..bf2e15c8c1f 100644 --- a/src/doc/src/reference/pkgid-spec.md +++ b/src/doc/src/reference/pkgid-spec.md @@ -1,6 +1,6 @@ -## Package ID Specifications +# Package ID Specifications -### Package ID specifications +## Package ID specifications Subcommands of Cargo frequently need to refer to a particular package within a dependency graph for various operations like updating, cleaning, building, etc. @@ -16,7 +16,7 @@ ambiguity, additional qualifiers can be added to make it unique. For example, if there are two versions of the `regex` package in the graph, then it can be qualified with a version to make it unique, such as `regex@1.4.3`. -#### Specification grammar +### Specification grammar The formal grammar for a Package Id Specification is: @@ -33,7 +33,7 @@ Here, brackets indicate that the contents are optional. The URL form can be used for git dependencies, or to differentiate packages that come from different sources such as different registries. -#### Example specifications +### Example specifications The following are references to the `regex` package on `crates.io`: @@ -59,7 +59,7 @@ Local packages on the filesystem can use `file://` URLs to reference them: | `file:///path/to/my/project/foo` | `foo` | `*` | | `file:///path/to/my/project/foo#1.1.8` | `foo` | `1.1.8` | -#### Brevity of specifications +### Brevity of specifications The goal of this is to enable both succinct and exhaustive syntaxes for referring to packages in a dependency graph. Ambiguous references may refer to diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md index c094aa815e1..faf3efe187f 100644 --- a/src/doc/src/reference/profiles.md +++ b/src/doc/src/reference/profiles.md @@ -1,4 +1,4 @@ -## Profiles +# Profiles Profiles provide a way to alter the compiler settings, influencing things like optimizations and debugging symbols. @@ -28,11 +28,11 @@ the settings from `Cargo.toml`. [config]: config.md -### Profile settings +## Profile settings The following is a list of settings that can be controlled in a profile. -#### opt-level +### opt-level The `opt-level` setting controls the [`-C opt-level` flag] which controls the level of optimization. Higher optimization levels may produce faster runtime code at @@ -60,7 +60,7 @@ techniques. [`-C opt-level` flag]: ../../rustc/codegen-options/index.html#opt-level [Profile Guided Optimization]: ../../rustc/profile-guided-optimization.html -#### debug +### debug The `debug` setting controls the [`-C debuginfo` flag] which controls the amount of debug information included in the compiled binary. @@ -82,7 +82,7 @@ depending on your needs as well. [debuginfo]: ../../rustc/codegen-options/index.html#debuginfo [profiling]: https://reviews.llvm.org/D46061 -#### split-debuginfo +### split-debuginfo The `split-debuginfo` setting controls the [`-C split-debuginfo` flag] which controls whether debug information, if generated, is either placed in the @@ -99,7 +99,7 @@ once more testing has been performed, and support for DWARF is stabilized. [nightly channel]: ../../book/appendix-07-nightly-rust.html [`-C split-debuginfo` flag]: ../../rustc/codegen-options/index.html#split-debuginfo -#### strip +### strip The `strip` option controls the [`-C strip` flag], which directs rustc to strip either symbols or debuginfo from a binary. This can be enabled like so: @@ -121,7 +121,7 @@ equivalent to `strip = "none"` and disables `strip` completely. [`-C strip` flag]: ../../rustc/codegen-options/index.html#strip -#### debug-assertions +### debug-assertions The `debug-assertions` setting controls the [`-C debug-assertions` flag] which turns `cfg(debug_assertions)` [conditional compilation] on or off. Debug @@ -139,7 +139,7 @@ The valid options are: [conditional compilation]: ../../reference/conditional-compilation.md#debug_assertions [`debug_assert!` macro]: ../../std/macro.debug_assert.html -#### overflow-checks +### overflow-checks The `overflow-checks` setting controls the [`-C overflow-checks` flag] which controls the behavior of [runtime integer overflow]. When overflow-checks are @@ -153,7 +153,7 @@ The valid options are: [`-C overflow-checks` flag]: ../../rustc/codegen-options/index.html#overflow-checks [runtime integer overflow]: ../../reference/expressions/operator-expr.md#overflow -#### lto +### lto The `lto` setting controls `rustc`'s [`-C lto`], [`-C linker-plugin-lto`], and [`-C embed-bitcode`] options, which control LLVM's [link time optimizations]. @@ -183,7 +183,7 @@ This is not yet supported natively in Cargo, but can be performed via [linker-plugin-lto chapter]: ../../rustc/linker-plugin-lto.html ["thin" LTO]: http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html -#### panic +### panic The `panic` setting controls the [`-C panic` flag] which controls which panic strategy to use. @@ -207,7 +207,7 @@ dependencies will also be forced to build with the `unwind` strategy. [`-C panic` flag]: ../../rustc/codegen-options/index.html#panic [`panic-abort-tests`]: unstable.md#panic-abort-tests -#### incremental +### incremental The `incremental` setting controls the [`-C incremental` flag] which controls whether or not incremental compilation is enabled. Incremental compilation @@ -230,7 +230,7 @@ The incremental value can be overridden globally with the `CARGO_INCREMENTAL` [environment variable]: environment-variables.md [`build.incremental`]: config.md#buildincremental -#### codegen-units +### codegen-units The `codegen-units` setting controls the [`-C codegen-units` flag] which controls how many "code generation units" a crate will be split into. More @@ -244,7 +244,7 @@ non-incremental builds. [`-C codegen-units` flag]: ../../rustc/codegen-options/index.html#codegen-units -#### rpath +### rpath The `rpath` setting controls the [`-C rpath` flag] which controls whether or not [`rpath`] is enabled. @@ -252,9 +252,9 @@ whether or not [`rpath`] is enabled. [`-C rpath` flag]: ../../rustc/codegen-options/index.html#rpath [`rpath`]: https://en.wikipedia.org/wiki/Rpath -### Default profiles +## Default profiles -#### dev +### dev The `dev` profile is used for normal development and debugging. It is the default for build commands like [`cargo build`], and is used for `cargo install --debug`. @@ -275,7 +275,7 @@ codegen-units = 256 rpath = false ``` -#### release +### release The `release` profile is intended for optimized artifacts used for releases and in production. This profile is used when the `--release` flag is used, and @@ -297,17 +297,17 @@ codegen-units = 16 rpath = false ``` -#### test +### test The `test` profile is the default profile used by [`cargo test`]. The `test` profile inherits the settings from the [`dev`](#dev) profile. -#### bench +### bench The `bench` profile is the default profile used by [`cargo bench`]. The `bench` profile inherits the settings from the [`release`](#release) profile. -#### Build Dependencies +### Build Dependencies To compile quickly, all profiles, by default, do not optimize build dependencies (build scripts, proc macros, and their dependencies), and avoid @@ -335,7 +335,7 @@ debug = true Build dependencies otherwise inherit settings from the active profile in use, as described in [Profile selection](#profile-selection). -### Custom profiles +## Custom profiles In addition to the built-in profiles, additional custom profiles can be defined. These may be useful for setting up multiple workflows and build @@ -365,7 +365,7 @@ output would go into the `target/release-lto` directory. [`target` directory]: ../guide/build-cache.md -### Profile selection +## Profile selection The profile used depends on the command, the command-line flags like `--release` or `--profile`, and the package (in the case of @@ -399,7 +399,7 @@ The profile for specific packages can be specified with [`cargo rustc`]: ../commands/cargo-rustc.md [`cargo test`]: ../commands/cargo-test.md -### Overrides +## Overrides Profile settings can be overridden for specific packages and build-time crates. To override the settings for a specific package, use the `package` @@ -451,7 +451,7 @@ match wins): Overrides cannot specify the `panic`, `lto`, or `rpath` settings. -#### Overrides and generics +### Overrides and generics The location where generic code is instantiated will influence the optimization settings used for that generic code. This can cause subtle diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md index 564dfb34e5b..959153cd7a7 100644 --- a/src/doc/src/reference/publishing.md +++ b/src/doc/src/reference/publishing.md @@ -1,4 +1,4 @@ -## Publishing on crates.io +# Publishing on crates.io Once you've got a library that you'd like to share with the world, it's time to publish it on [crates.io]! Publishing a crate is when a specific @@ -8,7 +8,7 @@ Take care when publishing a crate, because a publish is **permanent**. The version can never be overwritten, and the code cannot be deleted. There is no limit to the number of versions which can be published, however. -### Before your first publish +## Before your first publish First things first, you’ll need an account on [crates.io] to acquire an API token. To do so, [visit the home page][crates.io] and log in via a GitHub @@ -38,7 +38,7 @@ immediately. > `credentials.toml`. This can be useful if you no longer need it stored on > the local machine. -### Before publishing a new crate +## Before publishing a new crate Keep in mind that crate names on [crates.io] are allocated on a first-come-first-serve basis. Once a crate name is taken, it cannot be used for another crate. @@ -60,7 +60,7 @@ though they are not required. If you are publishing a library, you may also want to consult the [Rust API Guidelines]. -#### Packaging a crate +### Packaging a crate The next step is to package up your crate and upload it to [crates.io]. For this we’ll use the [`cargo publish`] subcommand. This command performs the following @@ -119,7 +119,7 @@ include = [ ] ``` -### Uploading the crate +## Uploading the crate When you are ready to publish, use the [`cargo publish`] command to upload to [crates.io]: @@ -130,19 +130,19 @@ $ cargo publish And that’s it, you’ve now published your first crate! -### Publishing a new version of an existing crate +## Publishing a new version of an existing crate In order to release a new version, change [the `version` value](manifest.md#the-version-field) specified in your `Cargo.toml` manifest. Keep in mind [the SemVer rules](semver.md) which provide guidelines on what is a compatible change. Then run [`cargo publish`] as described above to upload the new version. -### Managing a crates.io-based crate +## Managing a crates.io-based crate Management of crates is primarily done through the command line `cargo` tool rather than the [crates.io] web interface. For this, there are a few subcommands to manage a crate. -#### `cargo yank` +### `cargo yank` Occasions may arise where you publish a version of a crate that actually ends up being broken for one reason or another (syntax error, forgot to include a file, @@ -166,7 +166,7 @@ goal. Essentially a yank means that all packages with a `Cargo.lock` will not break, while any future `Cargo.lock` files generated will not list the yanked version. -#### `cargo owner` +### `cargo owner` A crate is often developed by more than one person, or the primary maintainer may change over time! The owner of a crate is the only person allowed to publish @@ -198,7 +198,7 @@ The syntax for teams is currently `github:org:team` (see examples above). In order to invite a team as an owner one must be a member of that team. No such restriction applies to removing a team as an owner. -### GitHub permissions +## GitHub permissions Team membership is not something GitHub provides simple public access to, and it is likely for you to encounter the following message when working with them: @@ -250,7 +250,7 @@ the “Grant Access” button next to its name: ![Authentication Access Control](../images/auth-level-acl.png) -#### Troubleshooting GitHub team access errors +### Troubleshooting GitHub team access errors When trying to add a GitHub team as crate owner, you may see an error like: diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md index 7714a36cdbc..74c81943579 100644 --- a/src/doc/src/reference/registries.md +++ b/src/doc/src/reference/registries.md @@ -1,4 +1,4 @@ -## Registries +# Registries Cargo installs crates and fetches dependencies from a "registry". The default registry is [crates.io]. A registry contains an "index" which contains a @@ -11,7 +11,7 @@ support publishing new crates directly from Cargo. If you are implementing a registry server, see [Running a Registry] for more details about the protocol between Cargo and a registry. -### Using an Alternate Registry +## Using an Alternate Registry To use a registry other than [crates.io], the name and index URL of the registry must be added to a [`.cargo/config.toml` file][config]. The `registries` @@ -51,7 +51,7 @@ CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index > Note: [crates.io] does not accept packages that depend on crates from other > registries. -### Publishing to an Alternate Registry +## Publishing to an Alternate Registry If the registry supports web API access, then packages can be published directly to the registry from Cargo. Several of Cargo's commands such as @@ -100,7 +100,7 @@ has a separate table for each registry, for example: token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" ``` -### Registry Protocols +## Registry Protocols Cargo supports two remote registry protocols: `git` and `sparse`. If the registry index URL starts with `sparse+`, Cargo uses the sparse protocol. Otherwise Cargo uses the `git` protocol. diff --git a/src/doc/src/reference/registry-index.md b/src/doc/src/reference/registry-index.md index 3eed6ef3945..7f331b826c1 100644 --- a/src/doc/src/reference/registry-index.md +++ b/src/doc/src/reference/registry-index.md @@ -1,4 +1,4 @@ -## Index Format +# Index Format The following defines the format of the index. New features are occasionally added, which are only understood starting with the version of Cargo that @@ -6,7 +6,7 @@ introduced them. Older versions of Cargo may not be able to use packages that make use of new features. However, the format for older packages should not change, so older versions of Cargo should be able to use them. -### Index Configuration +## Index Configuration The root of the index contains a file named `config.json` which contains JSON information used by Cargo for accessing the registry. This is an example of what the [crates.io] config file looks like: @@ -37,14 +37,14 @@ The keys are: API is described below. -### Download Endpoint +## Download Endpoint The download endpoint should send the `.crate` file for the requested package. Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2. The exact specifics of TLS support depend on the platform that Cargo is running on, the version of Cargo, and how it was compiled. -### Index files +## Index files The rest of the index repository contains one file for each package, where the filename is the name of the package in lowercase. Each version of the package has a separate line in the file. The files are organized in a tier of @@ -80,7 +80,7 @@ harder to support older versions of Cargo that lack `{prefix}`/`{lowerprefix}`. For example, nginx rewrite rules can easily construct `{prefix}` but can't perform case-conversion to construct `{lowerprefix}`. -### Name restrictions +## Name restrictions Registries should consider enforcing limitations on package names added to their index. Cargo itself allows names with any [alphanumeric], `-`, or `_` @@ -100,13 +100,13 @@ attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack) and other concerns in [UTR36](https://www.unicode.org/reports/tr36/) and [UTS39](https://www.unicode.org/reports/tr39/). -### Version uniqueness +## Version uniqueness Indexes *must* ensure that each version only appears once for each package. This includes ignoring SemVer build metadata. For example, the index must *not* contain two entries with a version `1.0.7` and `1.0.7+extra`. -### JSON schema +## JSON schema Each line in a package file contains a JSON object that describes a published version of the package. The following is a pretty-printed example with comments @@ -254,19 +254,19 @@ The JSON objects should not be modified after they are added except for the [Publish API]: registry-web-api.md#publish [`cargo metadata`]: ../commands/cargo-metadata.md -### Index Protocols +## Index Protocols Cargo supports two remote registry protocols: `git` and `sparse`. The `git` protocol stores index files in a git repository and the `sparse` protocol fetches individual files over HTTP. -#### Git Protocol +### Git Protocol The git protocol has no protocol prefix in the index url. For example the git index URL for [crates.io] is `https://github.com/rust-lang/crates.io-index`. Cargo caches the git repository on disk so that it can efficiently incrementally fetch updates. -#### Sparse Protocol +### Sparse Protocol The sparse protocol uses the `sparse+` protocol prefix in the registry URL. For example, the sparse index URL for [crates.io] is `sparse+https://index.crates.io/`. @@ -274,24 +274,24 @@ The sparse protocol downloads each index file using an individual HTTP request. this results in a large number of small HTTP requests, performance is significantly improved with a server that supports pipelining and HTTP/2. -##### Caching +#### Caching Cargo caches the crate metadata files, and captures the `ETag` or `Last-Modified` HTTP header from the server for each entry. When refreshing crate metadata, Cargo sends the `If-None-Match` or `If-Modified-Since` header to allow the server to respond with HTTP 304 "Not Modified" if the local cache is valid, saving time and bandwidth. If both `ETag` and `Last-Modified` headers are present, Cargo uses the `ETag` only. -##### Cache Invalidation +#### Cache Invalidation If a registry is using some kind of CDN or proxy which caches access to the index files, then it is recommended that registries implement some form of cache invalidation when the files are updated. If these caches are not updated, then users may not be able to access new crates until the cache is cleared. -##### Nonexistent Crates +#### Nonexistent Crates For crates that do not exist, the registry should respond with a 404 "Not Found", 410 "Gone" or 451 "Unavailable For Legal Reasons" code. -##### Sparse Limitations +#### Sparse Limitations Since the URL of the registry is stored in the lockfile, it's not recommended to offer a registry with both protocols. Discussion about a transition plan is ongoing in issue [#10964]. The [crates.io] registry is an exception, since Cargo internally substitutes diff --git a/src/doc/src/reference/registry-web-api.md b/src/doc/src/reference/registry-web-api.md index 8260028c020..757ec14bc93 100644 --- a/src/doc/src/reference/registry-web-api.md +++ b/src/doc/src/reference/registry-web-api.md @@ -1,5 +1,4 @@ - -## Web API +# Web API A registry may host a web API at the location defined in `config.json` to support any of the actions listed below. @@ -47,7 +46,7 @@ Cargo sets the following headers for all requests: 2019-01-02)`. This may be modified by the user in a configuration value. Added in 1.29. -### Publish +## Publish - Endpoint: `/api/v1/crates/new` - Method: PUT @@ -184,7 +183,7 @@ A successful response includes the JSON object: } ``` -### Yank +## Yank - Endpoint: `/api/v1/crates/{crate_name}/{version}/yank` - Method: DELETE @@ -202,7 +201,7 @@ A successful response includes the JSON object: } ``` -### Unyank +## Unyank - Endpoint: `/api/v1/crates/{crate_name}/{version}/unyank` - Method: PUT @@ -220,7 +219,7 @@ A successful response includes the JSON object: } ``` -### Owners +## Owners Cargo does not have an inherent notion of users and owners, but it does provide the `owner` command to assist managing who has authorization to @@ -228,7 +227,7 @@ control a crate. It is up to the registry to decide exactly how users and owners are handled. See the [publishing documentation] for a description of how [crates.io] handles owners via GitHub users and teams. -#### Owners: List +### Owners: List - Endpoint: `/api/v1/crates/{crate_name}/owners` - Method: GET @@ -255,7 +254,7 @@ A successful response includes the JSON object: } ``` -#### Owners: Add +### Owners: Add - Endpoint: `/api/v1/crates/{crate_name}/owners` - Method: PUT @@ -286,7 +285,7 @@ A successful response includes the JSON object: } ``` -#### Owners: Remove +### Owners: Remove - Endpoint: `/api/v1/crates/{crate_name}/owners` - Method: DELETE @@ -313,7 +312,7 @@ A successful response includes the JSON object: } ``` -### Search +## Search - Endpoint: `/api/v1/crates` - Method: GET @@ -346,7 +345,7 @@ A successful response includes the JSON object: } ``` -### Login +## Login - Endpoint: `/me` diff --git a/src/doc/src/reference/running-a-registry.md b/src/doc/src/reference/running-a-registry.md index 144f1ee6af7..87ab08ede33 100644 --- a/src/doc/src/reference/running-a-registry.md +++ b/src/doc/src/reference/running-a-registry.md @@ -1,4 +1,4 @@ -## Running a Registry +# Running a Registry A minimal registry can be implemented by having a git repository that contains an index, and a server that contains the compressed `.crate` files created by diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md index b8bcdc7ae2b..520604e5c0f 100644 --- a/src/doc/src/reference/source-replacement.md +++ b/src/doc/src/reference/source-replacement.md @@ -1,4 +1,4 @@ -## Source Replacement +# Source Replacement This document is about replacing the crate index. You can read about overriding dependencies in the [overriding dependencies] section of this @@ -34,7 +34,7 @@ token for the specified registry. [overriding dependencies]: overriding-dependencies.md [registries]: registries.md -### Configuration +## Configuration Configuration of replacement sources is done through [`.cargo/config.toml`][config] and the full set of available keys are: @@ -82,7 +82,7 @@ git = "https://example.com/path/to/repo" [config]: config.md -### Registry Sources +## Registry Sources A "registry source" is one that is the same as crates.io itself. That is, it has an index served in a git repository which matches the format of the @@ -92,7 +92,7 @@ then has configuration indicating where to download crates from. Currently there is not an already-available project for setting up a mirror of crates.io. Stay tuned though! -### Local Registry Sources +## Local Registry Sources A "local registry source" is intended to be a subset of another registry source, but available on the local filesystem (aka vendoring). Local registries @@ -111,7 +111,7 @@ Local registries are contained within one directory and contain a number of the same format as the crates.io-index project (populated with just entries for the crates that are present). -### Directory Sources +## Directory Sources A "directory source" is similar to a local registry source where it contains a number of crates available on the local filesystem, suitable for vendoring diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index f08d508a21d..19cc715e3d8 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -1,4 +1,4 @@ -## Specifying Dependencies +# Specifying Dependencies Your crates can depend on other libraries from [crates.io] or other registries, `git` repositories, or subdirectories on your local file system. @@ -8,7 +8,7 @@ locally. You can have different dependencies for different platforms, and dependencies that are only used during development. Let's take a look at how to do each of these. -### Specifying dependencies from crates.io +## Specifying dependencies from crates.io Cargo is configured to look for dependencies on [crates.io] by default. Only the name and a version string are required in this case. In [the cargo @@ -53,14 +53,14 @@ and `x > 0`. It is possible to further tweak the logic for selecting compatible versions using special operators, though it shouldn't be necessary most of the time. -### Version requirement syntax +## Version requirement syntax -#### Caret requirements +### Caret requirements **Caret requirements** are an alternative syntax for the default strategy, `^1.2.3` is exactly equivalent to `1.2.3`. -#### Tilde requirements +### Tilde requirements **Tilde requirements** specify a minimal version with some ability to update. If you specify a major, minor, and patch version or only a major and minor @@ -75,7 +75,7 @@ version, then minor- and patch-level changes are allowed. ~1 := >=1.0.0, <2.0.0 ``` -#### Wildcard requirements +### Wildcard requirements **Wildcard requirements** allow for any version where the wildcard is positioned. @@ -90,7 +90,7 @@ positioned. > **Note**: [crates.io] does not allow bare `*` versions. -#### Comparison requirements +### Comparison requirements **Comparison requirements** allow manually specifying a version range or an exact version to depend on. @@ -104,7 +104,7 @@ Here are some examples of comparison requirements: = 1.2.3 ``` -#### Multiple version requirements +### Multiple version requirements As shown in the examples above, multiple version requirements can be separated with a comma, e.g., `>= 1.2, < 1.5`. @@ -146,7 +146,7 @@ separated with a comma, e.g., `>= 1.2, < 1.5`. [#6584]: https://github.com/rust-lang/cargo/issues/6584 [#10599]: https://github.com/rust-lang/cargo/issues/10599 -### Specifying dependencies from other registries +## Specifying dependencies from other registries To specify a dependency from a registry other than [crates.io], first the registry must be configured in a `.cargo/config.toml` file. See the [registries @@ -163,7 +163,7 @@ some-crate = { version = "1.0", registry = "my-registry" } [registries documentation]: registries.md -### Specifying dependencies from `git` repositories +## Specifying dependencies from `git` repositories To depend on a library located in a `git` repository, the minimum information you need to specify is the location of the repository with the `git` key: @@ -221,7 +221,7 @@ See [Git Authentication] for help with git authentication for private repos. [Git Authentication]: ../appendix/git-authentication.md -### Specifying path dependencies +## Specifying path dependencies Over time, our `hello_world` package from [the guide](../guide/index.md) has grown significantly in size! It’s gotten to the point that we probably want to @@ -269,7 +269,7 @@ hello_utils = { path = "hello_utils", version = "0.1.0" } > locations](#multiple-locations) section for a fallback alternative for `git` > and `path` dependencies. -### Multiple locations +## Multiple locations It is possible to specify both a registry version and a `git` or `path` location. The `git` or `path` dependency will be used locally (in which case @@ -298,7 +298,7 @@ is published. This is similar to specifying an [override](overriding-dependencies.md), but only applies to this one dependency declaration. -### Platform specific dependencies +## Platform specific dependencies Platform-specific dependencies take the same format, but are listed under a `target` section. Normally Rust-like [`#[cfg]` @@ -357,7 +357,7 @@ winhttp = "0.4.0" openssl = "1.0.1" ``` -#### Custom target specifications +### Custom target specifications If you’re using a custom target specification (such as `--target foo/bar.json`), use the base filename without the `.json` extension: @@ -373,7 +373,7 @@ native = { path = "native/i686" } > **Note**: Custom target specifications are not usable on the stable channel. -### Development dependencies +## Development dependencies You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format is equivalent to `[dependencies]`: @@ -405,7 +405,7 @@ mio = "0.0.1" > packagers) may want to run tests within a crate, so providing a `version` if > possible can still be beneficial. -### Build dependencies +## Build dependencies You can depend on other Cargo-based crates for use in your build scripts. Dependencies are declared through the `build-dependencies` section of the @@ -437,7 +437,7 @@ itself and its build script are built separately, so their dependencies need not coincide. Cargo is kept simpler and cleaner by using independent dependencies for independent purposes. -### Choosing features +## Choosing features If a package you depend on offers conditional features, you can specify which to use: @@ -453,7 +453,7 @@ features = ["secure-password", "civet"] More information about features can be found in the [features chapter](features.md#dependency-features). -### Renaming dependencies in `Cargo.toml` +## Renaming dependencies in `Cargo.toml` When writing a `[dependencies]` section in `Cargo.toml` the key you write for a dependency typically matches up to the name of the crate you import from in the @@ -512,7 +512,7 @@ following to the above manifest: log-debug = ['bar/log-debug'] # using 'foo/log-debug' would be an error! ``` -### Inheriting a dependency from a workspace +## Inheriting a dependency from a workspace Dependencies can be inherited from a workspace by specifying the dependency in the workspace's [`[workspace.dependencies]`][workspace.dependencies] table. diff --git a/src/doc/src/reference/timings.md b/src/doc/src/reference/timings.md index b978d52cded..e8ff751caf5 100644 --- a/src/doc/src/reference/timings.md +++ b/src/doc/src/reference/timings.md @@ -10,7 +10,7 @@ This writes an HTML report in `target/cargo-timings/cargo-timing.html`. This also writes a copy of the report to the same directory with a timestamp in the filename, if you want to look at older runs. -#### Reading the graphs +## Reading the graphs There are two tables and two graphs in the output. diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 84d4d02fe76..0de66af6359 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -1,4 +1,4 @@ -## Unstable Features +# Unstable Features Experimental Cargo features are only available on the [nightly channel]. You are encouraged to experiment with these features to see if they meet your @@ -59,7 +59,7 @@ For the latest nightly, see the [nightly version] of this page. [stabilized]: https://doc.crates.io/contrib/process/unstable.html#stabilization [nightly version]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#script -### List of unstable features +## List of unstable features * Unstable-specific features * [-Z allow-features](#allow-features) --- Provides a way to restrict which unstable features are used. @@ -109,7 +109,7 @@ For the latest nightly, see the [nightly version] of this page. * [gitoxide](#gitoxide) --- Use `gitoxide` instead of `git2` for a set of operations. * [script](#script) --- Enable support for single-file `.rs` packages. -### allow-features +## allow-features This permanently-unstable flag makes it so that only a listed set of unstable features can be used. Specifically, if you pass @@ -135,7 +135,7 @@ to any Rust tools that cargo ends up calling (like `rustc` or `rustdoc`). Thus, if you run `cargo -Zallow-features=`, no unstable Cargo _or_ Rust features can be used. -### no-index-update +## no-index-update * Original Issue: [#3479](https://github.com/rust-lang/cargo/issues/3479) * Tracking Issue: [#7404](https://github.com/rust-lang/cargo/issues/7404) @@ -144,7 +144,7 @@ the registry index. This is intended for tools such as Crater that issue many Cargo commands, and you want to avoid the network latency for updating the index each time. -### mtime-on-use +## mtime-on-use * Original Issue: [#6477](https://github.com/rust-lang/cargo/pull/6477) * Cache usage meta tracking issue: [#7150](https://github.com/rust-lang/cargo/issues/7150) @@ -155,7 +155,7 @@ To make this more practical setting the `unstable.mtime_on_use` flag in `.cargo/ or the corresponding ENV variable will apply the `-Z mtime-on-use` to all invocations of nightly cargo. (the config flag is ignored by stable) -### avoid-dev-deps +## avoid-dev-deps * Original Issue: [#4988](https://github.com/rust-lang/cargo/issues/4988) * Tracking Issue: [#5133](https://github.com/rust-lang/cargo/issues/5133) @@ -165,7 +165,7 @@ used. The `-Z avoid-dev-deps` flag allows Cargo to avoid downloading dev-dependencies if they are not needed. The `Cargo.lock` file will not be generated if dev-dependencies are skipped. -### minimal-versions +## minimal-versions * Original Issue: [#4100](https://github.com/rust-lang/cargo/issues/4100) * Tracking Issue: [#5657](https://github.com/rust-lang/cargo/issues/5657) @@ -185,7 +185,7 @@ minimum versions that you are actually using. That is, if Cargo.toml says `foo = "1.0.0"` that you don't accidentally depend on features added only in `foo 1.5.0`. -### direct-minimal-versions +## direct-minimal-versions * Original Issue: [#4100](https://github.com/rust-lang/cargo/issues/4100) * Tracking Issue: [#5657](https://github.com/rust-lang/cargo/issues/5657) @@ -202,7 +202,7 @@ minimum versions that you are actually using. That is, if Cargo.toml says Indirect dependencies are resolved as normal so as not to be blocked on their minimal version validation. -### out-dir +## out-dir * Original Issue: [#4875](https://github.com/rust-lang/cargo/issues/4875) * Tracking Issue: [#6790](https://github.com/rust-lang/cargo/issues/6790) @@ -225,7 +225,7 @@ This can also be specified in `.cargo/config.toml` files. out-dir = "out" ``` -### doctest-xcompile +## doctest-xcompile * Tracking Issue: [#7040](https://github.com/rust-lang/cargo/issues/7040) * Tracking Rustc Issue: [#64245](https://github.com/rust-lang/rust/issues/64245) @@ -241,7 +241,7 @@ information from `.cargo/config.toml`. See the rustc issue for more information. cargo test --target foo -Zdoctest-xcompile ``` -### Build-plan +## Build-plan * Tracking Issue: [#5579](https://github.com/rust-lang/cargo/issues/5579) The `--build-plan` argument for the `build` command will output JSON with @@ -253,7 +253,7 @@ Example: cargo +nightly build --build-plan -Z unstable-options ``` -### Metabuild +## Metabuild * Tracking Issue: [rust-lang/rust#49803](https://github.com/rust-lang/rust/issues/49803) * RFC: [#2196](https://github.com/rust-lang/rfcs/blob/master/text/2196-metabuild.md) @@ -286,7 +286,7 @@ extra-info = "qwerty" Metabuild packages should have a public function called `metabuild` that performs the same actions as a regular `build.rs` script would perform. -### public-dependency +## public-dependency * Tracking Issue: [#44663](https://github.com/rust-lang/rust/issues/44663) The 'public-dependency' feature allows marking dependencies as 'public' @@ -303,7 +303,7 @@ my_dep = { version = "1.2.3", public = true } private_dep = "2.0.0" # Will be 'private' by default ``` -### msrv-policy +## msrv-policy - [#9930](https://github.com/rust-lang/cargo/issues/9930) (MSRV-aware resolver) - [#10653](https://github.com/rust-lang/cargo/issues/10653) (MSRV-aware cargo-add) - [#10903](https://github.com/rust-lang/cargo/issues/10903) (MSRV-aware cargo-install) @@ -311,7 +311,7 @@ private_dep = "2.0.0" # Will be 'private' by default The `msrv-policy` feature enables experiments in MSRV-aware policy for cargo in preparation for an upcoming RFC. -### build-std +## build-std * Tracking Repository: The `build-std` feature enables Cargo to compile the standard library itself as @@ -366,7 +366,7 @@ $ cargo +nightly build -Z build-std=core,alloc The value here is a comma-separated list of standard library crates to build. -#### Requirements +### Requirements As a summary, a list of requirements today to use `-Z build-std` are: @@ -375,7 +375,7 @@ As a summary, a list of requirements today to use `-Z build-std` are: * You must use both a nightly Cargo and a nightly rustc * The `-Z build-std` flag must be passed to all `cargo` invocations. -#### Reporting bugs and helping out +### Reporting bugs and helping out The `-Z build-std` feature is in the very early stages of development! This feature for Cargo has an extremely long history and is very large in scope, and @@ -392,7 +392,7 @@ something doesn't quite work the way you'd like it to, feel free to check out the [issue tracker](https://github.com/rust-lang/wg-cargo-std-aware/issues) of the tracking repository, and if it's not there please file a new issue! -### build-std-features +## build-std-features * Tracking Repository: This flag is a sibling to the `-Zbuild-std` feature flag. This will configure @@ -401,7 +401,7 @@ library. The default enabled features, at this time, are `backtrace` and `panic-unwind`. This flag expects a comma-separated list and, if provided, will override the default list of features enabled. -### binary-dep-depinfo +## binary-dep-depinfo * Tracking rustc issue: [#63012](https://github.com/rust-lang/rust/issues/63012) The `-Z binary-dep-depinfo` flag causes Cargo to forward the same flag to @@ -412,7 +412,7 @@ the crate will be rebuilt). The primary use case is for building the compiler itself, which has implicit dependencies on the standard library that would otherwise be untracked for change-detection. -### panic-abort-tests +## panic-abort-tests * Tracking Issue: [#67650](https://github.com/rust-lang/rust/issues/67650) * Original Pull Request: [#7460](https://github.com/rust-lang/cargo/pull/7460) @@ -428,7 +428,7 @@ like to stabilize it somehow! [rust-lang/rust#64158]: https://github.com/rust-lang/rust/pull/64158 -### config-include +## config-include * Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723) This feature requires the `-Zconfig-include` command-line option. @@ -456,7 +456,7 @@ different. When a config file contains an `include` key: 2. Then, the config file's own values are merged on top of the config from the `include` path. -### target-applies-to-host +## target-applies-to-host * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322) * Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453) @@ -498,7 +498,7 @@ target-applies-to-host = false cargo +nightly -Ztarget-applies-to-host build --target x86_64-unknown-linux-gnu ``` -### host-config +## host-config * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322) * Tracking Issue: [#9452](https://github.com/rust-lang/cargo/issues/9452) @@ -533,7 +533,7 @@ Setting `-Zhost-config` changes the default for `target-applies-to-host` to cargo +nightly -Ztarget-applies-to-host -Zhost-config build --target x86_64-unknown-linux-gnu ``` -### unit-graph +## unit-graph * Tracking Issue: [#8002](https://github.com/rust-lang/cargo/issues/8002) The `--unit-graph` flag can be passed to any build command (`build`, `check`, @@ -667,7 +667,7 @@ The following is a description of the JSON structure: } ``` -### Profile `rustflags` option +## Profile `rustflags` option * Original Issue: [rust-lang/cargo#7878](https://github.com/rust-lang/cargo/issues/7878) * Tracking Issue: [rust-lang/cargo#10271](https://github.com/rust-lang/cargo/issues/10271) @@ -697,7 +697,7 @@ profile-rustflags = true rustflags = [ "-C", "..." ] ``` -### rustdoc-map +## rustdoc-map * Tracking Issue: [#8296](https://github.com/rust-lang/cargo/issues/8296) This feature adds configuration settings that are passed to `rustdoc` so that @@ -738,7 +738,7 @@ The default value is `"remote"`. The value may also take a URL for a custom location. -### per-package-target +## per-package-target * Tracking Issue: [#9406](https://github.com/rust-lang/cargo/pull/9406) * Original Pull Request: [#9030](https://github.com/rust-lang/cargo/pull/9030) * Original Issue: [#7004](https://github.com/rust-lang/cargo/pull/7004) @@ -761,7 +761,7 @@ In this example, the crate is always built for as a plugin for a main program that runs on the host (or provided on the command line) target. -### artifact-dependencies +## artifact-dependencies * Tracking Issue: [#9096](https://github.com/rust-lang/cargo/pull/9096) * Original Pull Request: [#9992](https://github.com/rust-lang/cargo/pull/9992) @@ -771,7 +771,7 @@ and use the artifacts built by those crates at compile time. Run `cargo` with `-Z bindeps` to enable this functionality. -#### artifact-dependencies: Dependency declarations +### artifact-dependencies: Dependency declarations Artifact-dependencies adds the following keys to a dependency declaration in `Cargo.toml`: @@ -823,7 +823,7 @@ Artifact-dependencies adds the following keys to a dependency declaration in `Ca same-target = { version = "1.0", artifact = "bin", target = "target" } ``` -#### artifact-dependencies: Environment variables +### artifact-dependencies: Environment variables After building an artifact dependency, Cargo provides the following environment variables that you can use to access the artifact: @@ -852,9 +852,9 @@ For each kind of dependency, these variables are supplied to the same part of th [`env!`]: https://doc.rust-lang.org/std/macro.env.html -#### artifact-dependencies: Examples +### artifact-dependencies: Examples -##### Example: use a binary executable from a build script +#### Example: use a binary executable from a build script In the `Cargo.toml` file, you can specify a dependency on a binary to make available for a build script: @@ -879,7 +879,7 @@ fn main() { } ``` -##### Example: use _cdylib_ artifact in build script +#### Example: use _cdylib_ artifact in build script The `Cargo.toml` in the consuming package, building the `bar` library as `cdylib` for a specific build target… @@ -897,7 +897,7 @@ fn main() { } ``` -##### Example: use _binary_ artifact and its library in a binary +#### Example: use _binary_ artifact and its library in a binary The `Cargo.toml` in the consuming package, building the `bar` binary for inclusion as artifact while making it available as library as well… @@ -916,7 +916,7 @@ fn main() { } ``` -### publish-timeout +## publish-timeout * Tracking Issue: [11222](https://github.com/rust-lang/cargo/issues/11222) The `publish.timeout` key in a config file can be used to control how long @@ -934,7 +934,7 @@ It requires the `-Zpublish-timeout` command-line options to be set. timeout = 300 # in seconds ``` -### registry-auth +## registry-auth * Tracking Issue: [10474](https://github.com/rust-lang/cargo/issues/10474) * RFC: [#3139](https://github.com/rust-lang/rfcs/pull/3139) @@ -958,7 +958,7 @@ can go to get a token. WWW-Authenticate: Cargo login_url="https://test-registry-login/me ``` -### asymmetric-token +## asymmetric-token * Tracking Issue: [10519](https://github.com/rust-lang/cargo/issues/10519) * RFC: [#3231](https://github.com/rust-lang/rfcs/pull/3231) @@ -998,7 +998,7 @@ The "footer" (which is part of the signature) will be a JSON string in UTF-8 and PASETO includes the message that was signed, so the server does not have to reconstruct the exact string from the request in order to check the signature. The server does need to check that the signature is valid for the string in the PASETO and that the contents of that string matches the request. If a claim should be expected for the request but is missing in the PASETO then the request must be rejected. -### credential-process +## credential-process * Tracking Issue: [#8933](https://github.com/rust-lang/cargo/issues/8933) * RFC: [#2730](https://github.com/rust-lang/rfcs/pull/2730) @@ -1008,7 +1008,7 @@ authentication tokens by calling an external process. To use this feature, you must pass the `-Z credential-process` flag on the command-line. -#### `credential-process` Configuration +### `credential-process` Configuration To configure which process to run to fetch the token, specify the process in the `registry` table in a [config file] with spaces separating arguments. If the @@ -1062,7 +1062,7 @@ my-alias = ["/usr/bin/cargo-creds", "--argument"] global-credential-providers = ["cargo:token", "my-alias"] ``` -#### Built-in providers +### Built-in providers Cargo now includes several built-in credential providers. These providers are executed within the Cargo process. They are identified with the `cargo:` prefix. @@ -1107,7 +1107,7 @@ In the config, add it to `global-credential-providers`: global-credential-providers = ["cargo-credential-1password"] ``` -#### JSON Interface +### JSON Interface When using an external credential provider, Cargo communicates with the credential provider using stdin/stdout messages passed as a single line of JSON. @@ -1118,7 +1118,7 @@ how Cargo uses it. The messages here have additional newlines added for readability. Actual messages must not contain newlines. -##### Credential hello +#### Credential hello * Sent by: credential provider * Purpose: used to identify the supported protocols on process startup ```javascript @@ -1127,7 +1127,7 @@ Actual messages must not contain newlines. } ``` -##### Login request +#### Login request * Sent by: Cargo * Purpose: collect and store credentials ```javascript @@ -1141,7 +1141,7 @@ Actual messages must not contain newlines. } ``` -##### Read request +#### Read request * Sent by: Cargo * Purpose: Get the credential for reading crate information ```javascript @@ -1159,7 +1159,7 @@ Actual messages must not contain newlines. } ``` -##### Publish request +#### Publish request * Sent by: Cargo * Purpose: Get the credential for publishing a crate ```javascript @@ -1183,7 +1183,7 @@ Actual messages must not contain newlines. } ``` -##### Success response +#### Success response * Sent by: credential process * Purpose: Gives the credential to Cargo ```javascript @@ -1202,7 +1202,7 @@ Actual messages must not contain newlines. }} ``` -##### Failure response +#### Failure response * Sent by: credential process * Purpose: Gives error information to Cargo ```javascript @@ -1221,7 +1221,7 @@ Actual messages must not contain newlines. }} ``` -##### Example communication to request a token for reading: +#### Example communication to request a token for reading: 1. Cargo spawns the credential process, capturing stdin and stdout. 2. Credential process sends the Hello message to Cargo ```javascript @@ -1257,7 +1257,7 @@ Actual messages must not contain newlines. [crates.io]: https://crates.io/ [config file]: config.md -### `cargo config` +## `cargo config` * Original Issue: [#2362](https://github.com/rust-lang/cargo/issues/2362) * Tracking Issue: [#9301](https://github.com/rust-lang/cargo/issues/9301) @@ -1273,7 +1273,7 @@ cargo +nightly -Zunstable-options config get build.rustflags If no config value is included, it will display all config values. See the `--help` output for more options available. -### rustc `--print` +## rustc `--print` * Tracking Issue: [#9357](https://github.com/rust-lang/cargo/issues/9357) @@ -1288,7 +1288,7 @@ The primary use case is to run `cargo rustc --print=cfg` to get config values for the appropriate target and influenced by any other RUSTFLAGS. -### Different binary name +## Different binary name * Tracking Issue: [#9778](https://github.com/rust-lang/cargo/issues/9778) * PR: [#9627](https://github.com/rust-lang/cargo/pull/9627) @@ -1315,7 +1315,7 @@ filename = "007bar" path = "src/main.rs" ``` -### scrape-examples +## scrape-examples * RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123) * Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910) @@ -1359,7 +1359,7 @@ For example, you can set `doc-scrape-examples` to true for one example target, a you are ok with dev-deps being build for `cargo doc`. -### check-cfg +## check-cfg * RFC: [#3013](https://github.com/rust-lang/rfcs/pull/3013) * Tracking Issue: [#10554](https://github.com/rust-lang/cargo/issues/10554) @@ -1394,7 +1394,7 @@ println!("cargo:rustc-check-cfg=names(foo, bar)"); cargo check -Z unstable-options -Z check-cfg=output ``` -#### `cargo:rustc-check-cfg=CHECK_CFG` +### `cargo:rustc-check-cfg=CHECK_CFG` The `rustc-check-cfg` instruction tells Cargo to pass the given value to the `--check-cfg` flag to the compiler. This may be used for compile-time @@ -1406,7 +1406,7 @@ with a warning. If you want to integrate with Cargo features, use `-Zcheck-cfg=features` instead of trying to do it manually with this option. -### codegen-backend +## codegen-backend The `codegen-backend` feature makes it possible to select the codegen backend used by rustc using a profile. @@ -1435,7 +1435,7 @@ codegen-backend = true codegen-backend = "cranelift" ``` -### gitoxide +## gitoxide * Tracking Issue: [#11813](https://github.com/rust-lang/cargo/issues/11813) @@ -1462,7 +1462,7 @@ Valid operations are the following: * When the unstable feature is on, fetching/cloning a git repository is always a shallow fetch. This roughly equals to `git fetch --depth 1` everywhere. * Even with the presence of `Cargo.lock` or specifying a commit `{ rev = "…" }`, gitoxide is still smart enough to shallow fetch without unshallowing the existing repository. -### script +## script * Tracking Issue: [#12207](https://github.com/rust-lang/cargo/issues/12207) @@ -1499,7 +1499,7 @@ fn main() { } ``` -#### Single-file packages +### Single-file packages In addition to today's multi-file packages (`Cargo.toml` file with other `.rs` files), we are adding the concept of single-file packages which may contain an @@ -1549,7 +1549,7 @@ The lockfile for single-file packages will be placed in `CARGO_TARGET_DIR`. In the future, when workspaces are supported, that will allow a user to have a persistent lockfile. -#### Manifest-commands +### Manifest-commands You may pass a manifest directly to the `cargo` command, without a subcommand, like `foo/Cargo.toml` or a single-file package like `foo.rs`. This is mostly @@ -1569,7 +1569,7 @@ Differences between `cargo run --manifest-path ` and `cargo ` - `cargo ` runs with the config for `` and not the current dir, more like `cargo install --path ` - `cargo ` is at a verbosity level below the normal default. Pass `-v` to get normal output. -### `[lints]` +## `[lints]` * Tracking Issue: [#12115](https://github.com/rust-lang/cargo/issues/12115) @@ -1590,9 +1590,9 @@ workspace = true unsafe = "forbid" ``` -#### Documentation Updates +### Documentation Updates -##### The `lints` section +#### The `lints` section *as a new ["Manifest Format" entry](./manifest.html#the-manifest-format)* @@ -1634,7 +1634,7 @@ unsafe = "forbid" enum_glob_use = "deny" ``` -##### The `lints` table +#### The `lints` table *as a new [`[workspace]` entry](./workspaces.html#the-workspace-section)* @@ -1663,39 +1663,39 @@ version = "0.1.0" workspace = true ``` -## Stabilized and removed features +# Stabilized and removed features -### Compile progress +## Compile progress The compile-progress feature has been stabilized in the 1.30 release. Progress bars are now enabled by default. See [`term.progress`](config.md#termprogresswhen) for more information about controlling this feature. -### Edition +## Edition Specifying the `edition` in `Cargo.toml` has been stabilized in the 1.31 release. See [the edition field](manifest.md#the-edition-field) for more information about specifying this field. -### rename-dependency +## rename-dependency Specifying renamed dependencies in `Cargo.toml` has been stabilized in the 1.31 release. See [renaming dependencies](specifying-dependencies.md#renaming-dependencies-in-cargotoml) for more information about renaming dependencies. -### Alternate Registries +## Alternate Registries Support for alternate registries has been stabilized in the 1.34 release. See the [Registries chapter](registries.md) for more information about alternate registries. -### Offline Mode +## Offline Mode The offline feature has been stabilized in the 1.36 release. See the [`--offline` flag](../commands/cargo.md#option-cargo---offline) for more information on using the offline mode. -### publish-lockfile +## publish-lockfile The `publish-lockfile` feature has been removed in the 1.37 release. The `Cargo.lock` file is always included when a package is published if the @@ -1704,19 +1704,19 @@ to use the `Cargo.lock` file. See [`cargo package`](../commands/cargo-package.md) and [`cargo install`](../commands/cargo-install.md) for more information. -### default-run +## default-run The `default-run` feature has been stabilized in the 1.37 release. See [the `default-run` field](manifest.md#the-default-run-field) for more information about specifying the default target to run. -### cache-messages +## cache-messages Compiler message caching has been stabilized in the 1.40 release. Compiler warnings are now cached by default and will be replayed automatically when re-running Cargo. -### install-upgrade +## install-upgrade The `install-upgrade` feature has been stabilized in the 1.41 release. [`cargo install`] will now automatically upgrade packages if they appear to be @@ -1724,129 +1724,129 @@ out-of-date. See the [`cargo install`] documentation for more information. [`cargo install`]: ../commands/cargo-install.md -### Profile Overrides +## Profile Overrides Profile overrides have been stabilized in the 1.41 release. See [Profile Overrides](profiles.md#overrides) for more information on using overrides. -### Config Profiles +## Config Profiles Specifying profiles in Cargo config files and environment variables has been stabilized in the 1.43 release. See the [config `[profile]` table](config.md#profile) for more information about specifying [profiles](profiles.md) in config files. -### crate-versions +## crate-versions The `-Z crate-versions` flag has been stabilized in the 1.47 release. The crate version is now automatically included in the [`cargo doc`](../commands/cargo-doc.md) documentation sidebar. -### Features +## Features The `-Z features` flag has been stabilized in the 1.51 release. See [feature resolver version 2](features.md#feature-resolver-version-2) for more information on using the new feature resolver. -### package-features +## package-features The `-Z package-features` flag has been stabilized in the 1.51 release. See the [resolver version 2 command-line flags](features.md#resolver-version-2-command-line-flags) for more information on using the features CLI options. -### Resolver +## Resolver The `resolver` feature in `Cargo.toml` has been stabilized in the 1.51 release. See the [resolver versions](resolver.md#resolver-versions) for more information about specifying resolvers. -### extra-link-arg +## extra-link-arg The `extra-link-arg` feature to specify additional linker arguments in build scripts has been stabilized in the 1.56 release. See the [build script documentation](build-scripts.md#outputs-of-the-build-script) for more information on specifying extra linker arguments. -### configurable-env +## configurable-env The `configurable-env` feature to specify environment variables in Cargo configuration has been stabilized in the 1.56 release. See the [config documentation](config.html#env) for more information about configuring environment variables. -### rust-version +## rust-version The `rust-version` field in `Cargo.toml` has been stabilized in the 1.56 release. See the [rust-version field](manifest.html#the-rust-version-field) for more information on using the `rust-version` field and the `--ignore-rust-version` option. -### patch-in-config +## patch-in-config The `-Z patch-in-config` flag, and the corresponding support for `[patch]` section in Cargo configuration files has been stabilized in the 1.56 release. See the [patch field](config.html#patch) for more information. -### edition 2021 +## edition 2021 The 2021 edition has been stabilized in the 1.56 release. See the [`edition` field](manifest.md#the-edition-field) for more information on setting the edition. See [`cargo fix --edition`](../commands/cargo-fix.md) and [The Edition Guide](../../edition-guide/index.html) for more information on migrating existing projects. -### Custom named profiles +## Custom named profiles Custom named profiles have been stabilized in the 1.57 release. See the [profiles chapter](profiles.md#custom-profiles) for more information. -### Profile `strip` option +## Profile `strip` option The profile `strip` option has been stabilized in the 1.59 release. See the [profiles chapter](profiles.md#strip) for more information. -### Future incompat report +## Future incompat report Support for generating a future-incompat report has been stabilized in the 1.59 release. See the [future incompat report chapter](future-incompat-report.md) for more information. -### Namespaced features +## Namespaced features Namespaced features has been stabilized in the 1.60 release. See the [Features chapter](features.md#optional-dependencies) for more information. -### Weak dependency features +## Weak dependency features Weak dependency features has been stabilized in the 1.60 release. See the [Features chapter](features.md#dependency-features) for more information. -### timings +## timings The `-Ztimings` option has been stabilized as `--timings` in the 1.60 release. (`--timings=html` and the machine-readable `--timings=json` output remain unstable and require `-Zunstable-options`.) -### config-cli +## config-cli The `--config` CLI option has been stabilized in the 1.63 release. See the [config documentation](config.html#command-line-overrides) for more information. -### multitarget +## multitarget The `-Z multitarget` option has been stabilized in the 1.64 release. See [`build.target`](config.md#buildtarget) for more information about setting the default [target platform triples][target triple]. -### crate-type +## crate-type The `--crate-type` flag for `cargo rustc` has been stabilized in the 1.64 release. See the [`cargo rustc` documentation](../commands/cargo-rustc.md) for more information. -### Workspace Inheritance +## Workspace Inheritance Workspace Inheritance has been stabilized in the 1.64 release. See [workspace.package](workspaces.md#the-package-table), @@ -1854,32 +1854,32 @@ See [workspace.package](workspaces.md#the-package-table), and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace) for more information. -### terminal-width +## terminal-width The `-Z terminal-width` option has been stabilized in the 1.68 release. The terminal width is always passed to the compiler when running from a terminal where Cargo can automatically detect the width. -### sparse-registry +## sparse-registry Sparse registry support has been stabilized in the 1.68 release. See [Registry Protocols](registries.md#registry-protocols) for more information. -#### `cargo logout` +### `cargo logout` The [`cargo logout`] command has been stabilized in the 1.70 release. [target triple]: ../appendix/glossary.md#target '"target" (glossary)' -### `doctest-in-workspace` +## `doctest-in-workspace` The `-Z doctest-in-workspace` option for `cargo test` has been stabilized and enabled by default in the 1.72 release. See the [`cargo test` documentation](../commands/cargo-test.md#working-directory-of-tests) for more information about the working directory for compiling and running tests. -### keep-going +## keep-going The `--keep-going` option has been stabilized in the 1.74 release. See the [`--keep-going` flag](../commands/cargo-build.html#option-cargo-build---keep-going) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 36a2e73238e..e3ca278fee0 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -1,4 +1,4 @@ -## Workspaces +# Workspaces A *workspace* is a collection of one or more packages, called *workspace members*, that are managed together. @@ -29,7 +29,7 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections: * [`[replace]`](overriding-dependencies.md#the-replace-section) --- Override dependencies (deprecated). * [`[profile]`](profiles.md) --- Compiler settings and optimizations. -### The `[workspace]` section +## The `[workspace]` section To create a workspace, you add the `[workspace]` table to a `Cargo.toml`: ```toml @@ -40,7 +40,7 @@ To create a workspace, you add the `[workspace]` table to a `Cargo.toml`: At minimum, a workspace has to have a member, either with a root package or as a virtual manifest. -#### Root package +### Root package If the [`[workspace]` section](#the-workspace-section) is added to a `Cargo.toml` that already defines a `[package]`, the package is @@ -56,7 +56,7 @@ version = "0.1.0" # the current version, obeying semver authors = ["Alice ", "Bob "] ``` -#### Virtual workspace +### Virtual workspace Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section but without a [`[package]` section][package]. This is called a *virtual @@ -84,7 +84,7 @@ should be specified manually. It is usually deduced from the [`package.edition`] field which is absent in virtual manifests and the edition field of a member won't affect the resolver used by the workspace. -### The `members` and `exclude` fields +## The `members` and `exclude` fields The `members` and `exclude` fields define which packages are members of the workspace: @@ -114,7 +114,7 @@ manifest key can be used in member crates to point at a workspace's root to override this automatic search. The manual setting can be useful if the member is not inside a subdirectory of the workspace root. -#### Package selection +### Package selection In a workspace, package-related Cargo commands like [`cargo build`] can use the `-p` / `--package` or `--workspace` command-line flags to determine which @@ -124,7 +124,7 @@ a [virtual workspace](#virtual-workspace), it will apply to all members (as if `--workspace` were specified on the command-line). See also [`default-members`](#the-default-members-field). -### The `default-members` field +## The `default-members` field The optional `default-members` key can be specified to set the members to operate on when in the workspace root and the package selection flags are not @@ -138,7 +138,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"] When specified, `default-members` must expand to a subset of `members`. -### The `package` table +## The `package` table The `workspace.package` table is where you define keys that can be inherited by members of a workspace. These keys can be inherited by @@ -183,7 +183,7 @@ description.workspace = true documentation.workspace = true ``` -### The `dependencies` table +## The `dependencies` table The `workspace.dependencies` table is where you define dependencies to be inherited by members of a workspace. @@ -222,7 +222,7 @@ cc.workspace = true rand.workspace = true ``` -### The `metadata` table +## The `metadata` table The `workspace.metadata` table is ignored by Cargo and will not be warned about. This section can be used for tools that would like to store workspace