cargo_hakari/docs/publishing.rs
1// Copyright (c) The cargo-guppy Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Publishing a package to `crates.io` or other registries.
5//!
6//! *This section can be ignored if your workspace doesn't publish any crates to registries.*
7//!
8//! Many projects using `cargo hakari` may wish to publish their crates to `crates.io` or other
9//! registries. However, if you attempt to publish a crate from a Hakari-managed workspace, `cargo
10//! publish` may reject it for containing the local-only workspace-hack dependency.
11//!
12//! `cargo hakari` provides two ways to handle this.
13//!
14//! # A. Temporarily remove the workspace-hack dependency before publishing
15//!
16//! Simply run:
17//!
18//! ```sh
19//! cargo hakari publish -p <crate>
20//! ```
21//!
22//! This command temporarily removes the dependency on the `workspace-hack` before publishing the
23//! crate. The dependency will be re-added afterwards, unless the command is interrupted with ctrl-C
24//! (in which case you can use `cargo hakari manage-deps` to finish the job.)
25//!
26//! This works out of the box. However, it has the downside of requiring `cargo hakari publish`. If
27//! you don't have control over the commands run while publishing the package, it won't be possible
28//! to use this method.
29//!
30//! # B. Publish your own workspace-hack crate to the registry
31//!
32//! This method preserves workspace-hack dependencies in `Cargo.toml`s by targeting a stub crate on
33//! the registry.
34//!
35//! ## 1. Ensure the local crate is unique on the registry
36//!
37//! Rename it to something unique if necessary.
38//!
39//! > **TIP:** On Unix platforms, to rename `workspace-hack` to `my-workspace-hack` in other
40//! > `Cargo.toml` files: run this from the root of the workspace:
41//! >
42//! > ```sh
43//! > git ls-files | grep Cargo.toml | xargs perl -p -i -e 's/^workspace-hack = /my-workspace-hack = /'
44//! > ```
45//! >
46//! > If not in the context of a Git repository, run:
47//! >
48//! > ```sh
49//! > find . -name Cargo.toml | xargs perl -p -i -e 's/^workspace-hack = /my-workspace-hack = /'`
50//! > ```
51//!
52//! Remember to update `.config/hakari.toml` (or `.guppy/hakari.toml`) with the new name.
53//!
54//! The rest of this section assumes the crate is called `my-workspace-hack`.
55//!
56//! ## 2. Ensure that workspace-hack dependencies have a version set
57//!
58//! Depending on how workspace-hack dependencies are set up:
59//!
60//! ### i. Using `workspace-dotted`
61//!
62//! If you're using [the `workspace-dotted` line
63//! style](crate::docs::config#workspace-hack-line-style), ensure that the `workspace-hack` line in
64//! the root `Cargo.toml` has a `version` field set.
65//!
66//! ```toml
67//! [workspace.dependencies]
68//! my-workspace-hack = { version = "0.1", path = "..." }
69//! ```
70//!
71//! ### ii. Specifying dependencies directly
72//!
73//! If you're using a different line style, ensure that [the latest
74//! `dep-format-version`](crate::docs::config#dep-format-version) is set in `.config/hakari.toml`.
75//!
76//! `dep-format-version = "2"` and higher add the `version` field to the `my-workspace-hack = ...`
77//! lines in other `Cargo.toml` files. `cargo publish` uses the `version` field to recognize
78//! published dependencies.
79//!
80//! This option is new in cargo-hakari 0.9.8. Configuration files created by older versions of
81//! cargo-hakari may not have this option set.
82//!
83//! Ensure that this option is present in `.config/hakari.toml` and is set to the latest version.
84//! See the [config](crate::config) section for more details.
85//!
86//! Then run `cargo hakari manage-deps` to update the `workspace-hack = ...` lines.
87//!
88//! ---
89//!
90//! After performing the above actions, simply run `cargo publish` as usual to publish the crate.
91//!
92//! ## 3. Set options in the workspace-hack's `Cargo.toml`
93//!
94//! In `my-workspace-hack`'s `Cargo.toml` file, set the `package.publish` option to anything other
95//! than `false`. This enables its publication.
96//!
97//! ```toml
98//! [package]
99//! publish = true # to allow publishing to any registry
100//! ## or
101//! publish = ["crates-io"] # to allow publishing to crates.io only
102//! ```
103//!
104//! While you're here, you may also wish to set other options like `repository` or `homepage`.
105//!
106//! ## 4. Temporarily disable the workspace-hack crate
107//!
108//! **This step is really important.** Not doing it will cause the full dependency set in the
109//! workspace-hack to be published, which is not what you want.
110//!
111//! Run `cargo hakari disable` to disable the workspace-hack crate`.
112//!
113//! ## 5. Publish the stub workspace-hack crate
114//!
115//! Run `cargo publish -p my-workspace-hack --allow-dirty` to publish the crate to `crates.io`. For
116//! other registries, use the `--registry` flag.
117//!
118//! ## 6. Re-enable the workspace-hack crate
119//!
120//! Run `cargo hakari generate` to restore the workspace-hack's contents. You can also use your
121//! source control system's commands to do so, such as with `git restore`.
122//!
123//! ## 7. Consider using a `[patch]` directive
124//!
125//! To allow Cargo workspaces that depend on a Git or path dependency to use the published
126//! workspace-hack, consider using a `[patch]` directive. Steps to do so are described in the [patch
127//! directive](crate::docs::patch_directive) section.