Skip to main content

get_cargo_lock/
lib.rs

1//! Obtain the exact `Cargo.lock` used by the workspace that consumes a reusable
2//! external crate.
3//!
4//! For a build script belonging to a crate in a workspace,
5//! [`project-root`](https://crates.io/crates/project-root) is sufficient: it
6//! finds the workspace root, and the workspace's `Cargo.lock` follows from that
7//! path. This does not work for a crate developed separately and reused by
8//! multiple projects. Cargo builds its crates.io dependency from its cache,
9//! outside the consuming workspace, so searching upward would inspect the
10//! wrong directory.
11//!
12//! `get-cargo-lock` addresses that boundary. The published crate deliberately
13//! does not search: [`get_cargo_lock`] panics with setup instructions until the
14//! workspace owner activates a workspace-local proxy.
15//!
16//! # Use from an external crate
17//!
18//! Add this crate as a build dependency and call [`get_cargo_lock`] from the
19//! crate's `build.rs`:
20//!
21//! ```toml
22//! [build-dependencies]
23//! get-cargo-lock = "0.1"
24//! ```
25//!
26//! ```no_run
27//! let lockfile = get_cargo_lock::get_cargo_lock();
28//! println!("cargo:rerun-if-changed={}", lockfile.display());
29//! // Use lockfile for reflection or a nested Cargo invocation.
30//! ```
31//!
32//! # Configure the consuming workspace
33//!
34//! The workspace owner performs this setup once:
35//!
36//! ```text
37//! cargo install get-cargo-lock
38//! cargo get-cargo-lock install .
39//! cargo check
40//! ```
41//!
42//! The installer creates a `get-cargo-lock` package in the workspace, adds it
43//! to `workspace.members`, and adds this override:
44//!
45//! ```toml
46//! [patch.crates-io]
47//! get-cargo-lock = { path = "get-cargo-lock" }
48//! ```
49//!
50//! Cargo then compiles the injected package in place of the crates.io
51//! dependency. It exposes the same [`get_cargo_lock`] API, but its build script
52//! can find the workspace's `Cargo.lock` because the package is inside that
53//! workspace. The installer enables this behavior by removing a blocking file;
54//! it does not modify copied Rust sources. Re-running the command safely
55//! refreshes a proxy created by this tool.
56//!
57//! The command accepts a workspace directory, its `Cargo.toml`, or a standalone
58//! package. A standalone package is converted to a workspace containing itself
59//! and the proxy. The installer refuses to overwrite an unrecognized
60//! `get-cargo-lock` directory.
61
62#![forbid(unsafe_code)]
63
64use std::path::PathBuf;
65
66/// Returns the consuming workspace's `Cargo.lock`.
67///
68/// # Panics
69///
70/// The registry version always panics. The consuming workspace must patch it
71/// to the proxy generated by `cargo get-cargo-lock install <workspace>`.
72///
73/// ```no_run
74/// let lockfile = get_cargo_lock::get_cargo_lock();
75/// println!("cargo:rerun-if-changed={}", lockfile.display());
76/// ```
77#[cfg(not(get_cargo_lock_enabled))]
78#[must_use]
79pub fn get_cargo_lock() -> PathBuf {
80    panic!(
81        "get-cargo-lock cannot inspect the consuming workspace while its dependency source is in Cargo's cache. Install and activate the workspace proxy:\n\
82         cargo install get-cargo-lock\n\
83         cargo get-cargo-lock install <workspace>"
84    )
85}
86
87/// Returns the consuming workspace's `Cargo.lock`.
88///
89/// The path is determined when the injected workspace proxy is built.
90#[cfg(get_cargo_lock_enabled)]
91#[must_use]
92pub fn get_cargo_lock() -> PathBuf {
93    PathBuf::from(env!("GET_CARGO_LOCK_PATH"))
94}
95
96#[cfg(test)]
97mod tests {
98    #[test]
99    #[cfg(not(get_cargo_lock_enabled))]
100    #[should_panic(expected = "cargo get-cargo-lock install <workspace>")]
101    fn registry_library_explains_required_setup() {
102        let _ = super::get_cargo_lock();
103    }
104}