Skip to content

toolchains.md

Latest commit

 

History

History
138 lines (94 loc) · 6.07 KB

toolchains.md

File metadata and controls

138 lines (94 loc) · 6.07 KB

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