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 acargo-features
key at the top ofCargo.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 theunstable
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.
- Profile
- 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-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 thelogout
command to remove the currently saved registry token.- sparse-registry — Adds support for fetching from static-file 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
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.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
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 says
foo = "1.0.0"
that you don't accidentally depend on features added only in
foo 1.5.0
.
out-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 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
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 allcargo
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
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
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-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
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
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
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
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")); }
sparse-registry
The sparse-registry
feature allows cargo to interact with remote registries served
over plain 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 sparse index is identical to a checkout of a git-based index.
credential-process
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 1passwordop
CLI to store the token. You must install theop
CLI from the 1password website. You must runop signin
at least once with the appropriate arguments (such asop 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 appropriateOP_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 asmy.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 thecargo
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
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
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
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
-Z check-cfg
command line enables compile time checking of name and values in #[cfg]
, cfg!
,
#[link]
and #[cfg_attr]
with the rustc
and rustdoc
unstable --check-cfg
command line.
It's values are:
features
: enables features checking via--check-cfg=values(feature, ...)
. Note than this command line options will probably become the default when stabilizing.names
: enables well known names checking via--check-cfg=names()
.values
: enables well known values checking via--check-cfg=values()
.output
: enable the use ofrustc-check-cfg
in build script.
For instance:
cargo check -Z unstable-options -Z check-cfg=features
cargo check -Z unstable-options -Z check-cfg=names
cargo check -Z unstable-options -Z check-cfg=values
cargo check -Z unstable-options -Z check-cfg=features,names,values
Or for output
:
#![allow(unused)] fn main() { // build.rs println!("cargo:rustc-check-cfg=names(foo, bar)"); }
cargo check -Z unstable-options -Z check-cfg=output
cargo:rustc-check-cfg=CHECK_CFG
The rustc-check-cfg
instruction tells Cargo to pass the given value to the
--check-cfg
flag to the compiler. This may be used for compile-time
detection of unexpected conditional compilation name and/or values.
This can only be used in combination with -Zcheck-cfg=output
otherwise it is ignored
with a warning.
If you want to integrate with Cargo features, use -Zcheck-cfg=features
instead of
trying to do it manually with this option.
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
- Have a (recent) nightly version installed
- Place
cargo-features = ["workspace-inheritance"]
at the top of anyCargo.toml
you plan to use this feature in - Create a
[workspace.package]
and[workspace.dependencies]
in your workspaceCargo.toml
- Move any package keys or dependencies you feel should be shared between crates to their respective workspace table
- Change any keys you want to inherit to
{key}.workspace = true
in the memberCargo.toml
- 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
andreadme
are relative to the workspace rootinclude
andexclude
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 thefeatures
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 specifyoptional
.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
.)
config-cli
The --config
CLI option has been stabilized in the 1.63 release. See
the config documentation for more
information.