rules.md

Rules to build and run Zig code.

Note, all Zig targets implicitly depend on an automatically generated Zig module called bazel_builtin that exposes Bazel specific information such as the current target name or current repository name.

zig_binary

zig_binary(name, deps, srcs, data, cdeps, copts, csrcs, env, extra_docs, extra_srcs, linker_script,
           main)

Builds a Zig binary.

The target can be built using bazel build, corresponding to zig build-exe, and executed using bazel run, corresponding to zig run.

Documentation can be generated by requesting the zig_docs output group, e.g. using the command bazel build //my:target --output_groups=zig_docs.

EXAMPLE

load("@rules_zig//zig:defs.bzl", "zig_binary")

zig_binary(
    name = "my-binary",
    main = "main.zig",
    srcs = [
        "utils.zig",  # to support `@import("utils.zig")`.
    ],
    deps = [
        ":my-module",  # to support `@import("my-module")`.
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	modules required to build the target.	List of labels	optional	[]
srcs	Other Zig source files required to build the target, e.g. files imported using @import.	List of labels	optional	[]
data	Files required by the target during runtime.	List of labels	optional	[]
cdeps	C dependencies providing headers to include and libraries to link against, typically cc_library targets. Note, if you need to include C or C++ standard library headers and encounter errors of the following form: note: libc headers not available; compilation does not link against libc error: 'math.h' file not found Then you may need to list @rules_zig//zig/lib:libc or @rules_zig//zig/lib:libc++ in this attribute.	List of labels	optional	[]
copts	C compiler flags required to build the C sources of the target. Subject to location expansion.	List of strings	optional	[]
csrcs	C source files required to build the target.	List of labels	optional	[]
env	Additional environment variables to set when executed by bazel run. Subject to location expansion. NOTE: The environment variables are not set when you run the target outside of Bazel (for example, by manually executing the binary in bazel-bin/).	Dictionary: String -> String	optional	{}
extra_docs	Other files required to generate documentation, e.g. guides referenced using //!zig-autodoc-guide:.	List of labels	optional	[]
extra_srcs	Other files required to build the target, e.g. files embedded using @embedFile.	List of labels	optional	[]
linker_script	Custom linker script for the target.	Label	optional	None
main	The main source file.	Label	required

zig_configure

zig_configure(name, actual, mode, target, threaded, zig_version)

Transitions a target and its dependencies to a different configuration.

Settings like the build mode, e.g. ReleaseSafe, or the target platform, can be set on the command-line on demand, e.g. using --@rules_zig//zig/settings:mode=release_safe.

However, you may wish to always build a given target in a particular configuration, or you may wish to build a given target in multiple configurations in a single build, e.g. to generate a multi-platform release bundle.

Use this rule to that end.

You can read more about Bazel configurations and transitions here.

EXAMPLE

load(
    "@rules_zig//zig:defs.bzl",
    "zig_binary",
    "zig_configure",
)

zig_library(
    name = "library",
    main = "library.zig",
    tags = ["manual"],  # optional, exclude from `bazel build //...`.
)

zig_configure(
    name = "library_debug",
    actual = ":library",
    mode = "debug",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
actual	The target to transition.	Label	required
mode	The build mode setting, corresponds to the -O Zig compiler flag.	String	optional	""
target	The target platform, expects a label to a Bazel target platform used to select a zig_target_toolchain instance.	Label	optional	None
threaded	The threaded setting, corresponds to the -fsingle-threaded Zig compiler flag.	String	optional	""
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""

zig_configure_binary

zig_configure_binary(name, actual, mode, target, threaded, zig_version)

Transitions a target and its dependencies to a different configuration.

Settings like the build mode, e.g. ReleaseSafe, or the target platform, can be set on the command-line on demand, e.g. using --@rules_zig//zig/settings:mode=release_safe.

However, you may wish to always build a given target in a particular configuration, or you may wish to build a given target in multiple configurations in a single build, e.g. to generate a multi-platform release bundle.

Use this rule to that end.

You can read more about Bazel configurations and transitions here.

EXAMPLE

load(
    "@rules_zig//zig:defs.bzl",
    "zig_binary",
    "zig_configure_binary",
)

zig_binary(
    name = "binary",
    main = "main.zig",
    tags = ["manual"],  # optional, exclude from `bazel build //...`.
)

zig_configure_binary(
    name = "binary_debug",
    actual = ":binary",
    mode = "debug",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
actual	The target to transition.	Label	required
mode	The build mode setting, corresponds to the -O Zig compiler flag.	String	optional	""
target	The target platform, expects a label to a Bazel target platform used to select a zig_target_toolchain instance.	Label	optional	None
threaded	The threaded setting, corresponds to the -fsingle-threaded Zig compiler flag.	String	optional	""
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""

zig_configure_test

zig_configure_test(name, actual, mode, target, threaded, zig_version)

Transitions a target and its dependencies to a different configuration.

Settings like the build mode, e.g. ReleaseSafe, or the target platform, can be set on the command-line on demand, e.g. using --@rules_zig//zig/settings:mode=release_safe.

However, you may wish to always build a given target in a particular configuration, or you may wish to build a given target in multiple configurations in a single build, e.g. to generate a multi-platform release bundle.

Use this rule to that end.

You can read more about Bazel configurations and transitions here.

EXAMPLE

load(
    "@rules_zig//zig:defs.bzl",
    "zig_test",
    "zig_configure_test",
)

zig_test(
    name = "test",
    main = "test.zig",
    tags = ["manual"],  # optional, exclude from `bazel build //...`.
)

zig_configure_test(
    name = "test_debug",
    actual = ":test",
    mode = "debug",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
actual	The target to transition.	Label	required
mode	The build mode setting, corresponds to the -O Zig compiler flag.	String	optional	""
target	The target platform, expects a label to a Bazel target platform used to select a zig_target_toolchain instance.	Label	optional	None
threaded	The threaded setting, corresponds to the -fsingle-threaded Zig compiler flag.	String	optional	""
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""

zig_library

zig_library(name, deps, srcs, data, cdeps, copts, csrcs, extra_docs, extra_srcs, linker_script,
            main)

Builds a Zig library.

The target can be built using bazel build, corresponding to zig build-lib.

Documentation can be generated by requesting the zig_docs output group, e.g. using the command bazel build //my:target --output_groups=zig_docs.

EXAMPLE

load("@rules_zig//zig:defs.bzl", "zig_library")

zig_library(
    name = "my-library",
    main = "main.zig",
    srcs = [
        "utils.zig",  # to support `@import("utils.zig")`.
    ],
    deps = [
        ":my-module",  # to support `@import("my-module")`.
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	modules required to build the target.	List of labels	optional	[]
srcs	Other Zig source files required to build the target, e.g. files imported using @import.	List of labels	optional	[]
data	Files required by the target during runtime.	List of labels	optional	[]
cdeps	C dependencies providing headers to include and libraries to link against, typically cc_library targets. Note, if you need to include C or C++ standard library headers and encounter errors of the following form: note: libc headers not available; compilation does not link against libc error: 'math.h' file not found Then you may need to list @rules_zig//zig/lib:libc or @rules_zig//zig/lib:libc++ in this attribute.	List of labels	optional	[]
copts	C compiler flags required to build the C sources of the target. Subject to location expansion.	List of strings	optional	[]
csrcs	C source files required to build the target.	List of labels	optional	[]
extra_docs	Other files required to generate documentation, e.g. guides referenced using //!zig-autodoc-guide:.	List of labels	optional	[]
extra_srcs	Other files required to build the target, e.g. files embedded using @embedFile.	List of labels	optional	[]
linker_script	Custom linker script for the target.	Label	optional	None
main	The main source file.	Label	required

zig_module

zig_module(name, deps, srcs, data, extra_srcs, main)

Defines a Zig module.

A Zig module is a collection of Zig sources with a main source file that defines the module's entry point.

This rule does not perform compilation by itself. Instead, modules are compiled at the use-site. Zig performs whole program compilation.

EXAMPLE

load("@rules_zig//zig:defs.bzl", "zig_module")

zig_module(
    name = "my-module",
    main = "main.zig",
    srcs = [
        "utils.zig",  # to support `@import("utils.zig")`.
    ],
    deps = [
        ":other-module",  # to support `@import("other-module")`.
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other modules required when building the module.	List of labels	optional	[]
srcs	Other Zig source files required when building the module, e.g. files imported using @import.	List of labels	optional	[]
data	Files required by the module during runtime.	List of labels	optional	[]
extra_srcs	Other files required when building the module, e.g. files embedded using @embedFile.	List of labels	optional	[]
main	The main source file.	Label	required

zig_shared_library

zig_shared_library(name, deps, srcs, data, cdeps, copts, csrcs, extra_docs, extra_srcs,
                   linker_script, main)

Builds a Zig shared library.

The target can be built using bazel build, corresponding to zig build-lib.

EXAMPLE

load("@rules_zig//zig:defs.bzl", "zig_shared_library")

zig_shared_library(
    name = "my-library",
    main = "main.zig",
    srcs = [
        "utils.zig",  # to support `@import("utils.zig")`.
    ],
    deps = [
        ":my-module",  # to support `@import("my-module")`.
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	modules required to build the target.	List of labels	optional	[]
srcs	Other Zig source files required to build the target, e.g. files imported using @import.	List of labels	optional	[]
data	Files required by the target during runtime.	List of labels	optional	[]
cdeps	C dependencies providing headers to include and libraries to link against, typically cc_library targets. Note, if you need to include C or C++ standard library headers and encounter errors of the following form: note: libc headers not available; compilation does not link against libc error: 'math.h' file not found Then you may need to list @rules_zig//zig/lib:libc or @rules_zig//zig/lib:libc++ in this attribute.	List of labels	optional	[]
copts	C compiler flags required to build the C sources of the target. Subject to location expansion.	List of strings	optional	[]
csrcs	C source files required to build the target.	List of labels	optional	[]
extra_docs	Other files required to generate documentation, e.g. guides referenced using //!zig-autodoc-guide:.	List of labels	optional	[]
extra_srcs	Other files required to build the target, e.g. files embedded using @embedFile.	List of labels	optional	[]
linker_script	Custom linker script for the target.	Label	optional	None
main	The main source file.	Label	required

zig_test

zig_test(name, deps, srcs, data, cdeps, copts, csrcs, env, env_inherit, extra_docs, extra_srcs,
         linker_script, main)

Builds a Zig test.

The target can be executed using bazel test, corresponding to zig test.

Documentation can be generated by requesting the zig_docs output group, e.g. using the command bazel build //my:target --output_groups=zig_docs.

EXAMPLE

load("@rules_zig//zig:defs.bzl", "zig_test")

zig_test(
    name = "my-test",
    main = "test.zig",
    srcs = [
        "utils.zig",  # to support `@import("utils.zig")`.
    ],
    deps = [
        ":my-module",  # to support `@import("my-module")`.
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	modules required to build the target.	List of labels	optional	[]
srcs	Other Zig source files required to build the target, e.g. files imported using @import.	List of labels	optional	[]
data	Files required by the target during runtime.	List of labels	optional	[]
cdeps	C dependencies providing headers to include and libraries to link against, typically cc_library targets. Note, if you need to include C or C++ standard library headers and encounter errors of the following form: note: libc headers not available; compilation does not link against libc error: 'math.h' file not found Then you may need to list @rules_zig//zig/lib:libc or @rules_zig//zig/lib:libc++ in this attribute.	List of labels	optional	[]
copts	C compiler flags required to build the C sources of the target. Subject to location expansion.	List of strings	optional	[]
csrcs	C source files required to build the target.	List of labels	optional	[]
env	Additional environment variables to set when executed by bazel run or bazel test. Subject to location expansion.	Dictionary: String -> String	optional	{}
env_inherit	Environment variables to inherit from external environment when executed by bazel test.	List of strings	optional	[]
extra_docs	Other files required to generate documentation, e.g. guides referenced using //!zig-autodoc-guide:.	List of labels	optional	[]
extra_srcs	Other files required to build the target, e.g. files embedded using @embedFile.	List of labels	optional	[]
linker_script	Custom linker script for the target.	Label	optional	None
main	The main source file.	Label	required