Zillowe FoundationZillowe Documentation

Library Examples

Practical examples of how to use the Zoi library in your Rust code.

This page provides practical, copy-paste-ready examples for using Zoi's library features.

Resolving a Package Source

This example resolves a source string before installation. This is useful if you want to inspect the package metadata, chosen version, or source path in your own application.

Code

use zoi::resolve_package;
use anyhow::Result;

fn main() -> Result<()> {
    let resolved = resolve_package("@core/hello@stable", true)?;

    println!("Resolved package: {}", resolved.package.name);
    println!("Resolved version: {}", resolved.version);
    println!("Source path: {}", resolved.source_path.display());

    Ok(())
}

Resolving a Dependency Graph

This example computes the dependency graph for one or more sources without installing anything.

Code

use zoi::{resolve_dependency_graph, DependencyResolutionOptions, Scope};
use anyhow::Result;

fn main() -> Result<()> {
    let sources = vec!["@core/hello@stable".to_string()];
    let options = DependencyResolutionOptions {
        scope_override: Some(Scope::User),
        yes: true,
        quiet: true,
        ..Default::default()
    };

    let resolution = resolve_dependency_graph(&sources, &options)?;

    println!("Resolved {} packages", resolution.graph.nodes.len());
    println!(
        "Non-Zoi dependencies: {}",
        resolution.non_zoi_dependencies.len()
    );

    Ok(())
}

Building a Package

This example demonstrates how to build a package from a .pkg.lua file. This will create a distributable package archive (.pkg.tar.zst).

Code

use zoi::{build_with_options, BuildOptions};
use std::path::Path;
use anyhow::Result;

fn main() -> Result<()> {
    // Path to your package definition file.
    let package_file = Path::new("path/to/your/package.pkg.lua");

    let options = BuildOptions {
        build_type: Some("source"),
        platforms: vec!["linux-amd64".to_string()],
        sign_key: Some("YourPgpKeyNameOrFingerprint".to_string()),
        ..Default::default()
    };

    println!("Building package: {}", package_file.display());

    build_with_options(package_file, &options)?;

    println!("Package built successfully!");

    Ok(())
}

Installing a Package

This example shows how to install a package from a local archive file that you have either built or downloaded.

Code

use zoi::{install_package_with_options, PackageInstallOptions, Scope};
use std::path::Path;
use anyhow::Result;

fn main() -> Result<()> {
    // Path to the package archive.
    let archive_path = Path::new("path/to/your/package-1.0.0-linux-amd64.pkg.tar.zst");

    let options = PackageInstallOptions {
        scope_override: Some(Scope::User),
        registry_handle: "local".to_string(),
        yes: true,
        ..Default::default()
    };

    println!("Installing from archive: {}", archive_path.display());

    let installed_files = install_package_with_options(archive_path, &options)?;

    println!("Package installed successfully. {} files were installed.", installed_files.len());

    Ok(())
}

Installing From Sources

This example installs from source specs instead of a prebuilt archive. The source can be a registry package name, a local .pkg.lua file, or a URL.

Code

use zoi::{install_sources, SourceInstallOptions, Scope};
use anyhow::Result;

fn main() -> Result<()> {
    let sources = vec![
        "@core/hello@stable".to_string(),
        "./my-package.pkg.lua".to_string(),
    ];

    let options = SourceInstallOptions {
        scope_override: Some(Scope::User),
        yes: true,
        build: true,
        ..Default::default()
    };

    install_sources(&sources, &options)?;

    Ok(())
}

Uninstalling a Package

This example demonstrates how to programmatically uninstall a package.

Code

use zoi::{uninstall_package, Scope};
use anyhow::Result;

fn main() -> Result<()> {
    let package_name = "my-package-name";

    // Optionally specify the scope from which to uninstall.
    let scope = Some(Scope::User);

    println!("Uninstalling package: {}", package_name);

    // Call the uninstall function.
    uninstall_package(package_name, scope)?;

    println!("Package '{}' uninstalled successfully.", package_name);

    Ok(())
}

A software organization

2026 © All Rights Reserved.

  • All the content is available under CC BY-SA 4.0, expect where otherwise stated.

Last updated on