Zillowe Docs - Library API

How to integrate Zoi's package management features into your own Rust applications.

Zoi is not just a command-line tool; it's also a Rust library that you can use to programmatically build and manage packages. This allows you to embed Zoi's powerful packaging capabilities directly into your own applications.

Docs.rs. Crates.io.

Getting Started

To use Zoi as a library, add it as a dependency in your project:

cargo add zoi-rs

Or in your Cargo.toml file:

[dependencies]
zoi-rs = "1" # Check crates.io for the latest version

Core Functions

These are the primary functions for building and managing packages.

build_with_options

Builds a Zoi package using a typed options struct.

build

Compatibility wrapper for building a Zoi package.

install_sources

Installs packages from registry, local file, URL, or git-backed sources.

resolve_package

Resolves a source string into a package, version, and origin metadata.

resolve_dependency_graph

Returns the dependency graph for one or more requested sources.

install_package_with_options

Installs a local package archive using a typed options struct.

install_package

Compatibility wrapper for installing a local package archive.

uninstall_package

Uninstalls a Zoi package.

`build` function

This is the compatibility wrapper around build_with_options.

`build_with_options` function

This is the recommended build API for new integrations. It accepts a typed BuildOptions struct instead of a long positional argument list.

Signature

pub fn build_with_options(
    package_file: &Path,
    options: &BuildOptions<'_>,
) -> Result<()>

Key Types

pub struct BuildOptions<'a> {
    pub build_type: Option<&'a str>,
    pub platforms: Vec<String>,
    pub sign_key: Option<String>,
    pub install_deps: bool,
    pub method: &'a str,
    pub image: Option<&'a str>,
    pub version_override: Option<&'a str>,
}

This function builds a Zoi package from a .pkg.lua definition file for one or more target platforms.

Signature

pub fn build(
    package_file: &Path,
    build_type: Option<&str>,
    platforms: &[String],
    sign_key: Option<String>,
    install_deps: bool,
    method: &str,
    image: Option<&str>,
    version_override: Option<&str>,
) -> Result<()>

Parameters

Parameter	Type	Description
`package_file`	`&Path`	The path to the `.pkg.lua` file that defines the package.
`build_type`	`Option<&str>`	The type of package to build (e.g. `"source"`). Defaults to `pre-compiled`, then `source`, if not set.
`platforms`	`&[String]`	A slice of platform strings to build for (e.g. `["linux-amd64", "windows-amd64"]`).
`sign_key`	`Option<String>`	An optional PGP key name or fingerprint to sign the resulting package archive.
`install_deps`	`bool`	Automatically install build-time dependencies before building.
`method`	`&str`	The build method to use (`"native"` or `"docker"`).
`image`	`Option<&str>`	The Docker image to use (required if `method` is `"docker"`).
`version_override`	`Option<&str>`	Optionally override the package version defined in the `.pkg.lua` file.

`install_package` function

This is the compatibility wrapper around install_package_with_options.

`install_sources` function

Installs one or more package sources using the same source formats supported by the CLI: registry package names, local .pkg.lua files, local manifests, URLs, and other supported direct sources.

Signature

pub fn install_sources(
    sources: &[String],
    options: &SourceInstallOptions,
) -> Result<()>

Key Types

pub struct SourceInstallOptions {
    pub repo: Option<String>,
    pub force: bool,
    pub all_optional: bool,
    pub yes: bool,
    pub scope_override: Option<Scope>,
    pub save: bool,
    pub build_type: Option<String>,
    pub dry_run: bool,
    pub build: bool,
    pub frozen_lockfile: bool,
}

`resolve_package` function

Resolves a single source string into a package plus origin metadata. This is useful for library consumers that want to inspect a package before installing it.

Signature

pub fn resolve_package(source: &str, yes: bool) -> Result<ResolvedPackage>

Result Type

pub struct ResolvedPackage {
    pub package: types::Package,
    pub version: String,
    pub sharable_manifest: Option<types::SharableInstallManifest>,
    pub source_path: PathBuf,
    pub registry_handle: Option<String>,
    pub git_sha: Option<String>,
}

`resolve_dependency_graph` function

Builds the dependency graph for one or more requested sources without performing installation.

Signature

pub fn resolve_dependency_graph(
    sources: &[String],
    options: &DependencyResolutionOptions,
) -> Result<DependencyResolution>

Key Types

pub struct DependencyResolutionOptions {
    pub scope_override: Option<Scope>,
    pub force: bool,
    pub yes: bool,
    pub all_optional: bool,
    pub build_type: Option<String>,
    pub quiet: bool,
}

`install_package_with_options` function

This is the recommended archive install API for new integrations. It accepts a typed PackageInstallOptions struct.

Signature

pub fn install_package_with_options(
    package_file: &Path,
    options: &PackageInstallOptions,
) -> Result<Vec<String>>

Key Types

pub struct PackageInstallOptions {
    pub scope_override: Option<Scope>,
    pub registry_handle: String,
    pub yes: bool,
    pub sub_packages: Option<Vec<String>>,
    pub link_bins: bool,
}

Installs a Zoi package from a local .pkg.tar.zst archive file.

Signature

pub fn install_package(
    package_file: &Path,
    scope_override: Option<Scope>,
    registry_handle: &str,
    yes: bool,
    sub_packages: Option<Vec<String>>,
) -> Result<Vec<String>>

Parameters

Parameter	Type	Description
`package_file`	`&Path`	The path to the local package archive (`.pkg.tar.zst`).
`scope_override`	`Option<Scope>`	An optional `Scope` (`User`, `System`, `Project`) to override the default scope defined in the package.
`registry_handle`	`&str`	The handle of the registry this package belongs to. Use `"local"` for packages not from a registry.
`yes`	`bool`	Automatically answer "yes" to any confirmation prompts (e.g. file conflicts).
`sub_packages`	`Option<Vec<String>>`	For split packages, optionally specify which sub-packages to install.

`uninstall_package` function

Removes a package that was previously installed by Zoi.

Signature

pub fn uninstall_package(
    package_name: &str,
    scope_override: Option<Scope>
) -> Result<()>

Parameters

Parameter	Type	Description
`package_name`	`&str`	The name of the package to uninstall.
`scope_override`	`Option<Scope>`	Optionally specify the scope to uninstall from. If `None`, Zoi will search for the package in all scopes.

For complete, runnable examples, please see the Library Examples page.

Library API

Getting Started

Core Functions

build_with_options

build

install_sources

resolve_package

resolve_dependency_graph

install_package_with_options

install_package

uninstall_package

`build` function

`build_with_options` function

Signature

Key Types

Signature

Parameters

`install_package` function

`install_sources` function

Signature

Key Types

`resolve_package` function

Signature

Result Type

`resolve_dependency_graph` function

Signature

Key Types

`install_package_with_options` function

Signature

Key Types

Signature

Parameters

`uninstall_package` function

Signature

Parameters

Zillowe Foundation

On this page