## Unstable Features

Experimental Cargo features are only available on the nightly channel. You are encouraged to experiment with these features to see if they meet your needs, and if there are any issues or problems. Check the linked tracking issues listed below for more information on the feature, and click the GitHub subscribe button if you want future updates.

After some period of time, if the feature does not have any major concerns, it can be stabilized, which will make it available on stable once the current nightly release reaches the stable channel (anywhere from 6 to 12 weeks).

There are three different ways that unstable features can be enabled based on how the feature works:

- New syntax in `Cargo.toml` requires a `cargo-features` key at the top of `Cargo.toml`, before any tables. For example:

      # This specifies which new Cargo.toml features are enabled.
      cargo-features = ["test-dummy-unstable"]

      [package]
      name = "my-package"
      version = "0.1.0"
      im-a-teapot = true  # This is a new option enabled by test-dummy-unstable.

- New command-line flags, options, and subcommands require the `-Z unstable-options` CLI option to also be included. For example, the new `--out-dir` option is only available on nightly:

  `cargo +nightly build --out-dir=out -Z unstable-options`

- `-Z` command-line flags are used to enable new functionality that may not have an interface, or the interface has not yet been designed, or for more complex features that affect multiple parts of Cargo. For example, the mtime-on-use feature can be enabled with:

  `cargo +nightly build -Z mtime-on-use`

  Run `cargo -Z help` to see a list of flags available.

  Anything which can be configured with a `-Z` flag can also be set in the cargo config file (`.cargo/config.toml`) in the `unstable` table. For example:

      [unstable]
      mtime-on-use = true
      multitarget = true

Each new feature described below should explain how to use it.

### List of unstable features

- Unstable-specific features
  - -Z allow-features — Provides a way to restrict which unstable features are used.
- Build scripts and linking
  - Metabuild — Provides declarative build scripts.
- Resolver and features
  - no-index-update — Prevents cargo from updating the index cache.
  - avoid-dev-deps — Prevents the resolver from including dev-dependencies during resolution.
  - minimal-versions — Forces the resolver to use the lowest compatible version instead of the highest.
  - public-dependency — Allows dependencies to be classified as either public or private.
  - workspace-inheritance - Allow workspace members to share fields and dependencies
- Output behavior
  - out-dir — Adds a directory where artifacts are copied to.
  - terminal-width — Tells rustc the width of the terminal so that long diagnostic messages can be truncated to be more readable.
  - Different binary name — Assign a name to the built binary that is separate from the crate name.
- Compile behavior
  - mtime-on-use — Updates the last-modified timestamp on every dependency every time it is used, to provide a mechanism to delete unused artifacts.
  - doctest-xcompile — Supports running doctests with the `--target` flag.
  - multitarget — Supports building for multiple targets at the same time.
  - build-std — Builds the standard library instead of using pre-built binaries.
  - build-std-features — Sets features to use with the standard library.
  - binary-dep-depinfo — Causes the dep-info file to track binary dependencies.
  - panic-abort-tests — Allows running tests with the "abort" panic strategy.
  - crate-type — Supports passing crate types to the compiler.
  - keep-going — Build as much as possible rather than aborting on the first error.
- rustdoc
  - `doctest-in-workspace` — Fixes workspace-relative paths when running doctests.
  - rustdoc-map — Provides mappings for documentation to link to external sites like docs.rs.
- `Cargo.toml` extensions
  - Profile `strip` option — Forces the removal of debug information and symbols from executables.
  - Profile `rustflags` option — Passed directly to rustc.
  - per-package-target — Sets the `--target` to use for each individual package.
  - artifact dependencies - Allow build artifacts to be included into other build artifacts and build them for different targets.
- Information and metadata
  - Build-plan — Emits JSON information on which commands will be run.
  - unit-graph — Emits JSON for Cargo's internal graph structure.
  - `cargo rustc --print` — Calls rustc with `--print` to display information from rustc.
- Configuration
  - config-cli — Adds the ability to pass configuration options on the command-line.
  - config-include — Adds the ability for config files to include other files.
  - `cargo config` — Adds a new subcommand for viewing config files.
- Registries
  - credential-process — Adds support for fetching registry tokens from an external authentication program.
  - `cargo logout` — Adds the `logout` command to remove the currently saved registry token.
  - http-registry — Adds support for fetching from http registries (`sparse+`)

### allow-features

This permanently-unstable flag makes it so that only a listed set of unstable features can be used. Specifically, if you pass `-Zallow-features=foo,bar`, you'll continue to be able to pass `-Zfoo` and `-Zbar` to `cargo`, but you will be unable to pass `-Zbaz`. You can pass an empty string (`-Zallow-features=`) to disallow all unstable features.

`-Zallow-features` also restricts which unstable features can be passed to the `cargo-features` entry in `Cargo.toml`. If, for example, you want to allow

    cargo-features = ["test-dummy-unstable"]

where `test-dummy-unstable` is unstable, that features would also be disallowed by `-Zallow-features=`, and allowed with `-Zallow-features=test-dummy-unstable`.

The list of features passed to cargo's `-Zallow-features` is also passed to any Rust tools that cargo ends up calling (like `rustc` or `rustdoc`). Thus, if you run `cargo -Zallow-features=`, no unstable Cargo or Rust features can be used.

### no-index-update

- Original Issue: #3479
- Tracking Issue: #7404

The `-Z no-index-update` flag ensures that Cargo does not attempt to update the registry index. This is intended for tools such as Crater that issue many Cargo commands, and you want to avoid the network latency for updating the index each time.

### mtime-on-use

- Original Issue: #6477
- Cache usage meta tracking issue: #7150

