Lua API Reference

Zoi provides a rich Lua environment for defining packages. This page serves as a complete reference for all global variables, tables, and utility functions available within your .pkg.lua scripts.

Global Variables

These variables are automatically available in your script's scope.

The SYSTEM Table

• SYSTEM.OS: The operating system (linux, macos, windows).
• SYSTEM.ARCH: The CPU architecture (amd64, arm64).
• SYSTEM.DISTRO: (Linux only) The distribution ID (e.g. ubuntu, arch).
• SYSTEM.DISTRO_VER: The version of the distribution (e.g. 22.04, 14.1).
• SYSTEM.DE: The detected Desktop Environment (e.g. kde, gnome, windows).
• SYSTEM.SERVER: The display server in use (e.g. x11, wayland, quartz).
• SYSTEM.KERNEL_VER: The kernel version of the operating system.
• SYSTEM.INIT: The detected init system (e.g. systemd, openrc).
• SYSTEM.CPU: CPU model information.
• SYSTEM.GPU: GPU model information.
• SYSTEM.MANAGER: The detected native package manager (e.g. apt, pacman).

The ZOI Table

• ZOI.VERSION: The version of the package being built (resolved from metadata).
• ZOI.scope: The currently requested installation scope (user, system, or project).
• ZOI.PATH.user: Path to Zoi's user directory (~/.zoi).
• ZOI.PATH.system: Path to Zoi's system-wide binary directory.

The ZOI.PKG Table

These variables provide absolute paths related to the current package environment.

The LOCATION Table

The LOCATION table provides absolute paths that correspond exactly to the ${...} placeholder variables used in build functions like zcp, zln, zmkdir, etc. These are the staging directory paths where files are placed during build, not the final install paths. This makes them directly usable in cmd() calls to achieve the same behavior as the placeholders.

Core Functions

zcp(source, destination)

Stages a file or directory to be included in the final package.

• Source: Path relative to BUILD_DIR, or use ${pkgluadir} for files next to the script.
• Destination: Use variables like ${pkgstore}, ${createpkgdir}, ${usrroot}, or ${usrhome}.

zlicense(source)

Stages a license file for the package. The destination path is determined by the installation scope:

• System Scope: ${usrroot}/usr/share/licenses/<pkgname>/<filename> (standard FHS location).

• Other Scopes: ${pkgstore}/<filename>.

• source: Path relative to BUILD_DIR, or use ${pkgluadir}.

zdoc(source)

Stages a documentation file for the package. The destination path is determined by the installation scope:

• System Scope: ${usrroot}/usr/share/doc/<pkgname>/<filename> (standard FHS location).

• Other Scopes: ${pkgstore}/doc/<filename>.

• source: Path relative to BUILD_DIR, or use ${pkgluadir}.

zman(source, section)

Stages a manual page for the package. If a directory is provided as the source, Zoi will recursively stage all manual files found within that directory.

The destination path is determined by the installation scope:

• System Scope: ${usrroot}/usr/share/man/man{section}/<filename> (standard FHS location).

• Other Scopes: ${pkgstore}/man/man{section}/<filename>.

• source: Path to a file or directory relative to BUILD_DIR, or use ${pkgluadir}.

• section: (Optional) The manual section (1-9). If omitted, Zoi attempts to infer it from the file extension (e.g. .1, .5).

zshell(source, shell)

Stages a shell completion file for a specific shell. The file is copied to ${pkgstore}/shell/{shell}/{filename} and symlinked into the global completions directory (~/.zoi/pkgs/shell/{shell}/{package}/). Zoi automatically manages the symlinks during install and uninstall.

• source: Path relative to BUILD_DIR, or use ${pkgluadir}.
• shell: The shell name. Supported values: "bash", "zsh", "fish", "elvish".

function package()
    zcp("${pkgluadir}/my-tool", "${pkgstore}/bin/my-tool")
    zshell("${pkgluadir}/_my-tool", "zsh")
    zshell("${pkgluadir}/my-tool.bash", "bash")
    zshell("${pkgluadir}/my-tool.fish", "fish")
