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}