Hello, World

A program written in Zig to only print Hello, World! and handle errors. This program is used as an example to demonstrate how to package software for Zoi.

In this guide, we'll walk through the hello.pkg.lua file to understand how it's packaged for Zoi using the from-source installation method.

Installation

You can install this program using Zoi by running:

zoi install @zillowe/hello

Setup

To follow this guide and build the package yourself, you need to have zoi and zig installed.

Packaging hello.pkg.lua Explained

Zoi uses Lua scripts (.pkg.lua files) to define packages. Let's break down the official hello.pkg.lua file.

1. Helper Variables and Functions

The script starts by defining local variables and a helper function to determine the Zig target triple based on the host system.

local repo_owner = "zillowe"
local repo_name = "hello"
local version = ZOI.VERSION or "5.0.0"
local git_url = "https://github.com/" .. repo_owner .. "/" .. repo_name .. ".git"

local function get_zig_target()
    local os = SYSTEM.OS
    local arch = SYSTEM.ARCH
    if arch == "amd64" then
        arch = "x86_64"
    elseif arch == "arm64" then
        arch = "aarch64"
    end
    return arch .. "-" .. os
end

2. The metadata Function

This defines the package's core properties, including supported build types (source only).

metadata({
    name = "hello",
    repo = "zillowe",
    version = version,
    revision = "1",
    description = "Hello World",
    website = "https://github.com/zillowe/hello",
    git = git_url,
    man = "https://raw.githubusercontent.com/zillowe/hello/refs/heads/main/app/man.md",
    maintainer = {
        name = "Zillowe Foundation",
        website = "https://zillowe.qzz.io",
        email = "contact@zillowe.qzz.io",
    },
    license = "Apache-2.0",
    bins = { "hello" },
    types = { "source" }, -- Supported build method
    tags = { "zillowe", "example", "hello", "cli" },
})

3. The dependencies Function

Defines build-time dependencies. This package requires zig and git to build from source.

dependencies({
    build = {
        types = {
            source = {
                required = { "pacman:zig", "pacman:git" },
            },
        },
    },
})

4. The prepare Function

Prepares the source code by cloning the repository at the specified version and running the build command.

function prepare()
    if BUILD_TYPE == "source" then
        cmd("git clone --depth 1 --branch " .. "v" .. version .. " " .. PKG.git .. " source")
        cmd("cd " .. BUILD_DIR .. "/source && zig build --release=small -Dtarget=" .. get_zig_target())
    end
end

5. The package Function

Stages the final build artifacts into the staging area using the zcp command.

function package()
    if BUILD_TYPE == "source" then
        local bin_name = "hello"
        if SYSTEM.OS == "windows" then
            bin_name = "hello.exe"
        end
        zcp("source/zig-out/bin/" .. bin_name, "${pkgstore}/bin/" .. bin_name)
    end
end

6. The verify Function

A placeholder for integrity verification, which returns true for source builds in this example.

function verify()
    return true
end

Building the Package

To build the package from source using the local definition:

zoi package build ./hello.pkg.lua --type source

This command will:

1. Create a temporary build environment.
2. Run the prepare, package, and verify functions from your script.
3. Bundle the results into a hello-5.0.0-{os}-{arch}.pkg.tar.zst archive.

Installing the Local Archive

Test your final package archive by installing it locally:

zoi package install ./hello-5.0.0-linux-amd64.pkg.tar.zst