ZIG.ECLASS

Section: eclass-manpages (5)
Updated: Mar 2025
Index Return to Main Contents

NAME

zig.eclass - Functions for working with ZBS (Zig Build System)

DESCRIPTION

Functions for working with Zig build system and package manager. Supports Zig 0.13+. Exports default functions for convenience.

Note that zig.eclass is mostly tailored for projects that: 1) Install something in build.zig steps: "artifacts" (executable, libraries, objects), source codes, assets, tests, scripts etc. But many authors also use it to write Zig "modules", build logic and/or bindings/wrappers for C/C++ libraries. They install nothing and are only used at build-time, so it's unneccessary and mostly useless to make ebuilds for them. 2) Have required `target`, `cpu` and optional `optimize` options in build.zig that accept standard Zig-style target and optimize mode. They are usually created by calling `b.standardTargetOptions` and `b.standardOptimizeOption` functions.

For end-user executables, usually it's recommended to patch to call these options and upstream it, but in some cases authors have good reasons to not have them, f.e. if it is built only for WASM platform with ReleaseSmall, and is not intended to run in /usr/bin/. In this case, declare dummy options using `b.option` and ignore their values, or else eclass wouldn't work.

Another case is when upstream has `target` option but it has custom format and does not accept usual Zig targets, but rather something specific to the project like "linux-baseline-lts", or combine CPU and target in one option. In this case, it's best to rename that option to something like `target-custom`, then declare `target` option and make converter from one value to other.

For non-executable binaries like C libraries, objects etc. our policy is stricter, all 3 options are required and should not be ignored, with no exceptions.

SUPPORTED EAPIS

TRANSITIVELY PROVIDED ECLASSES

zig-utils

FUNCTIONS

zig_get_jobs

Returns number of jobs from ZBS_ARGS_EXTRA or MAKEOPTS. If there is none, defaults to number of available processing units.

zig_init_base_args

Stores basic args for future "ezig build" calls in ZBS_ARGS_BASE. Package manager option is managed by "zig_src_prepare", ebuild and user options are added by "zig_src_configure".

This function is used by "zig_pkg_setup", and it is neccessary that args are available as early as possible, so that ebuilds could use them in steps like "src_unpack" if neccessary, while still having verbosity and amount of jobs from user respected.

TODO: currently this function enables "--search-prefix" (1) and "--sysroot" (2) only when cross-compiling, should be fixed to unconditionally enabling it.

For solving (1) this patch should be reworked and upstreamed: https://paste.sr.ht/~bratishkaerik/2ddffe2bf0f8f9d6dfb60403c2e9560334edaa88

(2) "--sysroot" should be passed together with "--search-prefix" above, if we pass only "--sysroot" it gives these errors: error: unable to find dynamic system library 'zstd' using strategy 'paths_first'. searched paths: none

zig_pkg_setup

Sets up environmental variables for Zig toolchain and basic args for Zig Build System.

zig_live_fetch [<args>...]

Fetches packages, if they exist, to the "ZBS_ECLASS_DIR/p/". Adds build file path to ZBS_BASE_ARGS. If you have some lazy dependency which is not triggered in default configuration, pass options like you would pass them for regular "ezig build". Try to cover all of them before "src_configure". **Note**: this function will be deprecated once/if https://github.com/ziglang/zig/pull/19975 lands.

Example: src_unpack() { # If there are no lazy dependency:
zig_live_fetch

# If there are lazy dependencies that can be triggered together:
zig_live_fetch -Denable-wayland -Denable-xwayland

        # If there are 2 lazy dependencies that can't be triggered
        # together in one call because they conflict:
        zig_live_fetch -Dmain-backend=opengl
        zig_live_fetch -Dmain-backend=vulkan
}

zig_src_unpack

Unpacks every archive in SRC_URI and ZBS_DEPENDENCIES, in that order. Adds build file path to ZBS_BASE_ARGS.

zig_src_prepare

Calls default "src_prepare" function, creates BUILD_DIR directory and enables system mode (by adding to ZBS_BASE_ARGS).

System mode is toggled here and not in "src_unpack" because they could have been fetched by "live_fetch" in live ebuilds instead.

zig_src_configure

Creates ZBS_ARGS array which can be used in all future phases, by combining ZBS_ARGS_BASE set previously, my_zbs_args from ebuild, and ZBS_ARGS_EXTRA by user, in this order.

Specific flags currently only add support for the cross-compilation. They are likely to be extended in the future.

zig_src_compile [<args>...]

Calls "ezig build" with previously set ZBS_ARGS. Args passed to this function will be passed after ZBS_ARGS. They can be used to call custom steps or override some options temporarily like `--prefix`. Note that `--prefix` and other relative arguments will process here as relative to BUILD_DIR.

zig_src_test [<args>...]

If "test" step exist, calls "ezig build test" with previously set ZBS_ARGS. Args passed to this function will be passed after ZBS_ARGS. Note: currently step detection might give false positives in very rare cases, it will be improved in the future. Note that `--prefix` and other relative arguments will process here as relative to BUILD_DIR.

