Module cargo_hakari::patch_directive

Using a [patch] directive.

To work effectively, cargo hakari requires that all the other crates in your workspace depend on it. This is done by adding a workspace-hack dependency to each crate’s Cargo.toml file, a process that can be automated by running cargo hakari manage-deps locally.

By default, the workspace-hack dependency are added like this:

[dependencies]
my-workspace-hack = { path = "../workspace-hack", version = "0.1.0" }

This is the simplest way to get started with cargo hakari. However, it has a significant limitation: if other projects depend on your code as a path or Git dependency, they will pull in all the dependencies from your local workspace-hack crate. This is typically undesirable.

To avoid this outcome, hakari allows you to use a [patch] directive. This page outlines the steps to do so.

1. Publish a stub crate to crates.io

If you haven’t already done so, follow the instructions in the publishing section section to publish a uniquely-named stub crate to crates.io. This needs to only be done once.

2. Refer to the stub crate by default

After this step, the workspace-hack dependency will be updated to refer to the stub crate on crates.io. (We will restore use of the real workspace-hack in step 3.)

To do this, add a workspace-hack-line-style option to .config/hakari.toml. There are two options, both of which are equivalent from hakari’s perspective.

A. "version-only"

This option is the closest to the default.

Update hakari.toml with:

workspace-hack-line-style = "version-only"

Then, run:

cargo hakari remove-deps
cargo hakari manage-deps

This will cause the workspace-hack lines to be updated to be similar to:

[dependencies]
my-workspace-hack = { version = "0.1.0" }

B. "workspace-dotted"

This option lets you specify the path to the workspace-hack crate, once, in the root Cargo.toml. You may prefer this if you’ve standardized on this format in your workspace.

Update hakari.toml with:

workspace-hack-line-style = "workspace-dotted"

Also, add the following to your root Cargo.toml:

[workspace.dependencies]
my-workspace-hack = "0.1.0"  # or another version number if you've changed it

Then, run

cargo hakari remove-deps
cargo hakari manage-deps

This will cause the workspace-hack lines to be updated to be similar to:

[dependencies]
my-workspace-hack.workspace = true

3. Add a [patch] directive to the root Cargo.toml

To the workspace’s root Cargo.toml, add a [patch] directive that points to the local dependency:

[patch.crates-io.my-workspace-hack]
path = "workspace-hack"

This ensures that while building within the workspace, the real workspace-hack is used. When building outside of the workspace, such as via a Git or path dependency, the [patch] directive is inactive, and the stub crate from crates.io is used.

Example

The guppy workspace itself uses a [patch] directive with "workspace-dotted". Here’s the root Cargo.toml, and a crate Cargo.toml.