Unstable Features - The Cargo Book (original) (raw)

The Cargo Book

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:

# 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.  
[unstable]  
mtime-on-use = true  
build-std = ["core", "alloc"]

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

For the latest nightly, see the nightly version of this page.

List of unstable 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-Zallow-features=foo,bar, you’ll continue to be able to pass -Zfooand -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 orrustdoc). Thus, if you run cargo -Zallow-features=, no unstable Cargo or Rust features can be used.

no-index-update

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

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.tomlor 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

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

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 saysfoo = "1.0.0" that you don’t accidentally depend on features added only infoo 1.5.0.

direct-minimal-versions

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

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 saysfoo = "1.0.0" that you don’t accidentally depend on features added only infoo 1.5.0.

Indirect dependencies are resolved as normal so as not to be blocked on their minimal version validation.

artifact-dir

This feature allows you to specify the directory where artifacts will be copied to after they are built. Typically artifacts are only written to thetarget/release or target/debug directories. However, determining the exact filename can be tricky since you need to parse JSON output. The --artifact-dirflag 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 --artifact-dir=out -Z unstable-options

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

[build]
artifact-dir = "out"

root-dir

The -Zroot-dir flag sets the root directory relative to which paths are printed. This affects both diagnostics and paths emitted by the file!() macro.

doctest-xcompile

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

Build-plan

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 is a feature to have declarative build scripts. Instead of writing a build.rs script, you specify a list of build dependencies in themetabuild 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 thepackage, 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

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.

To enable this feature, you can either use -Zpublic-dependency

cargo +nightly run -Zpublic-dependency

or [unstable] table, for example,

# .cargo/config.toml
[unstable]
public-dependency = true

public-dependency could also be enabled in cargo-features, though this is deprecated and will be removed soon.

cargo-features = ["public-dependency"]

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

Documentation updates:

msrv-policy

Catch-all unstable feature for MSRV-aware cargo features underRFC 2495.

MSRV-aware cargo add

This was stabilized in 1.79 in #13608.

MSRV-aware resolver

This was stabilized in 1.84 in #14639.

Convert incompatible_toolchain error into a lint

Unimplemented

--update-rust-version flag for cargo add, cargo update

Unimplemented

package.rust-version = "toolchain"

Unimplemented

Update cargo new template to set package.rust-version = "toolchain"

Unimplemented

precise-pre-release

The precise-pre-release feature allows pre-release versions to be selected with update --preciseeven when a pre-release is not specified by a projects Cargo.toml.

Take for example this Cargo.toml.

[dependencies]
my-dependency = "0.1.1"

It’s possible to update my-dependency to a pre-release with update -Zunstable-options my-dependency --precise 0.1.2-pre.0. This is because 0.1.2-pre.0 is considered compatible with 0.1.1. It would not be possible to upgrade to 0.2.0-pre.0 from 0.1.1 in the same way.

update-breaking

Allow upgrading dependencies version requirements in Cargo.toml across SemVer incompatible versions using with the --breaking flag.

This only applies to dependencies when

Users may further restrict which packages get upgraded by specifying them on the command line.

Example:

$ cargo +nightly -Zunstable-options update --breaking
$ cargo +nightly -Zunstable-options update --breaking clap

This is meant to fill a similar role as cargo-upgrade

build-std

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

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 thetest 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:

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:

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

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 andpanic-unwind. This flag expects a comma-separated list and, if provided, will override the default list of features enabled.

binary-dep-depinfo

The -Z binary-dep-depinfo flag causes Cargo to forward the same flag torustc 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.

checksum-freshness

The -Z checksum-freshness flag will replace the use of file mtimes in cargo’s fingerprints with a file checksum value. This is most useful on systems with a poor mtime implementation, or in CI/CD. The checksum algorithm can change without notice between cargo versions. Fingerprints are used by cargo to determine when a crate needs to be rebuilt.

For the time being files ingested by build script will continue to use mtimes, even when checksum-freshnessis enabled. This is not intended as a long term solution.

panic-abort-tests

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 waytest-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!

config-include

This feature requires the -Zconfig-include command-line option.

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 an array of config file paths. Only path ending with .toml is accepted.

# a path ending with `.toml`
include = "path/to/mordor.toml"

# or an array of paths
include = ["frodo.toml", "samwise.toml"]

Unlike other config values, the merge behavior of the include key is different. When a config file contains an include key:

  1. The config values are first loaded from the include path.
    • If the value of the include key is an array of paths, the config values are loaded and merged from left to right for each path.
    • Recurse this step if the config values from the include path also contain 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