zig_src_install [<args>...]

Calls "ezig build" with DESTDIR and previously set ZBS_ARGS. Args passed to this function will be passed after ZBS_ARGS. Also installs documentation via "einstalldocs". Note that `--prefix` and other relative arguments will process here as relative to D.

ECLASS VARIABLES

ZIG_OPTIONAL (SET BEFORE INHERIT)

If set to a non-empty value, all logic in zig-utils and zig eclasses will be considered optional. No dependencies will be added and no phase functions will be exported.

For zig.eclass users: You need to add Zig and pkgconfig dependencies in your BDEPEND, set QA_FLAGS_IGNORED and call all phase functions manually. If you want to use "ezig build" directly, call "zig_pkg_setup" before it.

For zig-utils.eclass users: see documentation in zig-utils.eclass instead.

ZBS_DEPENDENCIES (SET BEFORE INHERIT)

Bash associative array with all tarballs that will be fetched by "ezig fetch" in zig_src_unpack phase. Value is URL where tarball is located, key is name under which it would be downloaded and renamed. So generally it has effect of "value -> key".

Note: if Zig Build System dependency can't be represented in SRC_URI (like direct Git commit URIs), you should do the following (zig-ebuilder does archiving automatically for you):
  1. Archive each folder with dependency content in some tarball,
     so f.e. if you have 2 Git dependencies, create 2 tarballs.
  2. Archive all previous tarballs into one combined tarball (also
     called tarball-tarball from now on), no subdirs, so that eclass
     can firstly unpack this tarball with "unpack",
     and secondly unpack its content with "zig fetch".
  3. (zig-ebuilder can't do this) Host this tarball somewhere
     and put URL of this tarball in SRC_URI, and archives in
     ZBS_DEPENDENCIES, keys must be names of archives, values empty.

Example: declare -r -A ZBS_DEPENDENCIES=( [tarball_a-<long-hash>.tar.gz]='URL_A'
[tarball_b-<long-hash>.tar.gz]='URL_B'

        # If there are Git dependencies:
        [git_c-<long-hash>.tar.gz]=''
        # Tarball-tarball should contain inside above tarball flatly.
)

ZBS_DEPENDENCIES_SRC_URI (GENERATED BY ECLASS)

Content of ZBS_DEPENDENCIES converted at inherit-time, to be used in SRC_URI. Note that elements with empty keys will be skipped. Example: SRC_URI=" <URL to project sources, patches, non-Zig resources etc.>

# If there are Git dependencies:
# <URL to tarball-tarball>

${ZBS_DEPENDENCIES_SRC_URI}
"

my_zbs_args

Bash array with ebuild-specified arguments to pass to the "zig build" after "src_configure". It's appended to the ZBS_ARGS during "src_configure". Note: if you need to override default optimize mode of this eclass (ReleaseSafe) with your default, please use "--release=small" etc. syntax so that user can still override it in ZBS_ARGS_EXTRA. Note: `--prefix` and other relative arguments will process here as relative to BUILD_DIR.

Example: src_configure() {         local my_zbs_args=(
                -Dpie=true
        )

zig_src_configure
}

ZBS_ARGS_EXTRA (USER VARIABLE)

Bash string with user-specified arguments to pass to the "zig build" after "src_configure". It's appended to the ZBS_ARGS during "zig_src_configure".

If this does not have amount of jobs, eclass will try to take amount of jobs from MAKEOPTS, and if it also does not have them, it will default to $(nproc).

Example: ZBS_ARGS_EXTRA="-j8 --release=small"

ZBS_VERBOSE ?= ON (USER VARIABLE)

If enabled, eclass will add "--summary all --verbose" options to "ezig build", so that it prints every command before executing, and summarry tree at the end of step. If not, will do nothing. Enabled by default. Set to OFF to disable these verbose messages.

Note: this variable does not control other options starting with "--verbose-", such as "--verbose-link" or "--verbose-cimport". If you need them, add them manually to ZBS_ARGS_EXTRA.

BUILD_DIR ?= ${WORKDIR}/${P}-build

Directory where all "ezig build" calls will be proceeded. Defaults to "${WORKDIR}/${P}-build" if not set.

ZBS_ECLASS_DIR ?= ${WORKDIR}/zig-eclass

Directory where various files used by this eclass are stored. They can be supplied by the ebuild or by eclass. Currently, it's used only for Zig packages, which are stored in "p/" subdirectory. Defaults to "${WORKDIR}/zig-eclass" if not set. Should be set before calling "zig_src_unpack" or "zig_live_fetch".

AUTHORS

Alfred Wingate <parona@protonmail.com>
Violet Purcell <vimproved@inventati.org>
Eric Joldasov <bratishkaerik@landless-city.net>

MAINTAINERS

Eric Joldasov <bratishkaerik@landless-city.net>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

zig.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, March 13, 2025