The `-Z mtime-on-use` flag is an experiment to have Cargo update the mtime of used files to make it easier for tools like cargo-sweep to detect which files are stale. For many workflows this needs to be set on all invocations of cargo. To make this more practical setting the `unstable.mtime_on_use` flag in `.cargo/config.toml` or the corresponding ENV variable will apply the `-Z mtime-on-use` to all invocations of nightly cargo. (the config flag is ignored by stable)

### avoid-dev-deps

- Original Issue: #4988
- Tracking Issue: #5133

When running commands such as `cargo install` or `cargo build`, Cargo currently requires dev-dependencies to be downloaded, even if they are not used. The `-Z avoid-dev-deps` flag allows Cargo to avoid downloading dev-dependencies if they are not needed. The `Cargo.lock` file will not be generated if dev-dependencies are skipped.

### minimal-versions

- Original Issue: #4100
- Tracking Issue: #5657

> Note: It is not recommended to use this feature. Because it enforces minimal versions for all transitive dependencies, its usefulness is limited since not all external dependencies declare proper lower version bounds. It is intended that it will be changed in the future to only enforce minimal versions for direct dependencies.

When a `Cargo.lock` file is generated, the `-Z minimal-versions` flag will resolve the dependencies to the minimum SemVer version that will satisfy the requirements (instead of the greatest version).

The intended use-case of this flag is to check, during continuous integration, that the versions specified in Cargo.toml are a correct reflection of the minimum versions that you are actually using. That is, if Cargo.toml says `foo = "1.0.0"` that you don't accidentally depend on features added only in `foo 1.5.0`.

### out-dir

- Original Issue: #4875
- Tracking Issue: #6790

This feature allows you to specify the directory where artifacts will be copied to after they are built. Typically artifacts are only written to the `target/release` or `target/debug` directories. However, determining the exact filename can be tricky since you need to parse JSON output. The `--out-dir` flag makes it easier to predictably access the artifacts. Note that the artifacts are copied, so the originals are still in the `target` directory. Example:

    cargo +nightly build --out-dir=out -Z unstable-options

This can also be specified in `.cargo/config.toml` files.

    [build]
    out-dir = "out"

### doctest-xcompile

- Tracking Issue: #7040
- Tracking Rustc Issue: #64245

This flag changes `cargo test`'s behavior when handling doctests when a target is passed. Currently, if a target is passed that is different from the host cargo will simply skip testing doctests. If this flag is present, cargo will continue as normal, passing the tests to doctest, while also passing it a `--target` option, as well as enabling `-Zunstable-features --enable-per-target-ignores` and passing along information from `.cargo/config.toml`. See the rustc issue for more information.

    cargo test --target foo -Zdoctest-xcompile

### multitarget

- Tracking Issue: #8176

This flag allows passing multiple `--target` flags to the `cargo` subcommand selected. When multiple `--target` flags are passed the selected build targets will be built for each of the selected architectures.

For example to compile a library for both 32 and 64-bit:

    cargo build --target x86_64-unknown-linux-gnu --target i686-unknown-linux-gnu

or running tests for both targets:

    cargo test --target x86_64-unknown-linux-gnu --target i686-unknown-linux-gnu

This can also be specified in `.cargo/config.toml` files.

    [build]
    target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]

#### New `dir-name` attribute

Some of the paths generated under `target/` have resulted in a de-facto "build protocol", where `cargo` is invoked as a part of a larger project build. So, to preserve the existing behavior, there is also a new attribute `dir-name`, which when left unspecified, defaults to the name of the profile. For example:

    [profile.release-lto]
    inherits = "release"
    dir-name = "lto"  # Emits to target/lto instead of target/release-lto
    lto = true

### Build-plan

- Tracking Issue: #5579

The `--build-plan` argument for the `build` command will output JSON with information about which commands would be run without actually executing anything. This can be useful when integrating with another build tool. Example:

    cargo +nightly build --build-plan -Z unstable-options

### Metabuild

- Tracking Issue: rust-lang/rust#49803
- RFC: #2196

Metabuild is a feature to have declarative build scripts. Instead of writing a `build.rs` script, you specify a list of build dependencies in the `metabuild` key in `Cargo.toml`. A build script is automatically generated that runs each build dependency in order. Metabuild packages can then read metadata from `Cargo.toml` to specify their behavior.

Include `cargo-features` at the top of `Cargo.toml`, a `metabuild` key in the `package`, list the dependencies in `build-dependencies`, and add any metadata that the metabuild packages require under `package.metadata`. Example:

    cargo-features = ["metabuild"]

    [package]
    name = "mypackage"
    version = "0.0.1"
    metabuild = ["foo", "bar"]

    [build-dependencies]
    foo = "1.0"
    bar = "1.0"

    [package.metadata.foo]
    extra-info = "qwerty"

Metabuild packages should have a public function called `metabuild` that performs the same actions as a regular `build.rs` script would perform.

### public-dependency

- Tracking Issue: #44663

The 'public-dependency' feature allows marking dependencies as 'public' or 'private'. When this feature is enabled, additional information is passed to rustc to allow the 'exported_private_dependencies' lint to function properly.

This requires the appropriate key to be set in `cargo-features`:

    cargo-features = ["public-dependency"]

    [dependencies]
    my_dep = { version = "1.2.3", public = true }
    private_dep = "2.0.0" # Will be 'private' by default

### build-std

- Tracking Repository: https://github.com/rust-lang/wg-cargo-std-aware

The `build-std` feature enables Cargo to compile the standard library itself as part of a crate graph compilation. This feature has also historically been known as "std-aware Cargo". This feature is still in very early stages of development, and is also a possible massive feature addition to Cargo. This is a very large feature to document, even in the minimal form that it exists in today, so if you're curious to stay up to date you'll want to follow the tracking repository and its set of issues.

