zig-ebuilder

zig-ebuilder generates package recipes for system package manager. It consumes build.zig and build.zig.zon files to fetch dependencies and find:

• modules and artifacts (from dependencies and project itself),
• user options and system integration options.

Git-commit dependencies URLs git+https:// are automatically converted to tarball download URLs https:// if possible. Currently recognized services: Codeberg, GitHub, GitLab, Mach mirror and Sourcehut. If host is unknown, they are archived in one archive (called "tarball-tarball" from now on) which is then stored in cache directory, and path is printed to the user.

IMPORTANT Currently, there is no official way to declare information about licenses, homepage and "short description" in build.zig.zon, so we can't extract it. You will need to fill it manually after generation.

For now I recommend to use REUSE tooling (for authors and users) and wait for resolution of https://github.com/ziglang/zig/issues/14342.

Additionally, currently one unofficial field is supported: summary from another proposal (corresponds to "short description")

Result is then written to the file or STDOUT (you can set file name explicitly or let zig-ebuilder fill it for you).

Supported formats are ebuilds for Gentoo-based distros with zig.eclass (see https://github.com/gentoo/gentoo/pull/37283).

NOTE In theory nothing prevents changing it to be useful for other distros too. For now, as a workaround you can use --template option below.

Usage

For compilation you need Zig 0.14 .

For using at runtime you can use Zig 0.13, 0.14 or latest master commit (tested with 0.15.0-dev.2+79460d4a3).

$ zig build

Executable, build runners and default template will be installed in zig-out.

Fetched dependencies and tarball-tarball are stored in cache directory, by default ${XDG_CACHE_HOME}/zig-ebuilder/ or ${HOME}/.cache/zig-ebuilder/.

$ zig-ebuilder [options] <path-to-project>

Example for https://github.com/natecraddock/zf:

$ zig-ebuilder --zig /usr/bin/zig-0.13.0 .

# Copyright 2025 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

# Generated by zig-ebuilder 0.1.0

EAPI=8

DESCRIPTION="Write manually"
HOMEPAGE="Write manually"

declare -g -r -A ZBS_DEPENDENCIES=(
	[libxev-12207b7a5b538ffb7fb18f954ae17d2f8490b6e3778a9e30564ad82c58ee8da52361.tar.gz]='https://github.com/mitchellh/libxev/archive/f6a672a78436d8efee1aa847a43a900ad773618b.tar.gz'
	[vaxis-1220de23a3240e503397ea579de4fd85db422f537e10036ef74717c50164475813ce.tar.gz]='https://github.com/rockorager/libvaxis/archive/refs/tags/v0.5.1.tar.gz'
	[zg-122055beff332830a391e9895c044d33b15ea21063779557024b46169fb1984c6e40.tar.gz]='https://codeberg.org/atman/zg/archive/v0.13.2.tar.gz'
	[zig-aio-1220a55aedabdd10578d0c514719ea39ae1bc6d7ed990f508dc100db7f0ccf391437.tar.gz]='https://github.com/Cloudef/zig-aio/archive/b5a407344379508466c5dcbe4c74438a6166e2ca.tar.gz'
	[zigimg-1220dd654ef941fc76fd96f9ec6adadf83f69b9887a0d3f4ee5ac0a1a3e11be35cf5.tar.gz]='https://github.com/zigimg/zigimg/archive/3a667bdb3d7f0955a5a51c8468eac83210c1439e.tar.gz'
	[zigwin32-1220da4cab188b7b0e351de67626ca0dcadceddd16ca5997cfb578697f0525a59dac.tar.gz]='https://github.com/marlersoft/zigwin32/archive/4a78e716ae6496f52d9ddaf4fda2c4bb692631cd.tar.gz'
)

ZIG_SLOT="0.13"
inherit zig

SRC_URI="
	[Write manually main download URL of your package here]
	${ZBS_DEPENDENCIES_SRC_URI}
"

# List licenses by yourself
# LICENSE=""
SLOT="0"
KEYWORDS="~amd64"

src_configure() {
	local my_zbs_args=(
		# Here you have list of options that are exposed by build.zig,
		# pass USE flags and default values here.

		# pie: Build a Position Independent Executable
		# with_tui: Build TUI

		# -Dpie=[bool]
		# -Dwith_tui=[bool]
	)

	zig_src_configure
}

<path-to-project> is a build.zig file or directory containing it. If it is not set, current directory will be used.

zig-ebuilder will also try to find build.zig.zon file nearby.

You can also check most important options below, to check all of them see --help output:

--zig: Specify Zig executable to use for zig fetch and zig build. Default is to use zig from PATH.

--fetch: Choose fetch mode:

• none: skip all fetching. Dependencies will not be parsed in this case.
• plain: (default) fetch all dependencies.
• hashed: use optimized fetching from https://github.com/ziglang/zig/pull/21589, Zig needs to be patched before.

--zig-build-args: pass additional args to zig build. Useful if you need to pull step config which depends on some conflicting user option, or if some option is required and have no default:

$ zig-ebuilder . --zig-build-args -Dbackend=x11
$ zig-ebuilder . --zig-build-args -Dbackend=wayland
$ zig-ebuilder . --zig-build-args -Dbackend=arcan

--template: Specify file with custom ZTL template.

Licenses

This project is REUSE-compliant, text of licenses can be found in LICENSES directory. Short overview:

• Generator itself is licensed under EUPL-1.2.
• Some snippets from Zig upstream and modified build runners are licensed under upstream MIT.
• build.zig, build.zig.zon and default ZTL templates are licensed under 0BSD.
• This README and CI files are licensed under CC0-1.

Comparison of used licenses.