Historically, Cargo’s behavior for whether the linker and rustflagsconfiguration 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 andrustflags for build scripts as for all other compile artifacts. When--target is passed, however, Cargo respects linker from[target.], 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](../appendix/glossary.html#target ""target" (glossary)") 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-leveltarget-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 totrue, 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 falseto 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

The host key in a config file can be used to 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-hostcommand-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 anx86_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 tofalse from true.

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

unit-graph

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

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", "..." ]

To set this in a profile in Cargo configuration, you need to use either-Z profile-rustflags or [unstable] table to enable it. For example,

# .cargo/config.toml
[unstable]
profile-rustflags = true

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

rustdoc-map

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 rustcsysroot. If you are using rustup, this documentation can be installed withrustup component add rust-docs.

The default value is "remote".

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

per-package-target

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 forwasm32-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

Artifact dependencies 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.

artifact-dependencies: Dependency declarations

Artifact-dependencies adds the following keys to a dependency declaration in Cargo.toml:

[dependencies]  
bar = { version = "1.0", artifact = "staticlib" }  
zoo = { version = "1.0", artifact = ["bin:cat", "bin:dog"]}  
[dependencies]  
bar = { version = "1.0", artifact = "bin", lib = true }  
[build-dependencies]  
bar = { version = "1.0", artifact = "cdylib", target = "wasm32-unknown-unknown"}  
same-target = { version = "1.0", artifact = "bin", target = "target" }

artifact-dependencies: Environment variables

After building an artifact dependency, Cargo provides the following environment variables that you can use to access the artifact:

For each kind of dependency, these variables are supplied to the same part of the build process that has access to that kind of dependency:

artifact-dependencies: Examples

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:

[build-dependencies]
some-build-tool = { version = "1.0", artifact = "bin" }

Then inside the build script, the binary can be executed at build time:

fn main() {
    let build_tool = std::env::var_os("CARGO_BIN_FILE_SOME_BUILD_TOOL").unwrap();
    let status = std::process::Command::new(build_tool)
        .arg("do-stuff")
        .status()
        .unwrap();
    if !status.success() {
        eprintln!("failed!");
        std::process::exit(1);
    }
}

Example: use cdylib artifact in build script

The Cargo.toml in the consuming package, building the bar library as cdylibfor 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"));
}

publish-timeout

The publish.timeout key in a config file can be used to control how longcargo publish waits between posting a package to the registry and it being available in the local index.

A timeout of 0 prevents any checks from occurring. The current default is60 seconds.

It requires the -Zpublish-timeout command-line options to be set.

# config.toml
[publish]
timeout = 300  # in seconds

asymmetric-token

The -Z asymmetric-token flag enables the cargo:paseto credential provider which allows Cargo to authenticate to registries without sending secrets over the network.

In config.toml and credentials.toml files there is a field called private-key, which is a private key formatted in the secret subset of PASERK and is used to sign asymmetric tokens

A keypair can be generated with cargo login --generate-keypair which will:

It is recommended that the private-key be saved in credentials.toml. It is also supported in config.toml, primarily so that it can be set using the associated environment variable, which is the recommended way to provide it in CI contexts. This setup is what we have for the token field for setting a secret token.

There is also an optional field called private-key-subject which is a string chosen by the registry. This string will be included as part of an asymmetric token and should not be secret. It is intended for the rare use cases like “cryptographic proof that the central CA server authorized this action”. Cargo requires it to be non-whitespace printable ASCII. Registries that need non-ASCII data should base64 encode it.

Both fields can be set with cargo login --registry=name --private-key --private-key-subject="subject" which will prompt you to put in the key value.

A registry can have at most one of private-key or token set.

All PASETOs will include iat, the current time in ISO 8601 format. Cargo will include the following where appropriate:

The “footer” (which is part of the signature) will be a JSON string in UTF-8 and include:

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.

cargo config

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.

rustc --print

cargo rustc --print=VAL forwards the --print flag to rustc in order to extract information from rustc. This runs rustc with the corresponding--printflag, 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

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"]

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

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

scrape-examples

The -Z rustdoc-scrape-examples flag tells Rustdoc to search crates in the current workspace for calls to functions. Those call-sites are then included as documentation. You can use the flag like this:

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

By default, Cargo will scrape examples from the example targets of packages being documented. You can individually enable or disable targets from being scraped with the doc-scrape-examples flag, such as:

# Enable scraping examples from a library
[lib]
doc-scrape-examples = true

# Disable scraping examples from an example target
[[example]]
name = "my-example"
doc-scrape-examples = false

Note on tests: enabling doc-scrape-examples on test targets will not currently have any effect. Scraping examples from tests is a work-in-progress.