The functionality implemented today is behind a flag called `-Z build-std`. This flag indicates that Cargo should compile the standard library from source code using the same profile as the main build itself. Note that for this to work you need to have the source code for the standard library available, and at this time the only supported method of doing so is to add the `rust-src` rust rustup component:

    $ rustup component add rust-src --toolchain nightly

It is also required today that the `-Z build-std` flag is combined with the `--target` flag. Note that you're not forced to do a cross compilation, you're just forced to pass `--target` in one form or another.

Usage looks like:

    $ cargo new foo
    $ cd foo
    $ cargo +nightly run -Z build-std --target x86_64-unknown-linux-gnu
       Compiling core v0.0.0 (...)
       ...
       Compiling foo v0.1.0 (...)
        Finished dev [unoptimized + debuginfo] target(s) in 21.00s
         Running `target/x86_64-unknown-linux-gnu/debug/foo`
    Hello, world!

Here we recompiled the standard library in debug mode with debug assertions (like `src/main.rs` is compiled) and everything was linked together at the end.

Using `-Z build-std` will implicitly compile the stable crates `core`, `std`, `alloc`, and `proc_macro`. If you're using `cargo test` it will also compile the `test` crate. If you're working with an environment which does not support some of these crates, then you can pass an argument to `-Zbuild-std` as well:

    $ cargo +nightly build -Z build-std=core,alloc

The value here is a comma-separated list of standard library crates to build.

#### Requirements

As a summary, a list of requirements today to use `-Z build-std` are:

- You must install libstd's source code through `rustup component add rust-src`
- You must pass `--target`
- You must use both a nightly Cargo and a nightly rustc
- The `-Z build-std` flag must be passed to all `cargo` invocations.

#### Reporting bugs and helping out

The `-Z build-std` feature is in the very early stages of development! This feature for Cargo has an extremely long history and is very large in scope, and this is just the beginning. If you'd like to report bugs please either report them to:

- Cargo - https://github.com/rust-lang/cargo/issues/new - for implementation bugs
- The tracking repository - https://github.com/rust-lang/wg-cargo-std-aware/issues/new - for larger design questions.

Also if you'd like to see a feature that's not yet implemented and/or if something doesn't quite work the way you'd like it to, feel free to check out the issue tracker of the tracking repository, and if it's not there please file a new issue!

### build-std-features

- Tracking Repository: https://github.com/rust-lang/wg-cargo-std-aware

This flag is a sibling to the `-Zbuild-std` feature flag. This will configure the features enabled for the standard library itself when building the standard library. The default enabled features, at this time, are `backtrace` and `panic_unwind`. This flag expects a comma-separated list and, if provided, will override the default list of features enabled.

### binary-dep-depinfo

- Tracking rustc issue: #63012

The `-Z binary-dep-depinfo` flag causes Cargo to forward the same flag to `rustc` which will then cause `rustc` to include the paths of all binary dependencies in the "dep info" file (with the `.d` extension). Cargo then uses that information for change-detection (if any binary dependency changes, then the crate will be rebuilt). The primary use case is for building the compiler itself, which has implicit dependencies on the standard library that would otherwise be untracked for change-detection.

### panic-abort-tests

- Tracking Issue: #67650
- Original Pull Request: #7460

The `-Z panic-abort-tests` flag will enable nightly support to compile test harness crates with `-Cpanic=abort`. Without this flag Cargo will compile tests, and everything they depend on, with `-Cpanic=unwind` because it's the only way `test`-the-crate knows how to operate. As of rust-lang/rust#64158, however, the `test` crate supports `-C panic=abort` with a test-per-process, and can help avoid compiling crate graphs multiple times.

It's currently unclear how this feature will be stabilized in Cargo, but we'd like to stabilize it somehow!

### crate-type

- Tracking Issue: #10083
- RFC: #3180
- Original Pull Request: #10093

`cargo rustc --crate-type=lib,cdylib` forwards the `--crate-type` flag to `rustc`. This runs `rustc` with the corresponding `--crate-type` flag, and compiling.

When using it, it requires the `-Z unstable-options` command-line option:

    cargo rustc --crate-type lib,cdylib -Z unstable-options

### keep-going

- Tracking Issue: #0

`cargo build --keep-going` (and similarly for `check`, `test` etc) will build as many crates in the dependency graph as possible, rather than aborting the build at the first one that fails to build.

For example if the current package depends on dependencies `fails` and `works`, one of which fails to build, `cargo check -j1` may or may not build the one that succeeds (depending on which one of the two builds Cargo picked to run first), whereas `cargo check -j1 --keep-going` would definitely run both builds, even if the one run first fails.

The `-Z unstable-options` command-line option must be used in order to use `--keep-going` while it is not yet stable:

    cargo check --keep-going -Z unstable-options

### config-cli

- Tracking Issue: #7722

The `--config` CLI option allows arbitrary config values to be passed in via the command-line. The argument should be in TOML syntax of KEY=VALUE:

    cargo +nightly -Zunstable-options --config net.git-fetch-with-cli=true fetch

The `--config` option may be specified multiple times, in which case the values are merged in left-to-right order, using the same merging logic that multiple config files use. CLI values take precedence over environment variables, which take precedence over config files.

Some examples of what it looks like using Bourne shell syntax:

    # Most shells will require escaping.
    cargo --config http.proxy=\"http://example.com\" …

    # Spaces may be used.
    cargo --config "net.git-fetch-with-cli = true" …

    # TOML array example. Single quotes make it easier to read and write.
    cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …

    # Example of a complex TOML key.
    cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …

    # Example of overriding a profile setting.
    cargo --config profile.dev.package.image.opt-level=3 …

### config-include

- Tracking Issue: #7723

