zoi/
lib.rs

1//! # Zoi: The Universal Package Manager & Environment Setup Tool
2//!
3//! This crate provides the core functionality of Zoi as a library, allowing other
4//! Rust applications to leverage its package management and environment setup
5//! capabilities.
6//!
7//! ## Getting Started
8//!
9//! To use Zoi as a library, add it as a dependency in your `Cargo.toml`:
10//!
11//! ```toml
12//! [dependencies]
13//! zoi = { version = "1.0.0" } // Replace with the desired version
14//! ```
15//!
16//! ## Example: Install a package
17//!
18//! ```no_run
19//! use zoi::{install_package, Scope};
20//! use std::path::Path;
21//! use anyhow::Result;
22//!
23//! fn main() -> Result<()> {
24//!     let archive_path = Path::new("path/to/your/package-1.0.0-linux-amd64.pkg.tar.zst");
25//!     let scope = Some(Scope::User);
26//!     let registry_handle = "local";
27//!
28//!     let installed_files = install_package(archive_path, scope, registry_handle)?;
29//!
30//!     println!("Package installed successfully. {} files were installed.", installed_files.len());
31//!
32//!     Ok(())
33//! }
34//! ```
35//!
36//! For more detailed documentation, see the [Zoi Documentation Hub](https://zillowe.qzz.io/docs/zds/zoi).
37//! For more library examples, see the [Library Examples page](https://zillowe.qzz.io/docs/zds/zoi/lib/examples).
38
39pub mod cli;
40pub mod cmd;
41pub mod pkg;
42pub mod project;
43pub mod utils;
44
45use anyhow::Result;
46pub use pkg::types::{self, Scope};
47use std::path::Path;
48
49/// Builds a Zoi package from a local `.pkg.lua` file.
50///
51/// This function reads a package definition, runs the build process, and creates
52/// a distributable `.pkg.tar.zst` archive.
53///
54/// # Arguments
55///
56/// * `package_file`: Path to the `.pkg.lua` file.
57/// * `build_type`: The type of package to build (e.g. "source", "pre-compiled").
58/// * `platforms`: A slice of platform strings to build for (e.g. `["linux-amd64"]`).
59/// * `sign_key`: An optional PGP key name or fingerprint to sign the package.
60///
61/// # Errors
62///
63/// Returns an error if the build process fails, if the package file cannot be read,
64/// or if the specified build type is not supported by the package.
65///
66/// # Examples
67///
68/// ```no_run
69/// use zoi::build;
70/// use std::path::Path;
71/// use anyhow::Result;
72///
73/// fn main() -> Result<()> {
74///     let package_file = Path::new("my-package.pkg.lua");
75///     let platforms = vec!["linux-amd64".to_string()];
76///     build(package_file, "source", &platforms, None)?;
77///     println!("Package built successfully!");
78///     Ok(())
79/// }
80/// ```
81pub fn build(
82    package_file: &Path,
83    build_type: &str,
84    platforms: &[String],
85    sign_key: Option<String>,
86) -> Result<()> {
87    pkg::package::build::run(package_file, build_type, platforms, sign_key, None, None)
88}
89
90/// Installs a Zoi package from a local package archive.
91///
92/// This function unpacks a `.pkg.tar.zst` archive and installs its contents
93/// into the appropriate Zoi store, linking any binaries.
94///
95/// # Arguments
96///
97/// * `package_file`: Path to the local package archive.
98/// * `scope_override`: Optionally override the installation scope (`User`, `System`, `Project`).
99/// * `registry_handle`: The handle of the registry this package belongs to (e.g. "zoidberg", or "local").
100///
101/// # Returns
102///
103/// A `Result` containing a `Vec<String>` of all the file paths that were installed.
104///
105/// # Errors
106///
107/// Returns an error if the installation fails, such as if the archive is invalid
108/// or if there are file system permission issues.
109///
110/// # Examples
111///
112/// ```no_run
113/// use zoi::{install_package, Scope};
114/// use std::path::Path;
115/// use anyhow::Result;
116///
117/// fn main() -> Result<()> {
118///     let archive_path = Path::new("my-package-1.0.0-linux-amd64.pkg.tar.zst");
119///     install_package(archive_path, Some(Scope::User), "local")?;
120///     println!("Package installed!");
121///     Ok(())
122/// }
123/// ```
124pub fn install_package(
125    package_file: &Path,
126    scope_override: Option<Scope>,
127    registry_handle: &str,
128) -> Result<Vec<String>> {
129    pkg::package::install::run(package_file, scope_override, registry_handle, None)
130}
131
132/// Uninstalls a Zoi package.
133///
134/// This function removes a package's files from the Zoi store and unlinks its binaries.
135///
136/// # Arguments
137///
138/// * `package_name`: The name of the package to uninstall.
139/// * `scope_override`: Optionally specify the scope to uninstall from. If `None`, Zoi
140///   will search for the package across all scopes.
141///
142/// # Errors
143///
144/// Returns an error if the package is not found or if the uninstallation process fails.
145///
146/// # Examples
147///
148/// ```no_run
149/// use zoi::{uninstall_package, Scope};
150/// use anyhow::Result;
151///
152/// fn main() -> Result<()> {
153///     uninstall_package("my-package", Some(Scope::User))?;
154///     println!("Package uninstalled!");
155///     Ok(())
156/// }
157/// ```
158pub fn uninstall_package(package_name: &str, scope_override: Option<Scope>) -> Result<()> {
159    pkg::uninstall::run(package_name, scope_override).map(|_| ())
160}
zoi/lib.rs

zoi/
lib.rs
