1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

// Copyright (c) The cargo-guppy Contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! 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:
//!
//! ```toml
//! [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](crate::publishing) 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:
//!
//! ```toml
//! workspace-hack-line-style = "version-only"
//! ```
//!
//! Then, run:
//!
//! ```sh
//! cargo hakari remove-deps
//! cargo hakari manage-deps
//! ```
//!
//! This will cause the workspace-hack lines to be updated to be similar to:
//!
//! ```toml
//! [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:
//!
//! ```toml
//! workspace-hack-line-style = "workspace-dotted"
//! ```
//!
//! Also, add the following to your root `Cargo.toml`:
//!
//! ```toml
//! [workspace.dependencies]
//! my-workspace-hack = "0.1.0"  # or another version number if you've changed it
//! ```
//!
//! Then, run
//!
//! ```sh
//! cargo hakari remove-deps
//! cargo hakari manage-deps
//! ```
//!
//! This will cause the workspace-hack lines to be updated to be similar to:
//!
//! ```toml
//! [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:
//!
//! ```toml
//! [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`](https://github.com/guppy-rs/guppy/blob/main/Cargo.toml), and a [crate
//! `Cargo.toml`](https://github.com/guppy-rs/guppy/blob/main/guppy-summaries/Cargo.toml).