Crate cargo_hakari[−][src]
Expand description
cargo hakari
is a command-line application to manage workspace-hack crates. Use it to speed up
local 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
the about
module.
Examples
The cargo-guppy
repository uses a workspace-hack crate managed by cargo hakari
. See the
generated Cargo.toml
.
Platform support
- 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
– it is recommended that repositories disable automatic line ending conversion. Here’s how to do it in Git. (Pull requests to improve this are welcome.)
Installation and usage
All of the below commands take options that control their behavior.
To install, run:
cargo install cargo-hakari
To update, run:
cargo install --force cargo-hakari
If $HOME/.cargo/bin
is in your PATH
, the cargo hakari
command will be available.
Usage
Initialize a workspace-hack crate for a workspace at path my-workspace-hack
:
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
Publish a crate that currently depends on the workspace-hack crate (cargo publish
can’t be
used in this circumstance):
cargo hakari publish -p <crate>
Keeping the workspace-hack crate up-to-date
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-guppy
.
All cargo hakari
commands take a --quiet
option to suppress output, though showing diff
output in CI is often useful.
Disabling and uninstalling
Disable the workspace-hack crate temporarily by removing generated contents. (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
Configuration
cargo hakari
is configured through .guppy/hakari.toml
at the root of the workspace.
Example configuration:
# 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"
# 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",
]
# Options to control Hakari output.
[output]
# 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
config
module.