Note on dev-dependencies: documenting a library does not normally require the crate’s dev-dependencies. However, example targets require dev-deps. For backwards compatibility, -Z rustdoc-scrape-examples will not introduce a dev-deps requirement for cargo doc. Therefore examples will not be scraped from example targets under the following conditions:

  1. No target being documented requires dev-deps, AND
  2. At least one crate with targets being documented has dev-deps, AND
  3. The doc-scrape-examples parameter is unset or false for all [[example]] targets.

If you want examples to be scraped from example targets, then you must not satisfy one of the above conditions. For example, you can set doc-scrape-examples to true for one example target, and that signals to Cargo that you are ok with dev-deps being build for cargo doc.

output-format for rustdoc

This flag determines the output format of cargo rustdoc, accepting html or json, providing tools with a way to lean on rustdoc’s experimental JSON format.

You can use the flag like this:

cargo rustdoc -Z unstable-options --output-format json

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"

To set this in a profile in Cargo configuration, you need to use either-Z codegen-backend or [unstable] table to enable it. For example,

# .cargo/config.toml
[unstable]
codegen-backend = true

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

gitoxide

With the ‘gitoxide’ unstable feature, all or the specified git operations will be performed by the gitoxide crate instead of git2.

While -Zgitoxide enables all currently implemented features, one can individually select git operations to run with gitoxide with the -Zgitoxide=operation[,operationN] syntax.

Valid operations are the following:

git

With the ‘git’ unstable feature, both gitoxide and git2 will perform shallow fetches of the crate index and git dependencies.

While -Zgit enables all currently implemented features, one can individually select when to perform shallow fetches with the -Zgit=operation[,operationN] syntax.

Valid operations are the following:

Details on shallow clones

script

Cargo can directly run .rs files as:

$ cargo +nightly -Zscript file.rs

where file.rs can be as simple as:

fn main() {}

A user may optionally specify a manifest in a cargo code fence in a module-level comment, like:

#!/usr/bin/env -S cargo +nightly -Zscript
---cargo
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

Single-file packages

In addition to today’s multi-file packages (Cargo.toml file with other .rsfiles), we are adding the concept of single-file packages which may contain an embedded manifest. There is no required distinguishment for a single-file.rs package from any other .rs file.

Single-file packages may be selected via --manifest-path, likecargo test --manifest-path foo.rs. Unlike Cargo.toml, these files cannot be auto-discovered.

A single-file package may contain an embedded manifest. An embedded manifest is stored using TOML in rust “frontmatter”, a markdown code-fence with cargoat the start of the infostring at the top of the file.

Inferred / defaulted manifest fields:

Disallowed manifest fields:

The default CARGO_TARGET_DIR for single-file packages is at $CARGO_HOME/target/<hash>:

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

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 intended for being put in #! lines.

The precedence for how to interpret cargo <subcommand> is

  1. Built-in xor single-file packages
  2. Aliases
  3. External subcommands

A parameter is identified as a manifest-command if it has one of:

Differences between cargo run --manifest-path <path> and cargo <path>

Documentation Updates

Profile trim-paths option

This adds a new profile setting to control how paths are sanitized in the resulting binary. This can be enabled like so:

cargo-features = ["trim-paths"]

[package]
# ...

[profile.release]
trim-paths = ["diagnostics", "object"]

To set this in a profile in Cargo configuration, you need to use either -Z trim-paths or [unstable] table to enable it. For example,

# .cargo/config.toml
[unstable]
trim-paths = true

[profile.release]
trim-paths = ["diagnostics", "object"]

Documentation updates

trim-paths

as a new “Profiles settings” entry

trim-paths is a profile setting which enables and controls the sanitization of file paths in build outputs. It takes the following values:

It also takes an array with the combinations of "macro", "diagnostics", and "object".

It is defaulted to none for the dev profile, and object for the release profile. You can manually override it by specifying this option in Cargo.toml:

[profile.dev]
trim-paths = "all"

[profile.release]
trim-paths = ["object", "diagnostics"]

The default release profile setting (object) sanitizes only the paths in emitted executable or library files. It always affects paths from macros such as panic messages, and in debug information only if they will be embedded together with the binary (the default on platforms with ELF binaries, such as Linux and windows-gnu), but will not touch them if they are in separate files (the default on Windows MSVC and macOS). But the paths to these separate files are sanitized.