The `include` key in a config file can be used to load another config file. It takes a string for a path to another file relative to the config file, or a list of strings. It requires the `-Zconfig-include` command-line option.

    # .cargo/config
    include = '../../some-common-config.toml'

The config values are first loaded from the include path, and then the config file's own values are merged on top of it.

This can be paired with config-cli to specify a file to load from the command-line. Pass a path to a config file as the argument to `--config`:

    cargo +nightly -Zunstable-options -Zconfig-include --config somefile.toml build

CLI paths are relative to the current working directory.

### target-applies-to-host

- Original Pull Request: #9322
- Tracking Issue: #9453

Historically, Cargo's behavior for whether the `linker` and `rustflags` configuration options from environment variables and `[target]` are respected for build scripts, plugins, and other artifacts that are always built for the host platform has been somewhat inconsistent. When `--target` is not passed, Cargo respects the same `linker` and `rustflags` for build scripts as for all other compile artifacts. When `--target` is passed, however, Cargo respects `linker` from `[target.<host triple>]`, and does not pick up any `rustflags` configuration. This dual behavior is confusing, but also makes it difficult to correctly configure builds where the host triple and the target triple happen to be the same, but artifacts intended to run on the build host should still be configured differently.

`-Ztarget-applies-to-host` enables the top-level `target-applies-to-host` setting in Cargo configuration files which allows users to opt into different (and more consistent) behavior for these properties. When `target-applies-to-host` is unset, or set to `true`, in the configuration file, the existing Cargo behavior is preserved (though see `-Zhost-config`, which changes that default). When it is set to `false`, no options from `[target.<host triple>]`, `RUSTFLAGS`, or `[build]` are respected for host artifacts regardless of whether `--target` is passed to Cargo. To customize artifacts intended to be run on the host, use `[host]` (`host-config`).

In the future, `target-applies-to-host` may end up defaulting to `false` to provide more sane and consistent default behavior.

    # config.toml
    target-applies-to-host = false

    cargo +nightly -Ztarget-applies-to-host build --target x86_64-unknown-linux-gnu

### host-config

- Original Pull Request: #9322
- Tracking Issue: #9452

The `host` key in a config file can be used pass flags to host build targets such as build scripts that must run on the host system instead of the target system when cross compiling. It supports both generic and host arch specific tables. Matching host arch tables take precedence over generic host tables.

It requires the `-Zhost-config` and `-Ztarget-applies-to-host` command-line options to be set, and that `target-applies-to-host = false` is set in the Cargo configuration file.

    # config.toml
    [host]
    linker = "/path/to/host/linker"
    [host.x86_64-unknown-linux-gnu]
    linker = "/path/to/host/arch/linker"
    rustflags = ["-Clink-arg=--verbose"]
    [target.x86_64-unknown-linux-gnu]
    linker = "/path/to/target/linker"

The generic `host` table above will be entirely ignored when building on a `x86_64-unknown-linux-gnu` host as the `host.x86_64-unknown-linux-gnu` table takes precedence.

Setting `-Zhost-config` changes the default for `target-applies-to-host` to `false` from `true`.

    cargo +nightly -Ztarget-applies-to-host -Zhost-config build --target x86_64-unknown-linux-gnu

### unit-graph

- Tracking Issue: #8002

The `--unit-graph` flag can be passed to any build command (`build`, `check`, `run`, `test`, `bench`, `doc`, etc.) to emit a JSON object to stdout which represents Cargo's internal unit graph. Nothing is actually built, and the command returns immediately after printing. Each "unit" corresponds to an execution of the compiler. These objects also include which unit each unit depends on.

    cargo +nightly build --unit-graph -Z unstable-options

This structure provides a more complete view of the dependency relationship as Cargo sees it. In particular, the "features" field supports the new feature resolver where a dependency can be built multiple times with different features. `cargo metadata` fundamentally cannot represent the relationship of features between different dependency kinds, and features now depend on which command is run and which packages and targets are selected. Additionally it can provide details about intra-package dependencies like build scripts or tests.

The following is a description of the JSON structure:

    {
      /* Version of the JSON output structure. If any backwards incompatible
         changes are made, this value will be increased.
      */
      "version": 1,
      /* Array of all build units. */
      "units": [
        {
          /* An opaque string which indicates the package.
             Information about the package can be obtained from `cargo metadata`.
          */
          "pkg_id": "my-package 0.1.0 (path+file:///path/to/my-package)",
          /* The Cargo target. See the `cargo metadata` documentation for more
             information about these fields.
             https://doc.rust-lang.org/cargo/commands/cargo-metadata.html
          */
          "target": {
            "kind": ["lib"],
            "crate_types": ["lib"],
            "name": "my-package",
            "src_path": "/path/to/my-package/src/lib.rs",
            "edition": "2018",
            "test": true,
            "doctest": true
          },
          /* The profile settings for this unit.
             These values may not match the profile defined in the manifest.
             Units can use modified profile settings. For example, the "panic"
             setting can be overridden for tests to force it to "unwind".
          */
          "profile": {
            /* The profile name these settings are derived from. */
            "name": "dev",
            /* The optimization level as a string. */
            "opt_level": "0",
            /* The LTO setting as a string. */
            "lto": "false",
            /* The codegen units as an integer.
               `null` if it should use the compiler's default.
            */
            "codegen_units": null,
            /* The debug information level as an integer.
               `null` if it should use the compiler's default (0).
            */
            "debuginfo": 2,
            /* Whether or not debug-assertions are enabled. */
            "debug_assertions": true,
            /* Whether or not overflow-checks are enabled. */
            "overflow_checks": true,
            /* Whether or not rpath is enabled. */
            "rpath": false,
            /* Whether or not incremental is enabled. */
            "incremental": true,
            /* The panic strategy, "unwind" or "abort". */
            "panic": "unwind"
          },
          /* Which platform this target is being built for.
             A value of `null` indicates it is for the host.
             Otherwise it is a string of the target triple (such as
             "x86_64-unknown-linux-gnu").
          */
          "platform": null,
          /* The "mode" for this unit. Valid values:

             * "test" — Build using `rustc` as a test.
             * "build" — Build using `rustc`.
             * "check" — Build using `rustc` in "check" mode.
             * "doc" — Build using `rustdoc`.
             * "doctest" — Test using `rustdoc`.
             * "run-custom-build" — Represents the execution of a build script.
          */
          "mode": "build",
          /* Array of features enabled on this unit as strings. */
          "features": ["somefeat"],
          /* Whether or not this is a standard-library unit,
             part of the unstable build-std feature.
             If not set, treat as `false`.
          */
          "is_std": false,
          /* Array of dependencies of this unit. */
          "dependencies": [
            {
              /* Index in the "units" array for the dependency. */
              "index": 1,
              /* The name that this dependency will be referred as. */
              "extern_crate_name": "unicode_xid",
              /* Whether or not this dependency is "public",
                 part of the unstable public-dependency feature.
                 If not set, the public-dependency feature is not enabled.
              */
              "public": false,
              /* Whether or not this dependency is injected into the prelude,
                 currently used by the build-std feature.
                 If not set, treat as `false`.
              */
              "noprelude": false
            }
          ]
        },
        // ...
      ],
      /* Array of indices in the "units" array that are the "roots" of the
         dependency graph.
      */
      "roots": [0],
    }

