Skip to main content

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}