Get Gentoo!
Development Guide
  1. Master index
  2. Eclass reference

zig-utils.eclass

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

8

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.

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/