### Profile `rustflags` option

- Original Issue: rust-lang/cargo#7878
- Tracking Issue: rust-lang/cargo#10271

This feature provides a new option in the `[profile]` section to specify flags that are passed directly to rustc. This can be enabled like so:

    cargo-features = ["profile-rustflags"]

    [package]
    # ...

    [profile.release]
    rustflags = [ "-C", "..." ]

### rustdoc-map

- Tracking Issue: #8296

This feature adds configuration settings that are passed to `rustdoc` so that it can generate links to dependencies whose documentation is hosted elsewhere when the dependency is not documented. First, add this to `.cargo/config`:

    [doc.extern-map.registries]
    crates-io = "https://docs.rs/"

Then, when building documentation, use the following flags to cause links to dependencies to link to docs.rs:

    cargo +nightly doc --no-deps -Zrustdoc-map

The `registries` table contains a mapping of registry name to the URL to link to. The URL may have the markers `{pkg_name}` and `{version}` which will get replaced with the corresponding values. If neither are specified, then Cargo defaults to appending `{pkg_name}/{version}/` to the end of the URL.

Another config setting is available to redirect standard library links. By default, rustdoc creates links to https://doc.rust-lang.org/nightly/. To change this behavior, use the `doc.extern-map.std` setting:

    [doc.extern-map]
    std = "local"

A value of `"local"` means to link to the documentation found in the `rustc` sysroot. If you are using rustup, this documentation can be installed with `rustup component add rust-docs`.

The default value is `"remote"`.

The value may also take a URL for a custom location.

### terminal-width

- Tracking Issue: #84673

This feature provides a new flag, `-Z terminal-width`, which is used to pass a terminal width to `rustc` so that error messages containing long lines can be intelligently truncated.

For example, passing `-Z terminal-width=20` (an arbitrarily low value) might produce the following error:

    error[E0308]: mismatched types
      --> src/main.rs:2:17
      |
    2 | ..._: () = 42;
      |       --   ^^ expected `()`, found integer
      |       |
      |       expected due to this

    error: aborting due to previous error

In contrast, without `-Z terminal-width`, the error would look as shown below:

    error[E0308]: mismatched types
     --> src/main.rs:2:17
      |
    2 |     let _: () = 42;
      |            --   ^^ expected `()`, found integer
      |            |
      |            expected due to this

    error: aborting due to previous error

### per-package-target

- Tracking Issue: #9406
- Original Pull Request: #9030
- Original Issue: #7004

The `per-package-target` feature adds two keys to the manifest: `package.default-target` and `package.forced-target`. The first makes the package be compiled by default (ie. when no `--target` argument is passed) for some target. The second one makes the package always be compiled for the target.

Example:

    [package]
    forced-target = "wasm32-unknown-unknown"

In this example, the crate is always built for `wasm32-unknown-unknown`, for instance because it is going to be used as a plugin for a main program that runs on the host (or provided on the command line) target.

### artifact-dependencies

- Tracking Issue: #9096
- Original Pull Request: #9992

Allow Cargo packages to depend on `bin`, `cdylib`, and `staticlib` crates, and use the artifacts built by those crates at compile time.

Run `cargo` with `-Z bindeps` to enable this functionality.

Example: use cdylib artifact in build script

The `Cargo.toml` in the consuming package, building the `bar` library as `cdylib` for a specific build target…

    [build-dependencies]
    bar = { artifact = "cdylib", version = "1.0", target = "wasm32-unknown-unknown" }

…along with the build script in `build.rs`.

    fn main() {
      wasm::run_file(std::env::var("CARGO_CDYLIB_FILE_BAR").unwrap());
    }

Example: use binary artifact and its library in a binary

The `Cargo.toml` in the consuming package, building the `bar` binary for inclusion as artifact while making it available as library as well…

    [dependencies]
    bar = { artifact = "bin", version = "1.0", lib = true }

…along with the executable using `main.rs`.

    fn main() {
      bar::init();
      command::run(env!("CARGO_BIN_FILE_BAR"));
    }

### http-registry

- Tracking Issue: 9069
- RFC: #2789

The `http-registry` feature allows cargo to interact with remote registries served over http rather than git. These registries can be identified by urls starting with `sparse+http://` or `sparse+https://`.

