crate_plugin_kit/install/build_host/mod.rs
1//! build-host: generates a wrapper project, `cargo build`s a cdylib out of it, and
2//! copies that into the install dir.
3//!
4//! # Why a wrapper is needed
5//!
6//! `cargo install` only knows about bin targets, so a `crate-type = ["cdylib"]` crate
7//! cannot be installed that way. And `cargo build` on a plugin crate directly does
8//! not make Cargo produce a cdylib for a dependency either.
9//!
10//! So a wrapper project of a few dozen lines is generated. The generator itself lives in
11//! the private `wrapper` module, because [`crate::pack`] — the release-asset path — builds
12//! the exact same wrapper from a local checkout:
13//!
14//! ```text
15//! <build>/<crate>/
16//! ├── Cargo.toml # [lib] crate-type = ["cdylib"], depends on the plugin and the host contract crate
17//! ├── src/lib.rs # one line: <contract>::export!(<plugin_crate>::create);
18//! └── target/ # cargo's build cache, kept between installs -- see `reset_wrapper`
19//! ```
20//!
21//! The benefit is that the plugin's own crate stays a plain rlib: crates.io consumes
22//! it normally, unit tests can `use` it directly, and the plugin author does not have
23//! to write a single `#[no_mangle]`.
24//!
25//! # Where the manifest comes from
26//!
27//! The plugin crate's source root holds a copy of `<manifest_name>`. `cargo metadata`
28//! is used here to locate the crate source dir, and the file is copied verbatim into
29//! the install dir — see the module docs of [`crate::manifest`].
30//!
31//! # Layout
32//!
33//! [`install`] is the whole flow. `metadata` holds the `cargo metadata` parsing, and
34//! `probe_contract_requirement` below is the one step that has to run *before* the
35//! wrapper exists.
36//!
37//! The two generated files are rewritten on every install; the target directory beside
38//! them is not. That asymmetry is deliberate and load-bearing — `reset_wrapper` says why.
39
40use std::path::{Path, PathBuf};
41use std::process::Command;
42
43use crate::cache::InstallSource;
44use crate::config::{KitConfig, KitPaths};
45use crate::error::{KitError, KitResult};
46use crate::install::{remove_dir_if_exists, Installed};
47use crate::loader;
48use crate::wrapper::{self, cargo_metadata_json, declared_contract_dep, ContractDep, PluginSource};
49
50mod metadata;
51
52use metadata::cargo_metadata;
53
54/// Where the plugin crate being installed comes from.
55///
56/// The two shapes differ in exactly three places — the dependency the probe asks cargo
57/// about, the source the wrapper is written for, and what the install record says
58/// afterwards. Everything else (the wrapper, the build, finding the artifact, landing the
59/// cdylib and the manifest) is [`install_with`], so an install from a directory cannot
60/// drift from an install from crates.io.
61enum Spec<'a> {
62 /// A published crate, pinned exactly: the version recorded must be the version built.
63 Registry {
64 crate_name: &'a str,
65 version: &'a str,
66 },
67 /// A checkout on this machine, with its manifest beside its `Cargo.toml`.
68 Local {
69 crate_name: &'a str,
70 version: &'a str,
71 dir: &'a Path,
72 },
73}
74
75impl Spec<'_> {
76 fn crate_name(&self) -> &str {
77 match self {
78 Spec::Registry { crate_name, .. } | Spec::Local { crate_name, .. } => crate_name,
79 }
80 }
81
82 fn version(&self) -> &str {
83 match self {
84 Spec::Registry { version, .. } | Spec::Local { version, .. } => version,
85 }
86 }
87
88 /// The dependency line the probe manifest needs to reach the plugin crate.
89 ///
90 /// A literal TOML string for the path: a Windows path is full of backslashes, and a
91 /// basic string would read them as escapes.
92 fn probe_dependency(&self) -> String {
93 match self {
94 Spec::Registry {
95 crate_name,
96 version,
97 } => format!("{crate_name} = \"={version}\""),
98 Spec::Local {
99 crate_name, dir, ..
100 } => {
101 format!("{crate_name} = {{ path = '{}' }}", dir.display())
102 }
103 }
104 }
105
106 fn plugin_source(&self) -> PluginSource<'_> {
107 match self {
108 Spec::Registry { version, .. } => PluginSource::Registry { version },
109 Spec::Local { dir, .. } => PluginSource::Path { dir },
110 }
111 }
112
113 /// How the install record describes it. A published crate built on this machine is
114 /// `BuildHost`; a checkout is `Local`, with the directory kept for `update`.
115 fn install_source(&self) -> InstallSource {
116 match self {
117 Spec::Registry { .. } => InstallSource::BuildHost,
118 Spec::Local { dir, .. } => InstallSource::Local {
119 path: dir.to_path_buf(),
120 },
121 }
122 }
123
124 /// The directory the plugin's manifest is copied from.
125 ///
126 /// A checkout knows it; a published crate has to be asked of cargo, which resolved it
127 /// into the registry source directory.
128 fn manifest_source<'a>(&'a self, from_cargo: Option<&'a Path>) -> Option<&'a Path> {
129 match self {
130 Spec::Local { dir, .. } => Some(dir),
131 Spec::Registry { .. } => from_cargo,
132 }
133 }
134}
135
136/// Installs a plugin through build-host.
137///
138/// `version` must be a concrete version number (the caller looks up the latest one on
139/// crates.io first).
140pub fn install(
141 cfg: &KitConfig,
142 paths: &KitPaths,
143 crate_name: &str,
144 version: &str,
145) -> KitResult<Installed> {
146 install_with(
147 cfg,
148 paths,
149 &Spec::Registry {
150 crate_name,
151 version,
152 },
153 )
154}
155
156/// Installs a plugin from a checkout on this machine.
157///
158/// `crate_name` and `version` are what the checkout's own manifest declares; the build is
159/// the same one a published plugin gets.
160pub fn install_from_path(
161 cfg: &KitConfig,
162 paths: &KitPaths,
163 crate_name: &str,
164 version: &str,
165 dir: &Path,
166) -> KitResult<Installed> {
167 install_with(
168 cfg,
169 paths,
170 &Spec::Local {
171 crate_name,
172 version,
173 dir,
174 },
175 )
176}
177
178/// The install itself: one implementation for both sources.
179fn install_with(cfg: &KitConfig, paths: &KitPaths, spec: &Spec<'_>) -> KitResult<Installed> {
180 let crate_name = spec.crate_name();
181 let cargo = which::which("cargo").map_err(|_| KitError::CargoNotFound)?;
182
183 let wrapper_dir = paths.build_dir(crate_name);
184 reset_wrapper(&wrapper_dir)?;
185 std::fs::create_dir_all(wrapper_dir.join("src"))?;
186
187 let stem = cfg.lib_stem(crate_name);
188
189 // Ask the plugin crate what it declares about the contract crate, and have the wrapper ask
190 // for exactly the same thing. Getting this wrong is not cosmetic: the private `wrapper`
191 // module explains what two disagreeing requirements do to the build.
192 let probe_dir = paths.build_dir(&format!("{crate_name}-probe"));
193 let contract = probe_contract_requirement(cfg, &cargo, &probe_dir, spec)?;
194 remove_dir_if_exists(&probe_dir)?;
195
196 wrapper::write(
197 cfg,
198 &wrapper_dir,
199 crate_name,
200 &stem,
201 spec.plugin_source(),
202 contract.as_ref(),
203 )?;
204
205 let manifest_path = wrapper_dir.join("Cargo.toml");
206
207 // 1. metadata: resolve and download dependencies, and pick up the target
208 // directory and the plugin source dir along the way
209 let metadata = cargo_metadata(&cargo, &manifest_path)?;
210 let target_dir = metadata.target_directory.clone();
211 let plugin_src = metadata.plugin_source_dir(crate_name);
212
213 // 2. the actual compile. stdio is inherited — this can take minutes and the user
214 // has to be able to watch it.
215 let status = Command::new(&cargo)
216 .arg("build")
217 .arg("--release")
218 .arg("--manifest-path")
219 .arg(&manifest_path)
220 .status()
221 .map_err(KitError::Io)?;
222
223 if !status.success() {
224 return Err(KitError::BuildFailed {
225 code: status.code(),
226 });
227 }
228
229 // 3. find the artifact
230 let release_dir = target_dir.join("release");
231 let built =
232 loader::find_library(&release_dir, &stem).map_err(|_| KitError::BuildArtifactMissing {
233 stem: stem.clone(),
234 dir: release_dir.display().to_string(),
235 })?;
236
237 // 4. land it: cdylib + manifest
238 let plugin_dir = paths.plugin_dir(crate_name);
239 remove_dir_if_exists(&plugin_dir)?;
240 std::fs::create_dir_all(&plugin_dir)?;
241
242 let dest_lib = plugin_dir.join(
243 built
244 .file_name()
245 .expect("an artifact always has a file name"),
246 );
247 std::fs::copy(&built, &dest_lib)?;
248
249 copy_manifest(cfg, &plugin_dir, spec.manifest_source(plugin_src))?;
250
251 Ok(Installed {
252 crate_name: crate_name.to_string(),
253 version: spec.version().to_string(),
254 dir: plugin_dir,
255 library: dest_lib,
256 source: spec.install_source(),
257 })
258}
259
260// ---- the wrapper directory ------------------------------------------------
261
262/// Clears the wrapper project, keeping the cargo target directory inside it.
263///
264/// The wrapper is regenerated from scratch on every install, so its two generated files must
265/// never survive from a previous run — a `Cargo.toml` still naming a plugin that has since been
266/// removed would be built instead of the one being installed. What must survive is `target/`:
267/// cargo puts its build cache there (the wrapper is its own single-element workspace, so there
268/// is no workspace above it to place one), and deleting it makes every install recompile the
269/// whole plugin stack — the plugin, the contract crate and every dependency of both. That is
270/// the difference between an update that finishes in milliseconds and one that takes minutes.
271///
272/// So this removes the wrapper's *source*, not the wrapper: the files `wrapper::write` is about
273/// to overwrite, plus anything a previous version of the kit might have left in an unexpected
274/// place. `target` is the only thing named, because it is the only thing that has to be.
275fn reset_wrapper(dir: &Path) -> KitResult<()> {
276 if !dir.is_dir() {
277 return Ok(());
278 }
279
280 for entry in std::fs::read_dir(dir)? {
281 let entry = entry?;
282 if entry.file_name() == "target" {
283 continue;
284 }
285 remove_entry(&entry.path())?;
286 }
287
288 Ok(())
289}
290
291/// Removes one file or directory tree.
292fn remove_entry(path: &Path) -> KitResult<()> {
293 if path.is_dir() {
294 std::fs::remove_dir_all(path)?;
295 } else {
296 std::fs::remove_file(path)?;
297 }
298 Ok(())
299}
300
301// ---- wrapper generation ---------------------------------------------------
302//
303// The generated files live in the private `wrapper` module, because `crate::pack` builds the
304// same wrapper from a local checkout. What stays here is the part that is specific to
305// installing from a registry: asking cargo what the *published* crate declares.
306
307/// Copies the manifest from the plugin source dir into the install dir.
308fn copy_manifest(cfg: &KitConfig, plugin_dir: &Path, plugin_src: Option<&Path>) -> KitResult<()> {
309 let Some(src_dir) = plugin_src else {
310 return Err(KitError::ManifestMissingField {
311 field: cfg.manifest_name.clone(),
312 path: PathBuf::from("<plugin source dir not located>"),
313 });
314 };
315
316 let src = src_dir.join(&cfg.manifest_name);
317 if !src.is_file() {
318 return Err(KitError::ManifestMissingField {
319 field: cfg.manifest_name.clone(),
320 path: src,
321 });
322 }
323
324 std::fs::copy(&src, plugin_dir.join(&cfg.manifest_name))?;
325 Ok(())
326}
327
328/// Ask cargo what the plugin crate declares about the contract crate.
329///
330/// Needs its own throwaway manifest, because the answer is needed *before* the wrapper's
331/// manifest can be written -- and it cannot be read off the wrapper, since the wrapper is where
332/// the question comes from in the first place.
333fn probe_contract_requirement(
334 cfg: &KitConfig,
335 cargo: &Path,
336 dir: &Path,
337 spec: &Spec<'_>,
338) -> KitResult<Option<ContractDep>> {
339 std::fs::create_dir_all(dir.join("src"))?;
340 // Its own workspace, so the wrapper's Cargo.toml above it does not claim it.
341 std::fs::write(
342 dir.join("Cargo.toml"),
343 format!(
344 "[package]\nname = \"probe\"\nversion = \"0.0.0\"\nedition = \"2021\"\npublish = false\n\n\
345 [workspace]\n\n[dependencies]\n{}\n",
346 spec.probe_dependency()
347 ),
348 )?;
349 std::fs::write(dir.join("src").join("lib.rs"), "")?;
350
351 let v = cargo_metadata_json(cargo, &dir.join("Cargo.toml"))?;
352 Ok(declared_contract_dep(
353 &v,
354 spec.crate_name(),
355 &cfg.contract_crate,
356 ))
357}
358
359#[cfg(test)]
360mod tests {
361 use super::*;
362
363 /// The whole point of [`reset_wrapper`]: the generated files go, cargo's cache stays.
364 ///
365 /// If `target/` is removed here, every install — `plugin add` as much as `plugin update` —
366 /// recompiles the plugin and its entire dependency graph from scratch. That failure is
367 /// invisible: the install still succeeds, it is just slow. So it is asserted here, where it
368 /// costs a second, instead of being noticed as "why does this take minutes again".
369 #[test]
370 fn reset_wrapper_keeps_the_target_directory() {
371 let tmp = tempfile::tempdir().unwrap();
372 let dir = tmp.path().join("myapp-plugin-foo");
373 std::fs::create_dir_all(dir.join("src")).unwrap();
374 std::fs::create_dir_all(dir.join("target").join("release")).unwrap();
375
376 std::fs::write(dir.join("Cargo.toml"), "# stale\n").unwrap();
377 std::fs::write(dir.join("src").join("lib.rs"), "// stale\n").unwrap();
378 std::fs::write(dir.join("target").join("release").join("cached"), "x").unwrap();
379
380 reset_wrapper(&dir).unwrap();
381
382 assert!(
383 !dir.join("Cargo.toml").exists() && !dir.join("src").exists(),
384 "a stale generated file must not survive into the next build"
385 );
386 assert!(
387 dir.join("target").join("release").join("cached").is_file(),
388 "cargo's cache is what makes an update cheap"
389 );
390 }
391
392 /// A wrapper directory that is not there yet is not an error: a first install creates it.
393 #[test]
394 fn reset_wrapper_accepts_a_missing_directory() {
395 let tmp = tempfile::tempdir().unwrap();
396
397 reset_wrapper(&tmp.path().join("never-built")).unwrap();
398 }
399}