toolchains.md

Rules to declare Zig toolchains.

zig_path_toolchain

load("@rules_zig//zig:toolchain.bzl", "zig_path_toolchain")

zig_path_toolchain(name, zig_cache, zig_exe_path, zig_lib_path, zig_version)

Defines a non-hermetic Zig compiler toolchain from absolute paths.

Use this rule when Zig is installed outside Bazel and cannot be exposed as Bazel files. The executable and library directory paths must be absolute and available on every execution machine that can run actions using this toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
zig_cache	The Zig cache directory prefix. Used for both the global and local cache.	String	required
zig_exe_path	Absolute path to an existing Zig executable for the target platform.	String	required
zig_lib_path	Absolute path to an existing Zig library directory for the target platform.	String	required
zig_version	The Zig toolchain's version.	String	required

zig_target_toolchain

load("@rules_zig//zig:toolchain.bzl", "zig_target_toolchain")

zig_target_toolchain(name, dynamic_linker, target)

Defines a Zig target configuration toolchain.

The Zig compiler toolchain, defined by the zig_toolchain rule, has builtin cross-compilation support. Meaning, most Zig toolchains can target any platform supported by Zig independent of the execution platform.

Therefore, there is no need to couple the execution platform with the target platform, at least not by default.

Use this rule to configure a Zig target platform and declare the corresponding Bazel target platform constraints using the builtin toolchain rule.

Use the target @rules_zig//zig/target:resolved_toolchain to access the resolved toolchain for the current target platform. You can build this target to obtain a JSON file capturing the relevant Zig compiler flags.

See https://bazel.build/extending/toolchains#defining-toolchains.

EXAMPLE

zig_target_toolchain(
    name = "x86_64-linux",
    target = "x86_64-linux",
)

toolchain(
    name = "x86_64-linux_toolchain",
    target_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":x86_64-linux",
    toolchain_type = "@rules_zig//zig/target:toolchain_type",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
dynamic_linker	The value of the --dynamic-linker flag.	String	optional	""
target	The value of the -target flag.	String	required

zig_toolchain

load("@rules_zig//zig:toolchain.bzl", "zig_toolchain")

zig_toolchain(name, zig_cache, zig_exe, zig_h, zig_lib, zig_version)

Defines a Zig compiler toolchain.

The Zig compiler toolchain, defined by the zig_toolchain rule, has builtin cross-compilation support. Meaning, most Zig toolchains can target any platform supported by Zig independent of the execution platform.

Therefore, there is no need to couple the execution platform with the target platform, at least not by default.

This rule configures a Zig compiler toolchain and the corresponding Bazel execution platform constraints can be declared using the builtin toolchain rule.

You will rarely need to invoke this rule directly. Instead, use the zig module extension provided by @rules_zig//zig:extensions.bzl.

Use the target @rules_zig//zig:resolved_toolchain to access the resolved toolchain for the current execution platform.

See https://bazel.build/extending/toolchains#defining-toolchains.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
zig_cache	The Zig cache directory prefix. Used for both the global and local cache.	String	required
zig_exe	A hermetically downloaded Zig executable for the target platform.	Label	required
zig_h	The Zig header at the root of the Zig library directory.	Label	required
zig_lib	A source directory containing the hermetic Zig library for the target platform.	Label	required
zig_version	The Zig toolchain's version.	String	required