When fetching index metadata over http, cargo only downloads the metadata for relevant crates, which can save significant time and bandwidth.

The format of the http index is identical to a checkout of a git-based index.

### credential-process

- Tracking Issue: #8933
- RFC: #2730

The `credential-process` feature adds a config setting to fetch registry authentication tokens by calling an external process.

Token authentication is used by the `cargo login`, `cargo publish`, `cargo owner`, and `cargo yank` commands. Additionally, this feature adds a new `cargo logout` command.

To use this feature, you must pass the `-Z credential-process` flag on the command-line. Additionally, you must remove any current tokens currently saved in the `credentials` file (which can be done with the new `logout` command).

#### `credential-process` Configuration

To configure which process to run to fetch the token, specify the process in the `registry` table in a config file:

    [registry]
    credential-process = "/usr/bin/cargo-creds"

If you want to use a different process for a specific registry, it can be specified in the `registries` table:

    [registries.my-registry]
    credential-process = "/usr/bin/cargo-creds"

The value can be a string with spaces separating arguments or it can be a TOML array of strings.

Command-line arguments allow special placeholders which will be replaced with the corresponding value:

- `{name}` — The name of the registry.
- `{api_url}` — The base URL of the registry API endpoints.
- `{action}` — The authentication action (described below).

Process names with the prefix `cargo:` are loaded from the `libexec` directory next to cargo. Several experimental credential wrappers are included with Cargo, and this provides convenient access to them:

    [registry]
    credential-process = "cargo:macos-keychain"

The current wrappers are:

- `cargo:macos-keychain`: Uses the macOS Keychain to store the token.
- `cargo:wincred`: Uses the Windows Credential Manager to store the token.
- `cargo:1password`: Uses the 1password `op` CLI to store the token. You must install the `op` CLI from the 1password website. You must run `op signin` at least once with the appropriate arguments (such as `op signin my.1password.com user@example.com`), unless you provide the sign-in-address and email arguments. The master password will be required on each request unless the appropriate `OP_SESSION` environment variable is set. It supports the following command-line arguments:
  - `--account`: The account shorthand name to use.
  - `--vault`: The vault name to use.
  - `--sign-in-address`: The sign-in-address, which is a web address such as `my.1password.com`.
  - `--email`: The email address to sign in with.

A wrapper is available for GNOME libsecret to store tokens on Linux systems. Due to build limitations, this wrapper is not available as a pre-compiled binary. This can be built and installed manually. First, install libsecret using your system package manager (for example, `sudo apt install libsecret-1-dev`). Then build and install the wrapper with `cargo install cargo-credential-gnome-secret`. In the config, use a path to the binary like this:

    [registry]
    credential-process = "cargo-credential-gnome-secret {action}"

#### `credential-process` Interface

There are two different kinds of token processes that Cargo supports. The simple "basic" kind will only be called by Cargo when it needs a token. This is intended for simple and easy integration with password managers, that can often use pre-existing tooling. The more advanced "Cargo" kind supports different actions passed as a command-line argument. This is intended for more pleasant integration experience, at the expense of requiring a Cargo-specific process to glue to the password manager. Cargo will determine which kind is supported by the `credential-process` definition. If it contains the `{action}` argument, then it uses the advanced style, otherwise it assumes it only supports the "basic" kind.

##### Basic authenticator

A basic authenticator is a process that returns a token on stdout. Newlines will be trimmed. The process inherits the user's stdin and stderr. It should exit 0 on success, and nonzero on error.

With this form, `cargo login` and `cargo logout` are not supported and return an error if used.

##### Cargo authenticator

The protocol between the Cargo and the process is very basic, intended to ensure the credential process is kept as simple as possible. Cargo will execute the process with the `{action}` argument indicating which action to perform:

- `store` — Store the given token in secure storage.
- `get` — Get a token from storage.
- `erase` — Remove a token from storage.

The `cargo login` command uses `store` to save a token. Commands that require authentication, like `cargo publish`, uses `get` to retrieve a token. `cargo logout` uses the `erase` command to remove a token.

The process inherits the user's stderr, so the process can display messages. Some values are passed in via environment variables (see below). The expected interactions are:

- `store` — The token is sent to the process's stdin, terminated by a newline. The process should store the token keyed off the registry name. If the process fails, it should exit with a nonzero exit status.

- `get` — The process should send the token to its stdout (trailing newline will be trimmed). The process inherits the user's stdin, should it need to receive input.

  If the process is unable to fulfill the request, it should exit with a nonzero exit code.

- `erase` — The process should remove the token associated with the registry name. If the token is not found, the process should exit with a 0 exit status.

##### Environment

The following environment variables will be provided to the executed command:

- `CARGO` — Path to the `cargo` binary executing the command.
- `CARGO_REGISTRY_NAME` — Name of the registry the authentication token is for.
- `CARGO_REGISTRY_API_URL` — The URL of the registry API.

#### `cargo logout`

A new `cargo logout` command has been added to make it easier to remove a token from storage. This supports both `credentials` file tokens and `credential-process` tokens.

When used with `credentials` file tokens, it needs the `-Z unstable-options` command-line option:

    cargo logout -Z unstable-options

When used with the `credential-process` config, use the `-Z credential-process` command-line option:

    cargo logout -Z credential-process

### `cargo config`

- Original Issue: #2362
- Tracking Issue: #9301

The `cargo config` subcommand provides a way to display the configuration files that cargo loads. It currently includes the `get` subcommand which can take an optional config value to display.

    cargo +nightly -Zunstable-options config get build.rustflags

If no config value is included, it will display all config values. See the `--help` output for more options available.

### `doctest-in-workspace`

- Tracking Issue: #9427

