Optimizing Build Performance

Cargo configuration options and source code organization patterns can help improve build performance, by prioritizing it over other aspects which may not be as important for your circumstances.

Same as when optimizing runtime performance, be sure to measure these changes against the workflows you actually care about, as we provide general guidelines and your circumstances may be different, it is possible that some of these approaches might actually make build performance worse for your use-case.

Example workflows to consider include:

• Compiler feedback as you develop (cargo check after making a code change)
• Test feedback as you develop (cargo test after making a code change)
• CI builds

Cargo and Compiler Configuration

Cargo uses configuration defaults that try to balance several aspects, including debuggability, runtime performance, build performance, binary size and others. This section describes several approaches for changing these defaults that should be designed to maximize build performance.

Common locations to override defaults are:

• Cargo.toml manifest
  • Available to all developers contributing to your project
  • Limited in what configuration is supported (see #12738 for expanding this)
• $WORKSPACE_ROOT/.cargo/config.toml configuration file
  • Available to all developers contributing to your project
  • Unlike Cargo.toml, this is sensitive to what directory you invoke cargo from (see #2930)
• $CARGO_HOME/.cargo/config.toml configuration file
  • For a developer to control the defaults for their development

Reduce amount of generated debug information

Recommendation: Add to your Cargo.toml or .cargo/config.toml:

[profile.dev]
debug = "line-tables-only"

[profile.dev.package."*"]
debug = false

[profile.debugging]
inherits = "dev"
debug = true

This will:

• Change the dev profile (default for development commands) to:
  • Limit debug information for workspace members to what is needed for useful panic backtraces
  • Avoid generating any debug information for dependencies
• Provide an opt-in for when debugging via --profile debugging

Trade-offs:

• ✅ Faster code generation (cargo build)
• ✅ Faster link times
• ✅ Smaller disk usage of the target directory
• ❌ Requires a full rebuild to have a high-quality debugger experience

Use an alternative codegen backend

Recommendation:

• Install the Cranelift codegen backend rustup component

  $ rustup component add rustc-codegen-cranelift-preview --toolchain nightly
  

• Add to your Cargo.toml or .cargo/config.toml:

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

• Run Cargo with -Z codegen-backend or enable the codegen-backend feature in .cargo/config.toml.
  • This is required because this is currently an unstable feature.

This will change the dev profile to use the Cranelift codegen backend for generating machine code, instead of the default LLVM backend. The Cranelift backend should generate code faster than LLVM, which should result in improved build performance.

Trade-offs:

• ✅ Faster code generation (cargo build)
• ❌ Requires using nightly Rust and an unstable Cargo feature
• ❌ Worse runtime performance of the generated code
  • Speeds up build part of cargo test, but might increase its test execution part
• ❌ Only available for certain targets
• ❌ Might not support all Rust features (e.g. unwinding)

Enable the experimental parallel frontend

Recommendation: Add to your .cargo/config.toml:

[build]
rustflags = "-Zthreads=8"

This rustflags will enable the parallel frontend of the Rust compiler, and tell it to use n threads. The value of n should be chosen according to the number of cores available on your system, although there are diminishing returns. We recommend using at most 8 threads.

Trade-offs:

• ✅ Faster build times (both cargo check and cargo build)
• ❌ Requires using nightly Rust and an unstable Rust feature

Use an alternative linker

Consider: installing and configuring an alternative linker, like LLD, mold or wild. For example, to configure mold on Linux, you can add to your .cargo/config.toml:

[target.'cfg(target_os = "linux")']
# mold, if you have GCC 12+
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

# mold, otherwise
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]

While dependencies may be built in parallel, linking all of your dependencies happens at once at the end of your build, which can make linking dominate your build times, especially for incremental rebuilds. Often, the linker Rust uses is already fairly fast and the gains from switching may not be worth it, but it is not always the case. For example, Linux targets besides x86_64-unknown-linux-gnu still use the Linux system linker which is quite slow (see rust#39915 for more details).

Trade-offs:

• ✅ Faster link times
• ❌ Might not support all use-cases, in particular if you depend on C or C++ dependencies

Resolve features for the whole workspace

Consider: adding to your project’s .cargo/config.toml

[resolver]
feature-unification = "workspace"

When invoking cargo, features get activated based on which workspace members you have selected. However, when contributing to an application, you may need to build and test various packages within the application, which can cause extraneous rebuilds because different sets of features may be activated for common dependencies. With feauture-unification, you can reuse more dependency builds by ensuring the same set of dependency features are activated, independent of which package you are currently building and testing.

Trade-offs:

• ✅ Fewer rebuilds when building different packages in a workspace
• ❌ Requires using nightly Rust and an unstable Cargo feature
• ❌ A package activating a feature can mask bugs in other packages that should activate it but don’t
• ❌ If the feature unification from --workspace doesn’t work for you, then this won’t either

Reducing built code

Removing unused dependencies

Recommendation: Periodically review unused dependencies for removal using third-party tools like cargo-machete, cargo-udeps, cargo-shear.

When changing code, it can be easy to miss that a dependency is no longer used and can be removed.

Note: native support for this in Cargo is being tracked in #15813.

Trade-offs:

• ✅ Faster full build and link times
• ❌ May incorrectly flag dependencies as unused or miss some

Removing unused features from dependencies

Recommendation: Periodically review unused features from dependencies for removal using third-party tools like cargo-features-manager, cargo-unused-features.

When changing code, it can be easy to miss that a dependency’s feature is no longer used and can be removed. This can reduce the number of transitive dependencies being built or reduce the amount of code within a crate being built. When removing features, extra caution is needed because features may also be used for desired behavior or performance changes which may not always be obvious from compiling or testing.

Trade-offs:

• ✅ Faster full build and link times
• ❌ May incorrectly flag features as unused