Skip to main content

r_package_installer/
lib.rs

1//! Transactional installation of predownloaded R package artifacts.
2//!
3//! This crate deliberately does not download or resolve packages. Each call
4//! prepares or publishes one package and is safe to schedule concurrently with
5//! calls for other packages.
6#![deny(unsafe_code, missing_docs)]
7
8mod archive;
9mod cache;
10mod error;
11mod fsutil;
12mod library;
13mod metadata;
14mod model;
15mod platform;
16mod source;
17mod transaction;
18
19pub use cache::Cache;
20pub use error::{Error, Result};
21pub use library::{recover_package, remove_package, scan_library};
22pub use model::{
23    ArchiveLimits, Artifact, BinaryArtifact, CacheEntry, CacheKey, CacheLockPolicy,
24    CancellationToken, Digest, ExpectedPackage, InstallOutcome, InstalledPackage, InstallerOptions,
25    LibraryEntry, LockMetadata, LockPolicy, PackageMetadata, PrepareRequest, RecoveryAction,
26    RecoveryPlan, RemovalOutcome, SourceArtifact, SourceOptions,
27};
28
29use std::path::Path;
30
31/// A reusable handle for a caller-owned package cache.
32#[derive(Debug, Clone)]
33pub struct Installer {
34    cache: Cache,
35    options: InstallerOptions,
36}
37
38impl Installer {
39    /// Creates an installer rooted at `cache_root`.
40    pub fn new(cache_root: impl Into<std::path::PathBuf>) -> Self {
41        Self {
42            cache: Cache::new(cache_root),
43            options: InstallerOptions::default(),
44        }
45    }
46
47    /// Creates an installer with explicit operational policy.
48    pub fn with_options(
49        cache_root: impl Into<std::path::PathBuf>,
50        options: InstallerOptions,
51    ) -> Self {
52        Self {
53            cache: Cache::new(cache_root),
54            options,
55        }
56    }
57
58    /// Returns the caller-owned cache configuration.
59    pub const fn cache(&self) -> &Cache {
60        &self.cache
61    }
62
63    /// Returns a validated immutable cache entry, building it on a miss.
64    pub fn prepare(&self, request: &PrepareRequest) -> Result<CacheEntry> {
65        self.cache.prepare(request, &self.options)
66    }
67
68    /// Publishes one cached package into an R library transactionally.
69    pub fn materialize(&self, entry: &CacheEntry, library: &Path) -> Result<InstallOutcome> {
70        transaction::materialize(entry, library, &self.options)
71    }
72
73    /// Prepares and publishes one package.
74    pub fn install(&self, request: &PrepareRequest, library: &Path) -> Result<InstallOutcome> {
75        let entry = self.prepare(request)?;
76        self.materialize(&entry, library)
77    }
78
79    /// Removes one package using the same backup transaction as installation.
80    pub fn remove(&self, library: &Path, package: &str) -> Result<RemovalOutcome> {
81        remove_package(library, package, &self.options)
82    }
83}