The `-Z doctest-in-workspace` flag changes the behavior of the current working directory used when running doctests. Historically, Cargo has run `rustdoc --test` relative to the root of the package, with paths relative from that root. However, this is inconsistent with how `rustc` and `rustdoc` are normally run in a workspace, where they are run relative to the workspace root. This inconsistency causes problems in various ways, such as when passing RUSTDOCFLAGS with relative paths, or dealing with diagnostic output.

The `-Z doctest-in-workspace` flag causes cargo to switch to running `rustdoc` from the root of the workspace. It also passes the `--test-run-directory` to `rustdoc` so that when running the tests, they are run from the root of the package. This preserves backwards compatibility and is consistent with how normal unittests are run.

### rustc `--print`

- Tracking Issue: #9357

`cargo rustc --print=VAL` forwards the `--print` flag to `rustc` in order to extract information from `rustc`. This runs `rustc` with the corresponding `--print` flag, and then immediately exits without compiling. Exposing this as a cargo flag allows cargo to inject the correct target and RUSTFLAGS based on the current configuration.

The primary use case is to run `cargo rustc --print=cfg` to get config values for the appropriate target and influenced by any other RUSTFLAGS.

### Different binary name

- Tracking Issue: #9778
- PR: #9627

The `different-binary-name` feature allows setting the filename of the binary without having to obey the restrictions placed on crate names. For example, the crate name must use only `alphanumeric` characters or `-` or `_`, and cannot be empty.

The `filename` parameter should not include the binary extension, `cargo` will figure out the appropriate extension and use that for the binary on its own.

The `filename` parameter is only available in the `[[bin]]` section of the manifest.

    cargo-features = ["different-binary-name"]

    [project]
    name =  "foo"
    version = "0.0.1"

    [[bin]]
    name = "foo"
    filename = "007bar"
    path = "src/main.rs"

### scrape-examples

- RFC: #3123
- Tracking Issue: #9910

The `-Z rustdoc-scrape-examples` argument tells Rustdoc to search crates in the current workspace for calls to functions. Those call-sites are then included as documentation. The flag can take an argument of `all` or `examples` which configures which crate in the workspace to analyze for examples. For instance:

    cargo doc -Z unstable-options -Z rustdoc-scrape-examples=examples

### check-cfg

- RFC: #3013
- Tracking Issue: #10554

`-Z check-cfg` command line enables compile time checking of name and values in `#[cfg]`, `cfg!`, `#[link]` and `#[cfg_attr]` with the `rustc` and `rustdoc` unstable `--check-cfg` command line.

It's values are:

- `features`: enables features checking via `--check-cfg=values(feature, ...)`. Note than this command line options will probably become the default when stabilizing.
- `names`: enables well known names checking via `--check-cfg=names()`.
- `values`: enables well known values checking via `--check-cfg=values()`.

For instance:

    cargo check -Z unstable-options -Z check-cfg=features
    cargo check -Z unstable-options -Z check-cfg=names
    cargo check -Z unstable-options -Z check-cfg=values
    cargo check -Z unstable-options -Z check-cfg=features,names,values

### workspace-inheritance

- RFC: #2906
- Tracking Issue: #8415
- Status
- Example Port

### Testing notes

Target audience for testing

- Maintainer who has a workspace
- (optional) Project depends on nightly toolchain

In preparing to stabilize, we are wanting to better understand

- If there were any pain points in porting your project
- Any errors or bugs that you found in testing
- Performance concerns
- Gaps in documentation
- Thoughts on how you feel this feature will work in practice

Please provide feedback on the tracking issue or create an issue for any bugs encountered.

To get started

1. Have a (recent) nightly version installed
2. Place `cargo-features = ["workspace-inheritance"]` at the top of any `Cargo.toml` you plan to use this feature in
3. Create a `[workspace.package]` and `[workspace.dependencies]` in your workspace `Cargo.toml`
4. Move any package keys or dependencies you feel should be shared between crates to their respective workspace table
5. Change any keys you want to inherit to `{key}.workspace = true` in the member `Cargo.toml`
6. run `cargo +nightly check`

An example port has been made in this PR as a "real-life" guide.

### The `workspace.package` table

Stabilization: This would be in `workspaces.md`, under The `workspace.metadata` table

The `workspace.package` table is where you define keys that can be inherited by members of a workspace. These keys can be inherited by defining them in the member package with `{key}.workspace = true`.

Keys that are supported:

`authors` | `categories`
`description` | `documentation`
`edition` | `exclude`
`homepage` | `include`
`keywords` | `license`
`license-file` | `publish`
`readme` | `repository`
`rust-version` | `version`

- `license-file` and `readme` are relative to the workspace root
- `include` and `exclude` are relative to your package root

Example:

    # [PROJECT_DIR]/Cargo.toml
    [workspace]
    members = ["bar"]

    [workspace.package]
    version = "1.2.3"
    authors = ["Nice Folks"]
    description = "..."
    documentation = "https://example.github.io/example"

    # [PROGJCT_DIR]/bar/Cargo.toml
    cargo-features = ["workspace-inheritance"]

    [package]
    name = "bar"
    version.workspace = true
    authors.workspace = true
    description.workspace = true
    documentation.workspace = true

### The `workspace.dependencies` table

The `workspace.dependencies` table is where you define dependencies to be inherited by members of a workspace.

Specifying a workspace dependency is similar to package dependencies except:

- Dependencies from this table cannot be declared as `optional`
- `features` declared in this table are additive with the `features` from `[dependencies]`

You can then inherit the workspace dependency as a package dependency

