cargo_hakari/docs/
patch_directive.rs

1// Copyright (c) The cargo-guppy Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Using a `[patch]` directive.
5//!
6//! To work effectively, `cargo hakari` requires that all the other crates in your workspace depend
7//! on it. This is done by adding a `workspace-hack` dependency to each crate's `Cargo.toml` file, a
8//! process that can be automated by running `cargo hakari manage-deps` locally.
9//!
10//! By default, the `workspace-hack` dependency are added like this:
11//!
12//! ```toml
13//! [dependencies]
14//! my-workspace-hack = { path = "../workspace-hack", version = "0.1.0" }
15//! ```
16//!
17//! This is the simplest way to get started with `cargo hakari`. However, it has a significant
18//! limitation: if other projects depend on your code as a path or Git dependency, they will pull in
19//! all the dependencies from your local workspace-hack crate. This is typically undesirable.
20//!
21//! To avoid this outcome, hakari allows you to use a `[patch]` directive. This page outlines the
22//! steps to do so.
23//!
24//! ## 1. Publish a stub crate to crates.io
25//!
26//! If you haven't already done so, follow the instructions in the [publishing
27//! section](crate::publishing) section to publish a uniquely-named stub crate to crates.io. This
28//! needs to only be done once.
29//!
30//! ## 2. Refer to the stub crate by default
31//!
32//! After this step, the workspace-hack dependency will be updated to refer to the stub crate on
33//! crates.io. (We will restore use of the real workspace-hack in step 3.)
34//!
35//! To do this, add a `workspace-hack-line-style` option to `.config/hakari.toml`. There are two
36//! options, both of which are equivalent from hakari's perspective.
37//!
38//! ### A. `"version-only"`
39//!
40//! This option is the closest to the default.
41//!
42//! Update `hakari.toml` with:
43//!
44//! ```toml
45//! workspace-hack-line-style = "version-only"
46//! ```
47//!
48//! Then, run:
49//!
50//! ```sh
51//! cargo hakari remove-deps
52//! cargo hakari manage-deps
53//! ```
54//!
55//! This will cause the workspace-hack lines to be updated to be similar to:
56//!
57//! ```toml
58//! [dependencies]
59//! my-workspace-hack = { version = "0.1.0" }
60//! ```
61//!
62//! ### B. `"workspace-dotted"`
63//!
64//! This option lets you specify the path to the workspace-hack crate, once, in the root
65//! `Cargo.toml`. You may prefer this if you've standardized on this format in your workspace.
66//!  
67//! Update `hakari.toml` with:
68//!
69//! ```toml
70//! workspace-hack-line-style = "workspace-dotted"
71//! ```
72//!
73//! Also, add the following to your root `Cargo.toml`:
74//!
75//! ```toml
76//! [workspace.dependencies]
77//! my-workspace-hack = "0.1.0"  # or another version number if you've changed it
78//! ```
79//!
80//! Then, run
81//!
82//! ```sh
83//! cargo hakari remove-deps
84//! cargo hakari manage-deps
85//! ```
86//!
87//! This will cause the workspace-hack lines to be updated to be similar to:
88//!
89//! ```toml
90//! [dependencies]
91//! my-workspace-hack.workspace = true
92//! ```
93//!
94//! ## 3. Add a `[patch]` directive to the root `Cargo.toml`
95//!
96//! To the workspace's root `Cargo.toml`, add a `[patch]` directive that points to the local
97//! dependency:
98//!
99//! ```toml
100//! [patch.crates-io.my-workspace-hack]
101//! path = "workspace-hack"
102//! ```
103//!
104//! This ensures that while building within the workspace, the real workspace-hack is used. When
105//! building outside of the workspace, such as via a Git or path dependency, the `[patch]` directive
106//! is inactive, and the stub crate from crates.io is used.
107//!
108//! # Example
109//!
110//! The guppy workspace itself uses a `[patch]` directive with `"workspace-dotted"`. Here's [the
111//! root `Cargo.toml`](https://github.com/guppy-rs/guppy/blob/main/Cargo.toml), and a [crate
112//! `Cargo.toml`](https://github.com/guppy-rs/guppy/blob/main/guppy-summaries/Cargo.toml).
cargo_hakari/docs/patch_directive.rs

cargo_hakari/docs/
patch_directive.rs