If trim-paths is not none or false, then the following paths are sanitized if they appear in a selected scope:

  1. Path to the source files of the standard and core library (sysroot) will begin with /rustc/[rustc commit hash], e.g. /home/username/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs ->/rustc/fe72845f7bb6a77b9e671e6a4f32fe714962cec4/library/core/src/result.rs
  2. Path to the current package will be stripped, relatively to the current workspace root, e.g. /home/username/crate/src/lib.rs -> src/lib.rs.
  3. Path to dependency packages will be replaced with [package name]-[version]. E.g. /home/username/deps/foo/src/lib.rs -> foo-0.1.0/src/lib.rs

When a path to the source files of the standard and core library is not in scope for sanitization, the emitted path will depend on if rust-src component is present. If it is, then some paths will point to the copy of the source files on your file system; if it isn’t, then they will show up as /rustc/[rustc commit hash]/library/...(just like when it is selected for sanitization). Paths to all other source files will not be affected.

This will not affect any hard-coded paths in the source code, such as in strings.

Environment variable

as a new entry of “Environment variables Cargo sets for build scripts”

gc

The -Zgc flag enables garbage-collection within cargo’s global cache within the cargo home directory. This includes downloaded dependencies such as compressed .crate files, extracted src directories, registry index caches, and git dependencies. When -Zgc is present, cargo will track the last time any index and dependency was used, and then uses those timestamps to manually or automatically delete cache entries that have not been used for a while.

cargo build -Zgc

Automatic garbage collection

Automatic deletion happens on commands that are already doing a significant amount of work, such as all of the build commands (cargo build, cargo test, cargo check, etc.), and cargo fetch. The deletion happens just after resolution and packages have been downloaded. Automatic deletion is only done once per day (see gc.auto.frequency to configure). Automatic deletion is disabled if cargo is offline such as with --offline or --frozen to avoid deleting artifacts that may need to be used if you are offline for a long period of time.

Automatic gc configuration

The automatic gc behavior can be specified via a cargo configuration setting. The settings available are:

# Example config.toml file.

# This table defines the behavior for automatic garbage collection.
[gc.auto]
# The maximum frequency that automatic garbage collection happens.
# Can be "never" to disable automatic-gc, or "always" to run on every command.
frequency = "1 day"
# Anything older than this duration will be deleted in the source cache.
max-src-age = "1 month"
# Anything older than this duration will be deleted in the compressed crate cache.
max-crate-age = "3 months"
# Any index older than this duration will be deleted from the index cache.
max-index-age = "3 months"
# Any git checkout older than this duration will be deleted from the checkout cache.
max-git-co-age = "1 month"
# Any git clone older than this duration will be deleted from the git cache.
max-git-db-age = "3 months"

Manual garbage collection with cargo clean

Manual deletion can be done with the cargo clean gc command. Deletion of cache contents can be performed by passing one of the cache options:

A DURATION is specified in the form “N seconds/minutes/days/weeks/months” where N is an integer.

A SIZE is specified in the form “N _suffix_” where suffix is B, kB, MB, GB, kiB, MiB, or GiB, and N is an integer or floating point number. If no suffix is specified, the number is the number of bytes.

cargo clean gc
cargo clean gc --max-download-age=1week
cargo clean gc --max-git-size=0 --max-download-size=100MB

open-namespaces

Allow multiple packages to participate in the same API namespace

This can be enabled like so:

cargo-features = ["open-namespaces"]

[package]
# ...

[lints.cargo]

A new lints tool table for cargo that can be used to configure lints emitted by cargo itself when -Zcargo-lints is used

[lints.cargo]
implicit-features = "warn"

This will work withRFC 2906 workspace-deduplicate:

[workspace.lints.cargo]
implicit-features = "warn"

[lints]
workspace = true

Path Bases

A path dependency may optionally specify a base by setting the base key to the name of a path base from the [path-bases] table in either theconfiguration or one of the built-in path bases. The value of that path base is prepended to the path value (along with a path separator if necessary) to produce the actual location where Cargo will look for the dependency.

For example, if the Cargo.toml contains:

cargo-features = ["path-bases"]

[dependencies]
foo = { base = "dev", path = "foo" }

Given a [path-bases] table in the configuration that contains:

[path-bases]
dev = "/home/user/dev/rust/libraries/"

This will produce a path dependency foo located at/home/user/dev/rust/libraries/foo.

Path bases can be either absolute or relative. Relative path bases are relative to the parent directory of the configuration file that declared that path base.

The name of a path base must use only alphanumericcharacters or - or _, must start with an alphabeticcharacter, and must not be empty.

If the name of path base used in a dependency is neither in the configuration nor one of the built-in path base, then Cargo will raise an error.

Built-in path bases

Cargo provides implicit path bases that can be used without the need to specify them in a [path-bases] table.