end

function build()
    -- Install to STAGING_DIR/data/pkgstore (same as ${pkgstore} in zcp)
    cmd("make DESTDIR=" .. LOCATION.PKGSTORE .. " install")
    
    -- Or install to full staging root
    cmd("make DESTDIR=" .. LOCATION.STAGINGDIR .. " install")
end

zsed(pattern, replacement, file)

Performs an in-place regular expression replacement on a file within the build directory. This avoids the need for external sed commands and provides cross-platform regex support.

• pattern: The regex pattern to match.
• replacement: The string to replace the matched pattern. Backreferences like $1 are supported.
• file: The path to the file relative to BUILD_DIR.

zpatch(patch_file, strip)

Applies a patch file to the build directory using the system patch command.

• patch_file: The path to the patch file relative to BUILD_DIR.
• strip: (Optional) The number of leading path components to strip from file names in the patch file. Defaults to 1 (equivalent to patch -p1).

zln(target, link)

Creates a symbolic link in the package.

• target: The destination of the link (e.g. ${pkgstore}/bin/my-app).
• link: The path of the symlink to create (e.g. ${pkgstore}/bin/my-link).

zchmod(path, mode)

Sets the permissions of a file or directory in the package.

• path: Path to the file or directory (e.g. ${pkgstore}/bin/my-app).
• mode: Octal permission mode (e.g. 493 for 0755).

zchown(path, owner, group)

Sets the ownership of a file or directory in the package.

• path: Path to the file or directory.
• owner: The owner name or UID.
• group: The group name or GID.

zmkdir(path)

Creates a directory in the package.

• path: Path to the directory to create (e.g. ${pkgstore}/share/my-app).

zrm(path)

Used in the uninstall() function to remove files or directories outside of the package store. Supports placeholders like ${pkgstore}, ${usrroot}, and ${usrhome}.

cmd(command)

Executes a shell command within the BUILD_DIR.

• Persistence: Unlike standard shell wrappers, cmd() in Zoi uses a persistent shell session. This means state changes like directory changes (cd), environment variable exports (export), and shell function definitions persist across multiple cmd() calls within the same lifecycle phase (e.g. within build() or package()).
• Returns: Three values: stdout (string), stderr (string), and exit_code (integer).

function build()
    -- These commands share the same shell process
    cmd("cd source")
    cmd("export CFLAGS='-O3'")
    cmd("make") -- Runs inside 'source' with 'CFLAGS' set
end

IMPORT(file_name)

Reads and returns the content of a file located in the same directory as the .pkg.lua script.

• If the file ends in .json, .yaml, or .toml, it is automatically parsed into a Lua table.

INCLUDE(file_name)

Executes another Lua script located in the same directory. Useful for sharing logic between packages.

Package Definitions

These top-level functions are used to define the package's structure and behavior.

metadata(table)

Defines the package's static properties. See Creating Packages for a full list of fields.

dependencies(table)

Defines build-time and runtime requirements. See Dependencies for details.

updates(list)

Defines a list of update messages shown to the user.

Table Fields:

• type: (enum) update, change, or vulnerability.
• message: (string) The message text.

hooks(table)

Defines commands to run at specific points in the package's lifecycle (e.g. post_install).

service(table)

Defines a background service managed by the system.

Table Fields:

• run: (string) The command to execute.
• run_at_load: (boolean) Start on boot/login.
• working_dir: (string) Directory to run in.
• env: (table) Environment variables.
• log_path: (string) Path for standard output.
• error_log_path: (string) Path for error output.

Lifecycle Functions

Zoi calls these functions in a specific order during the build and installation process.

prepare(args)

Runs first to fetch source code or binaries into BUILD_DIR.

build(args)

Optional function that runs after prepare and before package. Use it for compilation steps in BUILD_DIR, this keeps prepare for fetching and package for staging.

package(args)

Runs after build (or prepare if no build is defined) to compile and stage files into STAGING_DIR.

verify(args)