Example:

    # [PROJECT_DIR]/Cargo.toml
    [workspace]
    members = ["bar"]

    [workspace.dependencies]
    dep = { version = "0.1", features = ["fancy"] }
    dep-build = "0.8"
    dep-dev = "0.5.2"

    # [PROJECT_DIR]/bar/Cargo.toml
    cargo-features = ["workspace-inheritance"]

    [project]
    name = "bar"
    version = "0.2.0"

    [dependencies]
    dep = { workspace = true, features = ["dancy"] }

    [build-dependencies]
    dep-build.workspace = true

    [dev-dependencies]
    dep-dev.workspace = true

### Inheriting a dependency from a workspace

Stabilization: This would be in `specifying-dependencies.md`, under Renaming dependencies in Cargo.toml

Dependencies can be inherited from a workspace by specifying the dependency in the workspace's `[workspace.dependencies]` table. After that add it to the `[dependencies]` table with `dep.workspace = true`.

The `workspace` key can be defined with:

- `optional`: Note that the`[workspace.dependencies]` table is not allowed to specify `optional`.
- `features`: These are additive with the features declared in the `[workspace.dependencies]`

The `workspace` key cannot be defined with:

`branch` | `default-features`
`git` | `package`
`path` | `registry`
`registry-index` | `rev`
`tag` | `version`

Dependencies in the `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, and `[target."...".dependencies]` sections support the ability to reference the `[workspace.dependencies]` definition of dependencies.

Example:

    [dependencies]
    dep.workspace = true
    dep2 = { workspace = true, features = ["fancy"] }
    dep3 = { workspace = true, optional = true }
    dep4 = { workspace = true, optional = true, features = ["fancy"] }

    [build-dependencies]
    dep-build.workspace = true

    [dev-dependencies]
    dep-dev.workspace = true

## Stabilized and removed features

### Compile progress

The compile-progress feature has been stabilized in the 1.30 release. Progress bars are now enabled by default. See `term.progress` for more information about controlling this feature.

### Edition

Specifying the `edition` in `Cargo.toml` has been stabilized in the 1.31 release. See the edition field for more information about specifying this field.

### rename-dependency

Specifying renamed dependencies in `Cargo.toml` has been stabilized in the 1.31 release. See renaming dependencies for more information about renaming dependencies.

### Alternate Registries

Support for alternate registries has been stabilized in the 1.34 release. See the Registries chapter for more information about alternate registries.

### Offline Mode

The offline feature has been stabilized in the 1.36 release. See the `--offline` flag for more information on using the offline mode.

### publish-lockfile

The `publish-lockfile` feature has been removed in the 1.37 release. The `Cargo.lock` file is always included when a package is published if the package contains a binary target. `cargo install` requires the `--locked` flag to use the `Cargo.lock` file. See `cargo package` and `cargo install` for more information.

### default-run

The `default-run` feature has been stabilized in the 1.37 release. See the `default-run` field for more information about specifying the default target to run.

### cache-messages

Compiler message caching has been stabilized in the 1.40 release. Compiler warnings are now cached by default and will be replayed automatically when re-running Cargo.

### install-upgrade

The `install-upgrade` feature has been stabilized in the 1.41 release. `cargo install` will now automatically upgrade packages if they appear to be out-of-date. See the `cargo install` documentation for more information.

### Profile Overrides

Profile overrides have been stabilized in the 1.41 release. See Profile Overrides for more information on using overrides.

### Config Profiles

Specifying profiles in Cargo config files and environment variables has been stabilized in the 1.43 release. See the config `[profile]` table for more information about specifying profiles in config files.

### crate-versions

The `-Z crate-versions` flag has been stabilized in the 1.47 release. The crate version is now automatically included in the `cargo doc` documentation sidebar.

### Features

The `-Z features` flag has been stabilized in the 1.51 release. See feature resolver version 2 for more information on using the new feature resolver.

### package-features

The `-Z package-features` flag has been stabilized in the 1.51 release. See the resolver version 2 command-line flags for more information on using the features CLI options.

### Resolver

The `resolver` feature in `Cargo.toml` has been stabilized in the 1.51 release. See the resolver versions for more information about specifying resolvers.

### extra-link-arg

The `extra-link-arg` feature to specify additional linker arguments in build scripts has been stabilized in the 1.56 release. See the build script documentation for more information on specifying extra linker arguments.

### configurable-env

The `configurable-env` feature to specify environment variables in Cargo configuration has been stabilized in the 1.56 release. See the config documentation for more information about configuring environment variables.

### rust-version

The `rust-version` field in `Cargo.toml` has been stabilized in the 1.56 release. See the rust-version field for more information on using the `rust-version` field and the `--ignore-rust-version` option.

### codegen-backend

The `codegen-backend` feature makes it possible to select the codegen backend used by rustc using a profile.

Example:

    [package]
    name = "foo"

    [dependencies]
    serde = "1.0.117"

    [profile.dev.package.foo]
    codegen-backend = "cranelift"

### 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 for more information.

### edition 2021

The 2021 edition has been stabilized in the 1.56 release. See the `edition` field for more information on setting the edition. See `cargo fix --edition` and The Edition Guide for more information on migrating existing projects.

### Custom named profiles

Custom named profiles have been stabilized in the 1.57 release. See the profiles chapter for more information.

### Profile `strip` option

The profile `strip` option has been stabilized in the 1.59 release. See the profiles chapter for more information.

### Future incompat report

Support for generating a future-incompat report has been stabilized in the 1.59 release. See the future incompat report chapter for more information.

### Namespaced features

Namespaced features has been stabilized in the 1.60 release. See the Features chapter for more information.

### Weak dependency features

Weak dependency features has been stabilized in the 1.60 release. See the Features chapter for more information.

### timings

The `-Ztimings` option has been stabilized as `--timings` in the 1.60 release. (`--timings=html` and the machine-readable `--timings=json` output remain unstable and require `-Zunstable-options`.)