Packaging Zoi

This document provides detailed guidance for packagers on how to build and package Zoi for various distributions and package managers.

Build Dependencies

These are required to compile Zoi from source.

• Rust Toolchain: Zoi requires a specific version of the Rust compiler. Refer to rust-toolchain.toml for the exact channel and Cargo.toml for the Rust version and edition.
• C Compiler: A C compiler like gcc or clang.
• OpenSSL: Development libraries for OpenSSL (libssl-dev or openssl-devel).
• pkg-config: The pkg-config utility.
• liblzma: Development libraries for lzma (liblzma-dev).
• Git: Required to embed the commit hash in the binary.

Runtime Dependencies

• Essential: git is required for most of Zoi's functionality.
• Optional: less or more for viewing manuals and other paged content.

Build Process

Zoi can be built in several ways, depending on the packaging requirements.

Using Cargo

The standard Rust build process. The release profile is optimized for size and performance (see .cargo/config.toml).

cargo build --release

This produces the zoi binary in target/release/.

Using the Makefile

The provided Makefile simplifies the build and installation process.

# Configure installation paths (creates config.mk)
./configure

# Build the release binary
make build

# Install to configured location
sudo make install

Using Build Scripts

The scripts/ directory contains CI/CD scripts for creating release builds. These scripts automatically embed the git commit hash.

• scripts/build-release.sh: Creates a release build for the current platform.

Building the Docker Image Locally

A Dockerfile is provided for reproducible, containerized builds. You can pass build arguments to customize the embedded configuration.

# Build the docker image
docker build -t zoi .

# Build with custom telemetry and registry info
docker build \
  --build-arg POSTHOG_API_KEY="your_key" \
  --build-arg POSTHOG_API_HOST="your_host" \
  --build-arg ZOI_DEFAULT_REGISTRY="https://my-registry.com/repo.git" \
  -t zoi .

Using the Official Zoi CLI Docker Image

For CI/CD pipelines or environments where you need a pre-built Zoi CLI, an official Docker image is available on the GitLab Container Registry. This image contains the zoi binary and its runtime dependencies, making it suitable for tasks like building Zoi packages.

The image is tagged with both the specific release version (e.g. zoi:Prod-Release-1.2.2) and zoi:latest.

# Pull the latest Zoi CLI image
docker pull registry.gitlab.com/Zillowe/Zillwen/Zusty/Zoi/zoi:latest

# Example usage in a GitLab CI/CD job
my-job:
  image: registry.gitlab.com/Zillowe/Zillwen/Zusty/Zoi/zoi:latest
  script:
    - zoi package build my-package.pkg.lua --type source --platform linux-amd64

Build-time Configuration

Several aspects of Zoi can be configured at build time by setting environment variables. These are processed by build.rs.

These can be set in a .env file at the project root (see .env.example) or passed directly to the build command.

Generating Completions and Man Pages

Your package should include shell completions and man pages.

Shell Completions

Generate and install completions for various shells.

# This command will also attempt to install the completions
./target/release/zoi shell <shell>

# To just print the completions to stdout
./target/release/zoi generate-completions <shell>

Man Pages

Generate man pages for zoi and all its subcommands.

# Generate pages into a `manuals/` directory
./target/release/zoi generate-manual

# Specify an output directory
OUT_DIR=dist/man/ ./target/release/zoi generate-manual

These files should be installed to the appropriate system location (e.g. /usr/share/man/man1).

Existing Packaging Files

Refer to the packages/ directory for examples of how Zoi is packaged for other managers:

• Arch Linux (AUR): packages/aur/zoi/PKGBUILD
• Homebrew: packages/brew/zoi.rb
• Scoop: packages/scoop/zoi.json