Unstable Features

Experimental Cargo features are only available on the nightly channel. Youtypically use one of the -Z flags to enable them. Run cargo -Z help tosee a list of flags available.

-Z unstable-options is a generic flag for enabling other unstablecommand-line flags. Options requiring this will be called out below.

Some unstable features will require you to specify the cargo-features key inCargo.toml.

no-index-update

  • Original Issue: #3479The -Z no-index-update flag ensures that Cargo does not attempt to updatethe registry index. This is intended for tools such as Crater that issue manyCargo commands, and you want to avoid the network latency for updating theindex each time.

avoid-dev-deps

  • Original Issue: #4988
  • Stabilization Issue: #5133When running commands such as cargo install or cargo build, Cargocurrently requires dev-dependencies to be downloaded, even if they are notused. The -Z avoid-dev-deps flag allows Cargo to avoid downloadingdev-dependencies if they are not needed. The Cargo.lock file will not begenerated if dev-dependencies are skipped.

minimal-versions

  • Original Issue: #4100
  • Tracking Issue: #5657When a Cargo.lock file is generated, the -Z minimal-versions flag willresolve the dependencies to the minimum semver version that will satisfy therequirements (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 theminimum 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.

out-dir

  • Original Issue: #4875
  • Tracking Issue: #6790This feature allows you to specify the directory where artifacts will becopied to after they are built. Typically artifacts are only written to thetarget/release or target/debug directories. However, determining theexact filename can be tricky since you need to parse JSON output. The—out-dir flag makes it easier to predictably access the artifacts. Notethat the artifacts are copied, so the originals are still in the targetdirectory. Example:
  1. cargo +nightly build --out-dir=out -Z unstable-options

Profile Overrides

  • Tracking Issue: rust-lang/rust#48683
  • RFC: #2282Profiles can be overridden for specific packages and custom build scripts.The general format looks like this:
  1. cargo-features = ["profile-overrides"]
  3. [package]
  4. ...
  6. [profile.dev]
  7. opt-level = 0
  8. debug = true
  10. # the `image` crate will be compiled with -Copt-level=3
  11. [profile.dev.overrides.image]
  12. opt-level = 3
  14. # All dependencies (but not this crate itself or any workspace member)
  15. # will be compiled with -Copt-level=2 . This includes build dependencies.
  16. [profile.dev.overrides."*"]
  17. opt-level = 2
  19. # Build scripts or proc-macros and their dependencies will be compiled with
  20. # `-Copt-level=3`. By default, they use the same rules as the rest of the
  21. # profile.
  22. [profile.dev.build-override]
  23. opt-level = 3

Overrides can only be specified for dev and release profiles.

Config Profiles

  • Tracking Issue: rust-lang/rust#48683
  • RFC: #2282Profiles can be specified in .cargo/config files. The -Z config-profilecommand-line flag is required to use this feature. The format is the same asin a Cargo.toml manifest. If found in multiple config files, settings willbe merged using the regular config hierarchy.Config settings take precedence over manifest settings.
  1. [profile.dev]
  2. opt-level = 3
  1. cargo +nightly build -Z config-profile

Namespaced features

  • Original issue: #1286
  • Tracking Issue: #5565Currently, it is not possible to have a feature and a dependency with the samename in the manifest. If you set namespaced-features to true, the namespacesfor features and dependencies are separated. The effect of this is that, in thefeature requirements, dependencies have to be prefixed with crate:. Like this:
  1. [package]
  2. namespaced-features = true
  4. [features]
  5. bar = ["crate:baz", "foo"]
  6. foo = []
  8. [dependencies]
  9. baz = { version = "0.1", optional = true }

To prevent unnecessary boilerplate from having to explicitly declare featuresfor each optional dependency, implicit features get created for any optionaldependencies where a feature of the same name is not defined. However, ifa feature of the same name as a dependency is defined, that feature mustinclude the dependency as a requirement, as foo = ["crate:foo"].

Build-plan

  • Tracking Issue: #5579The —build-plan argument for the build command will output JSON withinformation about which commands would be run without actually executinganything. This can be useful when integrating with another build tool.Example:
  1. cargo +nightly build --build-plan -Z unstable-options

Metabuild

  • Tracking Issue: rust-lang/rust#49803
  • RFC: #2196Metabuild is a feature to have declarative build scripts. Instead of writinga build.rs script, you specify a list of build dependencies in themetabuild key in Cargo.toml. A build script is automatically generatedthat runs each build dependency in order. Metabuild packages can then readmetadata 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 metadatathat the metabuild packages require under package.metadata. Example:

  1. cargo-features = ["metabuild"]
  3. [package]
  4. name = "mypackage"
  5. version = "0.0.1"
  6. metabuild = ["foo", "bar"]
  8. [build-dependencies]
  9. foo = "1.0"
  10. bar = "1.0"
  12. [package.metadata.foo]
  13. extra-info = "qwerty"

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

