Skip to main content

crate_plugin_kit/
pack.rs

1//! Producing the two files a plugin release carries.
2//!
3//! This is the mirror image of [`crate::install`]: instead of turning a published crate
4//! into a cdylib on the user's machine, it turns a checkout into the assets that let
5//! [`crate::install::prebuilt`] skip the build entirely.
6//!
7//! ```text
8//! {crate}-{version}-{target}.{so|dylib|dll}   <-- the cdylib
9//! {crate}-{version}-{target}.toml             <-- the plugin manifest, verbatim
10//! ```
11//!
12//! # Why these names
13//!
14//! [`crate::install::prebuilt`] builds its download URL by putting these two names after
15//! `.../releases/download/v{version}/`. Producing and consuming are one convention:
16//! change either side alone and every release silently falls back to building from
17//! source. Nothing here may be renamed without renaming it there too.
18//!
19//! # What it does
20//!
21//! 1. `cargo metadata` the plugin's manifest, for the crate name and version.
22//! 2. Check that the plugin manifest beside it declares the same version — a manifest
23//!    that lags behind `Cargo.toml` would publish assets nobody can consume.
24//! 3. Generate the wrapper — the same one [`crate::install`] builds, coming from the
25//!    private `wrapper` module — with the plugin as a **path** dependency, and
26//!    `cargo build --release --target <triple>` it.
27//! 4. Copy the cdylib and the plugin manifest into the output directory under the names
28//!    above, and — when the build target is this machine — `dlopen` the result to prove
29//!    it really exports the entry symbol.
30//!
31//! A failed build leaves the generated wrapper in the temp directory, which is where
32//! someone looks to see why; a successful one removes it again.
33
34use std::path::{Path, PathBuf};
35use std::process::Command;
36use std::sync::atomic::{AtomicU64, Ordering};
37
38use crate::config::KitConfig;
39use crate::error::{KitError, KitResult};
40use crate::install::remove_dir_if_exists;
41use crate::manifest::PluginManifest;
42use crate::wrapper::{self, cargo_metadata_json, declared_contract_dep, PluginSource};
43
44/// Options for [`build`].
45#[derive(Debug, Clone)]
46pub struct PackOptions {
47    /// Where cargo puts its build.
48    ///
49    /// `None` uses `<plugin dir>/target`, which is the directory a CI cache action
50    /// normally keeps — so the dependency builds are cached between releases.
51    pub target_dir: Option<PathBuf>,
52
53    /// `dlopen` the finished cdylib and look for the entry symbol.
54    ///
55    /// Defaults to `true`. It only happens when the build target is the machine doing
56    /// the packing: a cross-compiled artifact cannot be loaded here, so that case is
57    /// skipped silently rather than reported as a failure.
58    pub verify_export: bool,
59}
60
61impl Default for PackOptions {
62    fn default() -> Self {
63        Self {
64            target_dir: None,
65            verify_export: true,
66        }
67    }
68}
69
70/// The two files that were written.
71#[derive(Debug, Clone, PartialEq, Eq)]
72pub struct PackedAssets {
73    /// Full crate name, such as `bmux-plugin-cargo`.
74    pub crate_name: String,
75    /// The crate's own version.
76    pub version: String,
77    /// Target triple the cdylib was built for.
78    pub target: String,
79    /// Path of the written cdylib.
80    pub library: PathBuf,
81    /// Path of the written manifest.
82    pub manifest: PathBuf,
83}
84
85impl PackedAssets {
86    /// The base name both files share: `{crate}-{version}-{target}`.
87    pub fn base_name(&self) -> String {
88        format!("{}-{}-{}", self.crate_name, self.version, self.target)
89    }
90}
91
92/// Builds a plugin checkout into the two files a release carries.
93///
94/// `cfg` supplies the naming rules (it is the same [`KitConfig`] the host installs
95/// with); `plugin_dir` is the root of the plugin crate; `out_dir` is created if needed.
96///
97/// # Errors
98///
99/// - [`KitError::CargoNotFound`]: no `cargo` on `PATH`;
100/// - [`KitError::NoManifest`]: no `Cargo.toml` in `plugin_dir`;
101/// - [`KitError::NoPackage`]: `cargo metadata` did not describe that manifest;
102/// - [`KitError::ManifestMissingField`] / [`KitError::ManifestParse`]: the plugin
103///   manifest is missing or unreadable;
104/// - [`KitError::VersionMismatch`]: the plugin manifest and `Cargo.toml` disagree;
105/// - [`KitError::BuildFailed`] / [`KitError::BuildArtifactMissing`]: the wrapper build
106///   failed or produced nothing loadable;
107/// - [`KitError::LibraryLoad`] / [`KitError::SymbolMissing`]: the artifact does not
108///   export the entry symbol, so publishing it would produce an unloadable plugin.
109pub fn build(
110    cfg: &KitConfig,
111    plugin_dir: impl AsRef<Path>,
112    out_dir: impl AsRef<Path>,
113    options: &PackOptions,
114) -> KitResult<PackedAssets> {
115    let cargo = which::which("cargo").map_err(|_| KitError::CargoNotFound)?;
116
117    let plugin_dir = plugin_dir.as_ref().canonicalize()?;
118    let manifest_path = plugin_dir.join("Cargo.toml");
119    if !manifest_path.is_file() {
120        return Err(KitError::NoManifest { dir: plugin_dir });
121    }
122
123    // 1. what the crate calls itself, and which version this is
124    let metadata = cargo_metadata_json(&cargo, &manifest_path)?;
125    let (crate_name, version) = wrapper::package_identity(&metadata, &manifest_path)?;
126
127    // 2. the manifest that travels with the cdylib has to agree with Cargo.toml.
128    //    A host reads the manifest before it downloads anything, and the asset file
129    //    name is built from the crate version; if the two disagree, one of them lies.
130    let plugin_manifest = plugin_dir.join(&cfg.manifest_name);
131    let manifest = PluginManifest::read(&plugin_manifest)?;
132    if manifest.plugin.version != version {
133        return Err(KitError::VersionMismatch {
134            path: plugin_manifest,
135            declared: manifest.plugin.version,
136            crate_version: version,
137        });
138    }
139
140    // 3. the wrapper, then the build
141    let target = cfg.effective_target().to_string();
142    let target_dir = options
143        .target_dir
144        .clone()
145        .unwrap_or_else(|| plugin_dir.join("target"));
146
147    // A directory of this run's own. Sharing one by crate name would mean two runs — two
148    // tests, or two pack calls in one program — deleting and writing the same files at
149    // once; on Windows deleting a directory another process still has open fails outright
150    // with "access denied".
151    let wrapper_dir = wrapper_dir(cfg, &crate_name);
152    std::fs::create_dir_all(wrapper_dir.join("src"))?;
153
154    let stem = cfg.lib_stem(&crate_name);
155    let contract = declared_contract_dep(&metadata, &crate_name, &cfg.contract_crate);
156    wrapper::write(
157        cfg,
158        &wrapper_dir,
159        &crate_name,
160        &stem,
161        PluginSource::Path { dir: &plugin_dir },
162        contract.as_ref(),
163    )?;
164
165    // stdio is inherited: this can take a while and the caller should see cargo's output
166    let status = Command::new(&cargo)
167        .arg("build")
168        .arg("--release")
169        .arg("--manifest-path")
170        .arg(wrapper_dir.join("Cargo.toml"))
171        .arg("--target")
172        .arg(&target)
173        .arg("--target-dir")
174        .arg(&target_dir)
175        .status()
176        .map_err(KitError::Io)?;
177
178    if !status.success() {
179        return Err(KitError::BuildFailed {
180            code: status.code(),
181        });
182    }
183
184    // 4. name it the way `prebuilt` looks for it
185    let release_dir = target_dir.join(&target).join("release");
186    let built =
187        crate::loader::find_library_for_target(&release_dir, &stem, &target).map_err(|_| {
188            KitError::BuildArtifactMissing {
189                stem: stem.clone(),
190                dir: release_dir.display().to_string(),
191            }
192        })?;
193
194    let out_dir = out_dir.as_ref();
195    std::fs::create_dir_all(out_dir)?;
196
197    let base = format!("{crate_name}-{version}-{target}");
198    let library = out_dir.join(format!(
199        "{base}.{}",
200        crate::loader::lib_ext_for_target(&target)
201    ));
202    std::fs::copy(&built, &library)?;
203
204    let manifest_out = out_dir.join(format!("{base}.toml"));
205    std::fs::copy(&plugin_manifest, &manifest_out)?;
206
207    if options.verify_export && target == crate::TARGET_TRIPLE {
208        // The one check that cannot be made by inspecting file names: the symbol a host
209        // resolves before it calls anything. Catching it here costs a `dlopen`; catching
210        // it in the field costs a release.
211        //
212        // `()` as the entry type: the pointer is never dereferenced, so no layout
213        // assumption is made (see `loader::open`).
214        let _loaded = unsafe { crate::loader::open::<()>(&library, &cfg.entry_symbol) }?;
215    }
216
217    // Only worth keeping while something went wrong; a caller that packs repeatedly should
218    // not leave a trail of scaffolding in the temp directory. This removes the whole per-run
219    // directory, the crate directory inside it included.
220    //
221    // Failure is ignored on purpose: see `wrapper_dir` for why removing it can be refused on
222    // Windows, and a leftover directory is not a reason to fail a successful pack.
223    if let Some(run_root) = wrapper_dir.parent() {
224        let _ = remove_dir_if_exists(run_root);
225    }
226
227    Ok(PackedAssets {
228        crate_name,
229        version,
230        target,
231        library,
232        manifest: manifest_out,
233    })
234}
235
236/// Where this run's generated wrapper lives: `<temp>/<id>-plugin-asset-<pid>-<n>/<crate>`.
237///
238/// Unique per call, not per crate: two runs at once (two threads packing, or two `plugin
239/// asset` processes) must not delete and rewrite each other's files. The crate name stays in
240/// the path so a leftover directory is still identifiable, and the process id separates
241/// concurrent processes.
242///
243/// A failed build leaves the directory behind, which is the point — that is where someone
244/// looks. A successful one removes the per-run directory (its parent) again.
245fn wrapper_dir(cfg: &KitConfig, crate_name: &str) -> PathBuf {
246    static RUN: AtomicU64 = AtomicU64::new(0);
247
248    let run = RUN.fetch_add(1, Ordering::Relaxed);
249    std::env::temp_dir()
250        .join(format!(
251            "{}-plugin-asset-{}-{run}",
252            cfg.id,
253            std::process::id()
254        ))
255        .join(crate_name)
256}
257
258#[cfg(test)]
259mod tests {
260    use super::*;
261
262    #[test]
263    fn base_name_is_crate_version_target() {
264        let assets = PackedAssets {
265            crate_name: "bmux-plugin-cargo".to_string(),
266            version: "0.1.0".to_string(),
267            target: "x86_64-pc-windows-msvc".to_string(),
268            library: PathBuf::from("a.dll"),
269            manifest: PathBuf::from("a.toml"),
270        };
271
272        assert_eq!(
273            assets.base_name(),
274            "bmux-plugin-cargo-0.1.0-x86_64-pc-windows-msvc"
275        );
276    }
277
278    /// The regression this exists for: one directory per crate, shared by concurrent runs,
279    /// meant one run could be deleting files another was writing or compiling — which on
280    /// Windows fails outright with "access denied".
281    #[test]
282    fn every_run_gets_its_own_wrapper_dir() {
283        let cfg = KitConfig::new("myapp");
284
285        let first = wrapper_dir(&cfg, "myapp-plugin-foo");
286        let second = wrapper_dir(&cfg, "myapp-plugin-foo");
287        assert_ne!(first, second, "{first:?} must not be reused");
288
289        // Still identifiable: the crate name is the last component and the app id leads.
290        assert!(first.ends_with("myapp-plugin-foo"), "{}", first.display());
291        assert!(
292            first
293                .parent()
294                .and_then(|p| p.file_name())
295                .map(|n| n.to_string_lossy().starts_with("myapp-plugin-asset"))
296                .unwrap_or(false),
297            "{}",
298            first.display()
299        );
300    }
301
302    #[test]
303    fn two_crates_do_not_share_a_directory() {
304        let cfg = KitConfig::new("myapp");
305
306        assert_ne!(
307            wrapper_dir(&cfg, "myapp-plugin-foo"),
308            wrapper_dir(&cfg, "myapp-plugin-bar")
309        );
310    }
311
312    #[test]
313    fn verify_export_is_on_by_default() {
314        assert!(PackOptions::default().verify_export);
315        assert!(PackOptions::default().target_dir.is_none());
316    }
317
318    #[test]
319    fn a_missing_manifest_is_reported_as_such() {
320        let tmp = tempfile::tempdir().unwrap();
321        let cfg = KitConfig::new("myapp");
322
323        let err = build(
324            &cfg,
325            tmp.path(),
326            tmp.path().join("dist"),
327            &PackOptions::default(),
328        )
329        .unwrap_err();
330
331        assert!(matches!(err, KitError::NoManifest { .. }), "{err:?}");
332    }
333}