Skip to content

docs(guide): Cover feature-unification #16108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 14, 2025
Merged

docs(guide): Cover feature-unification #16108

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions src/doc/src/guide/build-performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,33 @@ 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`

```toml
[resolver]
feature-unification = "workspace"
```

When invoking `cargo`,
[features get activated][resolver-features] based on which workspace members you have selected.
However, when contributing to an application,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the word "application" here a bit confusing, I'd expect it to simply say "workspace".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is very intentional wording. Some people use cargo-hakari as a "build accelerator" by forcing feature sharing, including between host and target. RFC 3692 was taking a more limited scope of providing an easy way to approximate "build library X as if I was building it for application Y".

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`][feature-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][feature-unification]**
- ❌ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not stable (yet), do we want to call out it requires nightly Cargo? I've seem some other recommendations here did

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was probably doing something in parallel and overlooked the second item already pointed it out


[resolver-features]: ../reference/resolver.md#features
[feature-unification]: ../reference/unstable.md#feature-unification

## Reducing built code

### Removing unused dependencies
Expand Down