install-upgrade

  • Tracking Issue: #6797The install-upgrade feature changes the behavior of cargo install so thatit will reinstall a package if it is not "up-to-date". If it is "up-to-date",it will do nothing and exit with success instead of failing. Example:
  1. cargo +nightly install foo -Z install-upgrade

Cargo tracks some information to determine if a package is "up-to-date",including:

  • The package version and source.
  • The set of binary names installed.
  • The chosen features.
  • The release mode (—debug).
  • The target (—target).If any of these values change, then Cargo will reinstall the package.

Installation will still fail if a different package installs a binary of thesame name. —force may be used to unconditionally reinstall the package.

Installing with —path will always build and install, unless there areconflicting binaries from another package.

Additionally, a new flag —no-track is available to prevent cargo installfrom writing tracking information in $CARGO_HOME about which packages areinstalled.

public-dependency

  • Tracking Issue: #44663The 'public-dependency' feature allows marking dependencies as 'public'or 'private'. When this feature is enabled, additional information is passed to rustc to allowthe 'exported_private_dependencies' lint to function properly.

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

  1. cargo-features = ["public-dependency"]
  3. [dependencies]
  4. my_dep = { version = "1.2.3", public = true }
  5. private_dep = "2.0.0" # Will be 'private' by default

cache-messages

  • Tracking Issue: #6986The cache-messages feature causes Cargo to cache the messages generated bythe compiler. This is primarily useful if a crate compiles successfully withwarnings. Previously, re-running Cargo would not display any output. With thecache-messages feature, it will quickly redisplay the previous warnings.
  1. cargo +nightly check -Z cache-messages

This works with any command that runs the compiler (build, check, test,etc.).

This also changes the way Cargo interacts with the compiler, helping toprevent interleaved messages when multiple crates attempt to display a messageat the same time.

build-std

  • Tracking Repository: https://github.com/rust-lang/wg-cargo-std-awareThe build-std feature enables Cargo to compile the standard library itself aspart of a crate graph compilation. This feature has also historically been knownas "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 largefeature to document, even in the minimal form that it exists in today, so ifyou're curious to stay up to date you'll want to follow the trackingrepository and its set ofissues.

The functionality implemented today is behind a flag called -Z build-std. Thisflag indicates that Cargo should compile the standard library from source codeusing the same profile as the main build itself. Note that for this to work youneed to have the source code for the standard library available, and at thistime the only supported method of doing so is to add the rust-src rust rustupcomponent:

  1. $ 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'rejust forced to pass —target in one form or another.

Usage looks like:

  1. $ cargo new foo
  2. $ cd foo
  3. $ cargo +nightly run -Z build-std --target x86_64-unknown-linux-gnu
  4.    Compiling core v0.0.0 (...)
  5.    ...
  6.    Compiling foo v0.1.0 (...)
  7.     Finished dev [unoptimized + debuginfo] target(s) in 21.00s
  8.      Running `target/x86_64-unknown-linux-gnu/debug/foo`
  9. 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 someof these crates, then you can pass an argument to -Zbuild-std as well:

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

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

Requirements

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

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

Reporting bugs and helping out

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

timings

The timings feature gives some information about how long each compilationtakes, and tracks concurrency information over time.

  1. cargo +nightly build -Z timings

The -Ztimings flag can optionally take a comma-separated list of thefollowing values:

  • html — Saves a file called cargo-timing.html to the current directorywith a report of the compilation. Files are also saved with a timestamp inthe filename if you want to look at older runs.
  • info — Displays a message to stdout after each compilation finishes withhow long it took.
  • json — Emits some JSON information about timing information.The default if none are specified is html,info.

Reading the graphs

There are two graphs in the output. The "unit" graph shows the duration ofeach unit over time. A "unit" is a single compiler invocation. There are linesthat show which additional units are "unlocked" when a unit finishes. That is,it shows the new units that are now allowed to run because their dependenciesare all finished. Hover the mouse over a unit to highlight the lines. This canhelp visualize the critical path of dependencies. This may change between runsbecause the units may finish in different orders.

The "codegen" times are highlighted in a lavender color. In some cases, buildpipelining allows units to start when their dependencies are performing codegeneration. This information is not always displayed (for example, binaryunits do not show when code generation starts).

The "custom build" units are build.rs scripts, which when run arehighlighted in orange.

The second graph shows Cargo's concurrency over time. The three lines are:

  • "Waiting" (red) — This is the number of units waiting for a CPU slot toopen.
  • "Inactive" (blue) — This is the number of units that are waiting for theirdependencies to finish.
  • "Active" (green) — This is the number of units currently running.Note: This does not show the concurrency in the compiler itself. rustccoordinates with Cargo via the "job server" to stay within the concurrencylimit. This currently mostly applies to the code generation phase.

Tips for addressing compile times:

  • Look for slow dependencies.
    • Check if they have features that you may wish to consider disabling.
    • Consider trying to remove the dependency completely.
  • Look for a crate being built multiple times with different versions. Try toremove the older versions from the dependency graph.
  • Split large crates into smaller pieces.
  • If there are a large number of crates bottlenecked on a single crate, focusyour attention on improving that one crate to improve parallelism.