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

zoi/
lib.rs
