cargo hakari is a command-line application to manage workspace-hack crates. Use it to speed up
cargo build and
cargo check commands by 15-95%, and cumulatively by
20-25% or more.
For an explanation of what workspace-hack packages are and how they make your builds faster, see
cargo-guppy repository uses a workspace-hack crate managed by
cargo hakari. See the
- Unix platforms: Hakari works and is supported.
- Windows: Hakari works and outputs file paths with forward slashes for
consistency with Unix. CRLF line endings are not supported in the workspace-hack’s
Cargo.toml. Within Git repositories,
cargo hakari initautomatically does this for you. Here’s how to do it manually. (Pull requests to improve this are welcome.)
cargo binstall cargo-hakari
In GitHub Actions CI, use
cargo binstall under the hood:
- name: Install cargo-hakari uses: taiki-e/install-action@v2 with: tool: cargo-hakari
To install or update
cargo install cargo-hakari --locked
$HOME/.cargo/bin is in your
cargo hakari command will be available.
There are four steps you must take for
cargo hakari to work properly.
For hakari to work correctly, you must add your
Cargo.lock to version
even if you don’t have any binary crates. This is because patch version bumps in
dependencies can add or remove features or even entire transitive dependencies.
Initialize a workspace-hack crate for a workspace at path
cargo hakari init my-workspace-hack
Generate or update the contents of a workspace-hack crate:
cargo hakari generate
Add the workspace-hack crate as a dependency to all other workspace crates:
cargo hakari manage-deps
These are things that are not absolutely necessary to do, but will make
cargo hakari work
- uncomment or add commonly-used developer platforms
- read the note about the resolver, and strongly consider
resolver = "2"in your workspace’s
Remember to run
cargo hakari generate after changing the config.
Run the following commands in CI:
cargo hakari generate --diff # workspace-hack Cargo.toml is up-to-date cargo hakari manage-deps --dry-run # all workspace crates depend on workspace-hack
If either of these commands exits with a non-zero status, you can choose to fail CI or produce a warning message.
For an example, see this GitHub action used by
cargo hakari commands take a
--quiet option to suppress output, though showing diff
output in CI is often useful.
The commands in this section provide information about components in the workspace-hack.
Print out information about why a dependency is present in the workspace-hack:
cargo hakari explain <dependency-name>
cargo hakari verify
If some dependencies are built with more than one feature set, this command will print out details about them. This is always a bug—if you encounter it, a bug report with more information would be greatly appreciated!
If you publish crates to
crates.io or other registries, see the
Disable the workspace-hack crate temporarily by removing generated lines from
(Re-enable by running
cargo hakari generate.)
cargo hakari disable
Remove the workspace-hack crate as a dependency from all other workspace crates:
cargo hakari remove-deps
cargo hakari is configured through
.config/hakari.toml at the root of the workspace. Running
cargo hakari init causes a new file to be created at this location.
## The name of the package used for workspace-hack unification. hakari-package = "workspace-hack" ## Cargo resolver version in use -- version 2 is highly recommended. resolver = "2" ## Format for `workspace-hack = ...` lines in other Cargo.tomls. Version 2 requires cargo-hakari ## 0.9.8 or above. dep-format-version = "2" ## Add triples corresponding to platforms commonly used by developers here. ## https://doc.rust-lang.org/rustc/platform-support.html platforms = [ ## "x86_64-unknown-linux-gnu", ## "x86_64-apple-darwin", ## "x86_64-pc-windows-msvc", ] ## Write out exact versions rather than specifications. Set this to true if version numbers in ## `Cargo.toml` and `Cargo.lock` files are kept in sync, e.g. in some configurations of ## https://dependabot.com/. ## exact-versions = false
For more options, including how to exclude crates from the output, see the
cargo-hakari follows semantic versioning, where the public API is the command-line interface.
Within a given series, the command-line interface will be treated as append-only.
Cargo.toml will also be kept the same unless:
- a new config option is added, in which case the different output will be gated on the new option, or
- there is a bugfix involved.