If a built-in path base name is also declared in the configuration, then Cargo will prefer the value in the configuration. The allows Cargo to add new built-in path bases without compatibility issues (as existing uses will shadow the built-in name).

lockfile-path

This feature allows you to specify the path of lockfile Cargo.lock. By default, lockfile is written into <workspace_root>/Cargo.lock. However, when sources are stored in read-only directory, most of the cargo commands would fail, trying to write a lockfile. The --lockfile-pathflag makes it easier to work with readonly sources. Note, that currently path must end with Cargo.lock. Meaning, if you want to use this feature in multiple projects, lockfiles should be stored in different directories. Example:

cargo +nightly metadata --lockfile-path=$LOCKFILES_ROOT/my-project/Cargo.lock -Z unstable-options

package-workspace

This allows cargo to package (or publish) multiple crates in a workspace, even if they have inter-dependencies. For example, consider a workspace containing packages foo and dep, where foo depends on dep. Then

cargo +nightly -Zpackage-workspace package -p foo -p dep

will package both foo and dep, while

cargo +nightly -Zpackage-workspace publish -p foo -p dep

will publish both foo and dep. If foo and dep are the only crates in the workspace, you can use the --workspaceflag instead of specifying the crates individually:

cargo +nightly -Zpackage-workspace package --workspace
cargo +nightly -Zpackage-workspace publish --workspace

Lock-file behavior

When packaging a binary at the same time as one of its dependencies, the binary will be packaged with a lock-file pointing at the dependency’s registry entry_as though the dependency were already published_, even though it has not yet been. In this case, cargo needs to know the registry that the dependency will eventually be published on. cargo will attempt to infer this registry by examining the the publish field, falling back to crates.io if no publish field is set. To explicitly set the registry, pass a --registry or --index flag.

cargo +nightly -Zpackage-workspace --registry=my-registry package -p foo -p dep
cargo +nightly -Zpackage-workspace --index=https://example.com package -p foo -p dep

native-completions

This feature moves the handwritten completion scripts to Rust native, making it easier for us to add, extend and test new completions. This feature is enabled with the nightly channel, without requiring additional -Z options.

Areas of particular interest for feedback

Feedback can be broken down into

When in doubt, you can discuss this in #14520 or on zulip

How to use native-completions feature:

warnings

The -Z warnings feature enables the build.warnings configuration option to control how Cargo handles warnings. If the -Z warnings unstable flag is not enabled, then the build.warnings config will be ignored.

This setting currently only applies to rustc warnings. It may apply to additional warnings (such as Cargo lints or Cargo warnings) in the future.

build.warnings

Controls how Cargo handles warnings. Allowed values are:

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 dependenciesfor 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 andcargo 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 thecargo doc documentation sidebar.

Features

The -Z features flag has been stabilized in the 1.51 release. See feature resolver version 2for 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 flagsfor 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.

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.

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

Profile strip option

The profile strip option has been stabilized in the 1.59 release. See theprofiles 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 chapterfor 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.)

config-cli

The --config CLI option has been stabilized in the 1.63 release. See the config documentation for more information.

multitarget

The -Z multitarget option has been stabilized in the 1.64 release. See build.target for more information about setting the default [target platform triples](../appendix/glossary.html#target ""target" (glossary)").

crate-type

The --crate-type flag for cargo rustc has been stabilized in the 1.64 release. See the cargo rustc documentationfor more information.

Workspace Inheritance

Workspace Inheritance has been stabilized in the 1.64 release. See workspace.package,workspace.dependencies, and inheriting-a-dependency-from-a-workspacefor more information.

terminal-width

The -Z terminal-width option has been stabilized in the 1.68 release. The terminal width is always passed to the compiler when running from a terminal where Cargo can automatically detect the width.

sparse-registry

Sparse registry support has been stabilized in the 1.68 release. See Registry Protocols for more information.

cargo logout

The cargo logout command has been stabilized in the 1.70 release.

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 thecargo test documentationfor more information about the working directory for compiling and running tests.

keep-going

The --keep-going option has been stabilized in the 1.74 release. See the--keep-going flagin cargo build as an example for more details.

[lints]

[lints] (enabled via -Zlints) has been stabilized in the 1.74 release.

credential-process

The -Z credential-process feature has been stabilized in the 1.74 release.

See Registry Authentication documentation for details.

registry-auth

The -Z registry-auth feature has been stabilized in the 1.74 release with the additional requirement that a credential-provider is configured.

See Registry Authentication documentation for details.

check-cfg

The -Z check-cfg feature has been stabilized in the 1.80 release by making it the default behavior.

See the build script documentation for information about specifying custom cfgs.

Edition 2024

The 2024 edition has been stabilized in the 1.85 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.