Runs after package to ensure the integrity of the downloaded files. Should return true or false.

test(args)

Optional function run by zoi package test to validate the staged files.

uninstall()

Runs when the package is uninstalled to clean up external state.

The args table contains:

• sub: (string) The name of the sub-package being processed (for split packages).

Utility Tables (UTILS)

UTILS.FETCH

• UTILS.FETCH.url(url): Fetches the content of a URL as a string.
• UTILS.FETCH.<PROVIDER>.LATEST.<TYPE>({ repo, domain, branch })
  • Providers: GITHUB, GITLAB, GITEA, FORGEJO.
  • Types: tag, release, commit.
  • Example: local tag = UTILS.FETCH.GITHUB.LATEST.release({ repo = "Zillowe/Zoi" })

UTILS.PARSE

• UTILS.PARSE.json(string): Parses a JSON string into a Lua table.
• UTILS.PARSE.yaml(string): Parses a YAML string into a Lua table.
• UTILS.PARSE.toml(string): Parses a TOML string into a Lua table.
• UTILS.PARSE.checksumFile(content, filename): Extracts a checksum for a specific file from a standard checksum file string.

UTILS.FILE(url, path)

Downloads a file from a URL directly to the specified local path.

UTILS.DOWNLOAD(url, filename, hash)

Downloads a file from a URL and optionally verifies its hash.

• url: (string) The URL to download from.
• filename: (string, optional) The output filename. If omitted, the filename is extracted from the URL.
• hash: (string, optional) The expected hash of the file (e.g. "sha512-..." or "sha256-..."). If provided, the downloaded file is automatically verified. If the hash does not match, the function returns a RuntimeError, causing the build to fail.
• Returns: (string) The final filename of the downloaded file.

function prepare()
    -- Download and verify a file
    local file = UTILS.DOWNLOAD("https://example.com/tool.tar.gz", nil, "sha512-abc123...")
    UTILS.EXTRACT(file, "src")
end

UTILS.FS

• UTILS.FS.exists(path): Returns true if the path exists.
• UTILS.FS.copy(src, dest): Copies a file or directory.
• UTILS.FS.move(src, dest): Moves (renames) a file or directory.
• UTILS.FS.chmod(path, mode): Changes file permissions (Unix only).

UTILS.FIND

• UTILS.FIND.file(dir, name): Recursively searches for a file within a directory inside BUILD_DIR and returns its relative path.

UTILS.ARCHIVE

• UTILS.ARCHIVE.list(path): Returns a table (list of strings) containing all file paths within an archive (.zip, .tar.*, .zpa, .zsa, .7z, .rar, .deb).

UTILS.EXTRACT(source, out_dir)

Downloads (if URL) and extracts an archive (.zip, .tar.gz, .tar.xz, .tar.zst, .zpa, .zsa, .7z, .rar, .deb, .dmg, .pkg) into BUILD_DIR/out_dir.

UTILS.MAKE_ARCHIVE(source, output, algorithm)

Creates an archive from local source(s) and places it in the BUILD_DIR.

• source: (string or table) A single file/directory path or a list of paths relative to BUILD_DIR (or absolute).
• output: (string) The destination path for the created archive. If relative, it is placed in BUILD_DIR.
• algorithm: (string, optional) The compression algorithm. Supported values: "tar", "zip", "gz", "tar.gz", "tar.xz", "tar.zst", "zst". Defaults to "zst" (tar.zst).

function package()
    -- Create a zip archive of multiple directories
    UTILS.MAKE_ARCHIVE({ "bin", "share" }, "release.zip", "zip")
    zcp("release.zip", "${pkgstore}/release.zip")
end

Security Functions

verifyHash(file_path, "algo-hash")

Verifies a file's integrity. Supported algorithms: sha512, sha256.

• Example: verifyHash(file, "sha256-abc123...")

verifySignature(file_path, sig_path, key_name_or_url)

Verifies a PGP detached signature.

addPgpKey(url_or_path, name)

Adds a PGP key to Zoi's keyring for use in verifySignature.