ZIG-UTILS.ECLASS

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

NAME

zig-utils.eclass - Prepare Zig toolchain and set global variables

DESCRIPTION

Prepare Zig toolchain and set global variables. Supports Zig 0.13+. Does not set any default function, ebuilds must call them manually. Generally, only "zig-utils_setup" is needed.

Intended to be used by ebuilds that call "zig build-exe/lib/obj" or "zig test" directly and by "dev-lang/zig". For ebuilds with ZBS (Zig Build System), it's usually better to inherit zig.eclass instead, as it has default phases-functions.

SUPPORTED EAPIS

FUNCTIONS

zig-utils_c_env_to_zig_target <C-style target tuple> <CFLAGS>

Translates C-style target tuple (like CHOST) and CFLAGS to Zig-style target tuple. For full information "zig-utils_c_env_to_zig_cpu" is needed, because some information is located in different places in C and Zig, for example: * Moved from C target to Zig CPU: x86 and ARM families, * Moved from CFLAGS to Zig tuple: ARM Thumb mode.

Mostly used during cross-compilation to get target triple if user did not set ZIG_TARGET variable, and always during bootstraping Zig.

See ZIG_TARGET description for more information.

zig-utils_c_env_to_zig_cpu <C-style target tuple> <CFLAGS>

Translates C-style target tuple (like CHOST) and CFLAGS to Zig-style target CPU and features. For full information "zig-utils_c_env_to_zig_target" is needed, because some information is located in different places in C and Zig, for example: * Moved from C target to Zig CPU: x86 and ARM families, * Moved from CFLAGS to Zig tuple: ARM Thumb mode.

Used to get target CPU if user did not set ZIG_CPU variable.

See ZIG_CPU description for more information.

zig-utils_find_installation

Detects suitable Zig installation and sets ZIG_VER and ZIG_EXE variables.

See ZIG_EXE and ZIG_VER descriptions for more information.

zig-utils_setup

Checks if running Linux kernel version is supported by Zig. Populates ZIG_TARGET, ZIG_CPU, ZIG_EXE and ZIG_VER global variables with detected values, or, if user set them already, leaves as-is.

ezig [<args>...]

Runs ZIG_EXE with supplied arguments. Dies if ZIG_EXE is not set or if command exits with error. Respects `nonfatal`.

Always disables progress tree. By default enables ANSI escape codes (colors, etc.), user can set NO_COLOR environment variable to disable them.

Note that color support also determines how compile errors will be printed: source code lines and reference traces are not available when colors are disabled.

ECLASS VARIABLES

ZIG_SLOT (REQUIRED) (SET BEFORE INHERIT)

Zig slot that will be used in "ezig" function. Also, if ZIG_OPTIONAL is empty, adds dev-lang/zig and dev-lang/zig-bin dependency to BDEPEND. Must be >= "0.13".

Example: ZIG_SLOT="0.13"

When a new Zig release occurs, it is advisable for maintainers to check whether their ebuild supports that new version. If yes, they they should bump ZIG_SLOT to the latest version; if not supported, they need to patch any issues with new version and again bump ZIG_SLOT. This helps to reduce dependencies on outdated Zig versions.

This policy of "1 exclusive Zig slot" will work until it stabilizes enough (probably near 1.0), then it will be re-evaluated and most likely changed to more common in other eclasses ZIG_MIN/ ZIG_MAX form.

ZIG_NEEDS_LLVM (SET BEFORE INHERIT)

If set to a non-empty value, the package will BDEPEND on a Zig package with LLVM enabled. This is currently required for packages that require C/C++ source files to be compiled with Zig.

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-utils.eclass users: You have to add Zig dependency in your BDEPEND manually and call at least "zig-utils_setup" before using "ezig".

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

ZIG_TARGET

Zig target tuple to use. Has the following format: arch-os[.os_version_range]-abi[.abi_version] Can be passed as: * "-target " option in "zig test" or "zig build-exe/lib/obj", * "-Dtarget=" option in "zig build"
(if project uses "std.Build.standardTargetOptions").

Can be set by user in make.conf. If not set, then auto-generated by "zig-utils_setup".

Example: # Autodetected by Zig: ZIG_TARGET="native" # Machine running Linux x86_64 system, with glibc: ZIG_TARGET="x86_64-linux-gnu" # Similar to above, but versions are passed explicitly: ZIG_TARGET="x86_64-linux.6.1.12...6.6.16-gnu.2.38" # Machine running Linux PPC64 little-endian system, with musl ZIG_TARGET="powerpc64le-linux-musl"

Note for eclass users: it is discouraged to overwrite ZIG_TARGET value by ebuilds. In most cases, if you need to hardcode value for -Dtarget, it's better to change "build.zig" code instead to use appropriate values. For example, if some build-time executable intented for host is compiled for cross-platform target, change in build.zig "target" for that executable to be "b.graph.host".

In rare cases, if you really need to hardcode ZIG_TARGET, use this syntax before calling `zig-utils_setup` (or `zig_pkg_setup`) to allow user override: pkg_setup() { : "${ZIG_TARGET:=aarch64-freestanding-none}"
zig_pkg_setup
}

ZIG_CPU

Zig target CPU and features to use. Has the following format: family_name(+enable_feature|-disable_feature)* Can be passed as: * "-mcpu " option in "zig test" or "zig build-exe/lib/obj", * "-Dcpu=" option in "zig build"
(if project uses "std.Build.standardTargetOptions").

Can be set by user in make.conf. If not set, then auto-generated by "zig-utils_setup".

Example: # Autodetected by Zig: ZIG_CPU="native" # AMD Zen 2 processor ZIG_CPU="znver2" # x86_64 processor, X87 support enabled, SSE2 support disabled ZIG_CPU="x86_64+x87-sse2"

Note for eclass users: it is discouraged to overwrite ZIG_CPU value by ebuilds. In most cases, if you need to hardcode value for -Dcpu, it's better to change "build.zig" code instead to use appropriate values. For example, if some build-time executable intented for host is compiled for cross-platform target, change in build.zig "target" for that executable to be "b.graph.host".

In rare cases, if you really need to hardcode ZIG_CPU, use this syntax before calling `zig-utils_setup` (or `zig_pkg_setup`) to allow user override: pkg_setup() { : "${ZIG_CPU:=apple_m1}"
zig_pkg_setup
}

ZIG_EXE (GENERATED BY ECLASS)

Absolute path to the used Zig executable. Set by "zig-utils_setup"/"zig-utils_find_installation".

Please note that when passing one flag several times with different values: * (only "zig build") in "-Dbar=false -Dbar" form:
  errors due to conflict of flags, * (only "zig build") in "-Dbar=false -Dbar=true" form:
  "bar" becomes a list, which is likely not what you want, * in "-fbar -fno-bar" form:
  latest value overwrites values before. Example above shows only boolean option, but it is same with other types of options (enums, "std.zig.BuildId", "std.SemanticVersion", integers, strings, etc.).

ZIG_VER (GENERATED BY ECLASS)

Zig version as reported in dev-lang/zig-${PV} PV part. Set by "zig-utils_setup"/"zig-utils_find_installation".

Example: 0.13.0

AUTHORS

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-utils.eclass

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