cargo-hakari

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. Within Git repositories, cargo hakari init automatically does this for you. Here's how to do it manually. (Pull requests to improve this are welcome.)

Installation

All of the below commands take options that control their behavior.

To install, run:

sh cargo install cargo-hakari

To update, run:

sh cargo install --force cargo-hakari

If $HOME/.cargo/bin is in your PATH, the cargo hakari command will be available.

Usage

Getting started

There are three steps you must take for cargo hakari to work properly.

1. Initialize the workspace-hack

Initialize a workspace-hack crate for a workspace at path workspace-hack:

sh cargo hakari init workspace-hack

2. Generate the Cargo.toml

Generate or update the contents of a workspace-hack crate:

sh cargo hakari generate

3. Add dependencies to the workspace-hack

Add the workspace-hack crate as a dependency to all other workspace crates:

sh cargo hakari manage-deps

Making hakari work well

These are things that are not absolutely necessary to do, but will make cargo hakari work better.

1. Update the hakari config

Open up .config/hakari.toml, then:

• uncomment or add commonly-used developer platforms
• read the note about the resolver, and strongly consider setting resolver = "2" in your workspace's Cargo.toml.

Remember to run cargo hakari generate after changing the config.

2. Keep the workspace-hack up-to-date in CI

Run the following commands in CI:

sh 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.

Publishing a crate

If you publish crates to crates.io or other registries, see the publishing module.

Disabling and uninstalling

Disable the workspace-hack crate temporarily by removing generated lines from Cargo.toml. (Re-enable by running cargo hakari generate.)

sh cargo hakari disable

Remove the workspace-hack crate as a dependency from all other workspace crates:

sh cargo hakari remove-deps

Configuration

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.

Example configuration:

```toml

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 = [ # "x8664-unknown-linux-gnu", # "x8664-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 config module.

Stability guarantees

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. The generated 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.

Contributing

See the CONTRIBUTING file for how to help out.

License

This project is available under the terms of either the Apache 2.0 license or the MIT license.