'\" t
.\"     Title: zoi-rs
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-10-16
.\"    Manual: Zoi Library Manual
.\"    Source: zoi-rs
.\"  Language: English
.\"
.TH "ZOI\-RS" "3" "2026-10-16" "zoi\-rs" "Zoi Library Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
zoi-rs \- Rust library for the Zoi package manager and environment orchestrator
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam C
use anyhow::Result;
use zoi::{Scope, SourceInstallOptions, install_sources};

fn main() \-> Result<()> {
    let options = SourceInstallOptions {
        scope_override: Some(Scope::User),
        yes: true,
        ..Default::default()
    };
    install_sources(&["@core/ripgrep".to_string()], &options)?;
    Ok(())
}
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
The \fBzoi\-rs\fP crate (imported as \fBzoi\fP) exposes Zoi\(cqs package management,
dependency resolution, and archive building capabilities as a Rust library.
Its API is designed around "Pragmatic Transactionality": a two\-phase
installation process, SAT\-based dependency resolution, and
cryptographically verified registry state. The same code powers the
\fBzoi\fP(1) command\-line interface.
.sp
The authoritative API reference with runnable examples is published at
.URL "https://docs.rs/zoi\-rs" "" "."
The crate is distributed through crates.io at
.URL "https://crates.io/crates/zoi\-rs" "" "."
Conceptual guides live at
.URL "https://zillowe.qzz.io/docs/zds/zoi" "" "."
.SH "INSTALLATION"
.sp
Add the crate to a Rust project with Cargo:
.sp
.if n .RS 4
.nf
.fam C
cargo add zoi\-rs
.fam
.fi
.if n .RE
.sp
or declare the dependency manually in Cargo.toml:
.sp
.if n .RS 4
.nf
.fam C
[dependencies]
zoi\-rs = "1"
anyhow = "1"
.fam
.fi
.if n .RE
.sp
The library targets recent stable Rust (edition 2024) and defines no
optional feature flags. All fallible functions return \f(CRanyhow::Result\fP.
.SH "INSTALLING PACKAGES"
.sp
\fBinstall_sources\fP(\fIsources\fP, \fIoptions\fP)
.RS 4
Install one or more package sources: registry names such as
\f(CR@core/ripgrep\fP, local \f(CR.pkg.lua\fP files, URLs, or local manifests.
Takes \fBSourceInstallOptions\fP. This is the same path the CLI install
command uses, including plugin loading.
.RE
.sp
\fBinstall_package\fP(\fIarchive\fP, \fIscope\fP, \fIregistry\fP, \fIyes\fP, \fIsubs\fP)
.RS 4
Install a local .zpa archive. Returns the list of installed files.
Simplified wrapper around \fBinstall_package_with_options\fP with binary
linking enabled.
.RE
.sp
\fBinstall_package_with_options\fP(\fIarchive\fP, \fIoptions\fP)
.RS 4
Install a local .zpa archive with full control. Takes
\fBPackageInstallOptions\fP and returns the list of installed files.
.RE
.sp
\fBupdate_packages\fP(\fIall\fP, \fInames\fP, \fIyes\fP)
.RS 4
Update installed packages to their latest versions through a
transactional upgrade check against the registries.
.RE
.sp
\fBuninstall_package\fP(\fIname\fP, \fIscope\fP)
.RS 4
Remove an installed package from the store and unlink its binaries.
The name may include registry, repository, sub\-package, and version
selectors.
.RE
.SH "RESOLVING PACKAGES"
.sp
\fBresolve_package\fP(\fIsource\fP, \fIyes\fP)
.RS 4
Resolve a single source string into \fBResolvedPackage\fP metadata
(package definition, exact version, origin, and registry handle)
without installing anything.
.RE
.sp
\fBresolve_dependency_graph\fP(\fIsources\fP, \fIoptions\fP)
.RS 4
Calculate the full dependency graph for a set of sources without
modifying the disk. Returns a \fBDependencyResolution\fP holding the
install graph plus any non\-Zoi (foreign manager) dependencies. Takes
\fBDependencyResolutionOptions\fP.
.RE
.SH "BUILDING AND BUNDLING"
.sp
\fBbuild_with_options\fP(\fIpackage_file\fP, \fIoptions\fP)
.RS 4
Build a distributable .zpa archive from a \f(CR.pkg.lua\fP definition (see
\fBzoi\-lua\fP(5)). Takes \fBBuildOptions\fP to select build type, target
platforms, signing, output directory, build method, and testing.
.RE
.sp
\fBbuild\fP(\fIpackage_file\fP, \fIbuild_type\fP, \fIplatforms\fP, \fIsign_key\fP,
\fIinstall_deps\fP, \fImethod\fP, \fIimage\fP, \fIversion_override\fP)::
Simplified wrapper around \fBbuild_with_options\fP with embedded
signatures and no test phase.
.sp
\fBbundle_package\fP(\fIpackage_file\fP, \fIoutput_dir\fP, \fIsign\fP, \fIversion_override\fP,
\fIbuild_type\fP)::
Bundle a package definition and its local assets into a .zsa source
archive, always with an embedded signature.
.SH "OPTION STRUCTS"
.sp
\fBSourceInstallOptions\fP
.RS 4
Configure source installation: \fBrepo\fP (git spec), \fBforce\fP,
\fBall_optional\fP, \fByes\fP, \fBscope_override\fP, \fBsave\fP (write to zoi.lua),
\fBbuild_type\fP, \fBdry_run\fP (plan only), \fBbuild\fP (force a source build),
and \fBfrozen\fP (enforce zoi.lock).
.RE
.sp
\fBPackageInstallOptions\fP
.RS 4
Configure local archive installation: \fBscope_override\fP (default User),
\fBregistry_handle\fP (default "local"), \fByes\fP (default true),
\fBsub_packages\fP, and \fBlink_bins\fP (default true).
.RE
.sp
\fBBuildOptions\fP
.RS 4
Configure archive building: \fBbuild_type\fP, \fBplatforms\fP (default:
current platform), \fBsign_key\fP, \fBsign_mode\fP (Embed or File),
\fBoutput_dir\fP, \fBsub_packages\fP, \fBinstall_deps\fP (default true), \fBtest\fP,
\fBmethod\fP ("native", "bwrap", or "docker"), \fBimage\fP, \fBversion_override\fP,
and \fBfakeroot\fP.
.RE
.sp
\fBDependencyResolutionOptions\fP
.RS 4
Configure graph resolution: \fBscope_override\fP, \fBforce\fP, \fByes\fP,
\fBall_optional\fP, \fBbuild_type\fP, and \fBquiet\fP.
.RE
.SH "KEY TYPES"
.sp
\fBScope\fP
.RS 4
Selects the \fBUser\fP, \fBSystem\fP, or \fBProject\fP installation scope.
.RE
.sp
\fBResolvedPackage\fP
.RS 4
The result of \fBresolve_package\fP: the package definition, exact
version, an optional shareable manifest, the source path, and origin
metadata (registry handle, repository type, git revision).
.RE
.sp
\fBDependencyResolution\fP
.RS 4
The result of \fBresolve_dependency_graph\fP: the dependency graph plus
foreign dependencies.
.RE
.sp
\fBtypes\fP
.RS 4
Package metadata types, including \fBtypes::Package\fP,
\fBtypes::Config\fP and \fBtypes::Policy\fP, \fBtypes::InstallManifest\fP,
\fBtypes::SignMode\fP, registry types, services, hooks, and security
advisories.
.RE
.sp
\fButils\fP
.RS 4
Shared helpers such as platform detection, well\-known directory paths,
HTTP client construction, filesystem utilities, hashing, and prompting.
.RE
.SH "MODULES"
.sp
\fBzoi::cli\fP, \fBzoi::cmd\fP
.RS 4
Command\-line argument parsing and the implementation of every \fBzoi\fP(1)
subcommand. Prefer the top\-level functions above unless embedding the
full CLI behavior.
.RE
.sp
\fBzoi::pkg\fP
.RS 4
Facade over the lower\-level crates: installation, resolution, local
store access, packaging, deltas, verification, PGP, caching,
transactions, services, and plugins.
.RE
.sp
\fBzoi::project\fP
.RS 4
Project support: configuration, environments, task execution,
lockfiles, and verification for zoi.lua\-based projects.
.RE
.SH "ERRORS"
.sp
Library functions return \f(CRanyhow::Result\fP. Failures report build,
resolution, install, verification, and network errors with context.
Callers should surface the error chain to the user; there are no custom
error enums to match on.
.SH "EXAMPLES"
.sp
Install a registry package into the user scope:
.sp
.if n .RS 4
.nf
.fam C
use anyhow::Result;
use zoi::{Scope, SourceInstallOptions, install_sources};

fn main() \-> Result<()> {
    let options = SourceInstallOptions {
        scope_override: Some(Scope::User),
        yes: true,
        ..Default::default()
    };
    install_sources(&["@core/ripgrep".to_string()], &options)?;
    Ok(())
}
.fam
.fi
.if n .RE
.sp
Resolve without installing:
.sp
.if n .RS 4
.nf
.fam C
use anyhow::Result;
use zoi::resolve_package;

fn main() \-> Result<()> {
    let resolved = resolve_package("@core/ripgrep", true)?;
    println!("{} {}", resolved.package.name, resolved.version);
    Ok(())
}
.fam
.fi
.if n .RE
.sp
Build an archive from a package definition:
.sp
.if n .RS 4
.nf
.fam C
use std::path::Path;
use anyhow::Result;
use zoi::{BuildOptions, build_with_options};

fn main() \-> Result<()> {
    let options = BuildOptions {
        test: true,
        ..Default::default()
    };
    build_with_options(Path::new("ripgrep.pkg.lua"), &options)?;
    Ok(())
}
.fam
.fi
.if n .RE
.SH "SEE ALSO"
.sp
\fBzoi\fP(1), \fBzoi\-lua\fP(5)
.sp
Full API reference: \c
.URL "https://docs.rs/zoi\-rs" "" ""
.sp
Crate.io: \c
.URL "https://crates.io/crates/zoi\-rs" "" ""
.sp
Online documentation: \c
.URL "https://zillowe.qzz.io/docs/zds/zoi" "" ""
.sp
Project repository and issue tracker:
.URL "https://gitlab.com/zillowe/zillwen/zusty/zoi" "" ""
.SH "COPYING"
.sp
Copyright \(co Zillowe Foundation. Licensed under Apache\-2.0.