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        false,
100    )
101}
102
103/// Installs a Zoi package from a local package archive.
104///
105/// This function unpacks a `.pkg.tar.zst` archive and installs its contents
106/// into the appropriate Zoi store, linking any binaries.
107///
108/// # Arguments
109///
110/// * `package_file`: Path to the local package archive.
111/// * `scope_override`: Optionally override the installation scope (`User`, `System`, `Project`).
112/// * `registry_handle`: The handle of the registry this package belongs to (e.g. "zoidberg", or "local").
113/// * `yes`: Automatically answer "yes" to any confirmation prompts (e.g. file conflicts).
114/// * `sub_packages`: For split packages, optionally specify which sub-packages to install.
115///
116/// # Returns
117///
118/// A `Result` containing a `Vec<String>` of all the file paths that were installed.
119///
120/// # Errors
121///
122/// Returns an error if the installation fails, such as if the archive is invalid
123/// or if there are file system permission issues.
124///
125/// # Examples
126///
127/// ```no_run
128/// use zoi::{install_package, Scope};
129/// use std::path::Path;
130/// use anyhow::Result;
131///
132/// fn main() -> Result<()> {
133///     let archive_path = Path::new("my-package-1.0.0-linux-amd64.pkg.tar.zst");
134///     install_package(archive_path, Some(Scope::User), "local", true, None)?;
135///     println!("Package installed!");
136///     Ok(())
137/// }
138/// ```
139pub fn install_package(
140    package_file: &Path,
141    scope_override: Option<Scope>,
142    registry_handle: &str,
143    yes: bool,
144    sub_packages: Option<Vec<String>>,
145) -> Result<Vec<String>> {
146    pkg::package::install::run(
147        package_file,
148        scope_override,
149        registry_handle,
150        None,
151        yes,
152        sub_packages,
153    )
154}
155
156/// Uninstalls a Zoi package.
157///
158/// This function removes a package's files from the Zoi store and unlinks its binaries.
159///
160/// # Arguments
161///
162/// * `package_name`: The name of the package to uninstall.
163/// * `scope_override`: Optionally specify the scope to uninstall from. If `None`, Zoi
164///   will search for the package across all scopes.
165///
166/// # Errors
167///
168/// Returns an error if the package is not found or if the uninstallation process fails.
169///
170/// # Examples
171///
172/// ```no_run
173/// use zoi::{uninstall_package, Scope};
174/// use anyhow::Result;
175///
176/// fn main() -> Result<()> {
177///     uninstall_package("my-package", Some(Scope::User))?;
178///     println!("Package uninstalled!");
179///     Ok(())
180/// }
181/// ```
182pub fn uninstall_package(package_name: &str, scope_override: Option<Scope>) -> Result<()> {
183    pkg::uninstall::run(package_name, scope_override).map(|_| ())
184}
zoi/lib.rs

zoi/
lib.rs
