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

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

zig_binary(name, deps, srcs, data, compiler_runtime, copts, csrcs, env, extra_docs, extra_srcs,
           linker_script, linkopts, main, strip_debug_symbols, zigopts)

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	The list of other modules or C/C++ libraries that the library target depends upon.	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	[]
compiler_runtime	Whether to include Zig compiler runtime symbols in the generated output. The default behavior is to include them in executables and shared libraries.	String	optional	"default"
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. Note, as of Zig version 0.15.1 linker-scripts require the LLVM/LLD backend to be enabled, see ziglang/zig#25069. Set zigopts=["-fllvm", "-flld"] to that end.	Label	optional	None
linkopts	Additional list of flags passed to the linker. Subject to location expansion.	List of strings	optional	[]
main	The main source file. If not set, deps must contain exactly one Zig module dependency which will be used as the root module. Note that in that case, 'srcs', 'extra_srcs' and 'csrcs' must also be empty as they are taken from the root module instead.	Label	optional	None
strip_debug_symbols	Whether to pass '-fstrip' to the zig compiler to remove debug symbols.	Boolean	optional	False
zigopts	Additional list of flags passed to the zig compiler. Subject to location expansion. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_c_library

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

zig_c_library(name, data, cdeps, import_name)

Defines a Zig C module.

A Zig C module is a Zig module whose C headers dependencies have been translated to zig using translate-c, and which only output defines the module's entry point.

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

EXAMPLE

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

zig_c_library(
    name = "my-module",
    cdeps = [
        ":cc-library",
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Files required by the module during runtime.	List of labels	optional	[]
cdeps	C dependencies to translate their headers from.	List of labels	required
import_name	The import name of the module.	String	optional	""

zig_configure

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

zig_configure(name, actual, extra_toolchains, mode, target, threaded, use_cc_common_link,
              zig_version, zigopt)

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_static_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
extra_toolchains	Additional toolchains to consider during toolchain resolution for the transitioned target.	List of labels	optional	[]
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	""
use_cc_common_link	Whether to use cc_common.link to link zig binaries, tests and shared libraries. Possible values: [-1, 0, 1]. -1 means use current configuration value for //zig/settings:experimental_use_cc_common_link. 0 means do not use cc_common.link (use zig build-exe instead). 1 means use cc_common.link.	Integer	optional	-1
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""
zigopt	Additional list of flags passed to the zig compiler for all Zig compile actions. The flags specified by this setting do not override those specified via the zigopts attribute of zig_* rules. Instead, they are prepended to the command line before module specific flags. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_configure_binary

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

zig_configure_binary(name, actual, extra_toolchains, mode, target, threaded, use_cc_common_link,
                     zig_version, zigopt)

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
extra_toolchains	Additional toolchains to consider during toolchain resolution for the transitioned target.	List of labels	optional	[]
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	""
use_cc_common_link	Whether to use cc_common.link to link zig binaries, tests and shared libraries. Possible values: [-1, 0, 1]. -1 means use current configuration value for //zig/settings:experimental_use_cc_common_link. 0 means do not use cc_common.link (use zig build-exe instead). 1 means use cc_common.link.	Integer	optional	-1
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""
zigopt	Additional list of flags passed to the zig compiler for all Zig compile actions. The flags specified by this setting do not override those specified via the zigopts attribute of zig_* rules. Instead, they are prepended to the command line before module specific flags. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_configure_test

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

zig_configure_test(name, actual, extra_toolchains, mode, target, threaded, use_cc_common_link,
                   zig_version, zigopt)

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
extra_toolchains	Additional toolchains to consider during toolchain resolution for the transitioned target.	List of labels	optional	[]
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	""
use_cc_common_link	Whether to use cc_common.link to link zig binaries, tests and shared libraries. Possible values: [-1, 0, 1]. -1 means use current configuration value for //zig/settings:experimental_use_cc_common_link. 0 means do not use cc_common.link (use zig build-exe instead). 1 means use cc_common.link.	Integer	optional	-1
zig_version	The Zig SDK version, must be registered using the zig module extension.	String	optional	""
zigopt	Additional list of flags passed to the zig compiler for all Zig compile actions. The flags specified by this setting do not override those specified via the zigopts attribute of zig_* rules. Instead, they are prepended to the command line before module specific flags. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_library

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

zig_library(name, deps, srcs, data, extra_srcs, import_name, main, zigopts)

Defines a Zig library.

A Zig library 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_library")

zig_library(
    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	[]
import_name	The import name of the module.	String	optional	""
main	The main source file.	Label	required
zigopts	Additional list of flags passed to the zig compiler for this module. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_shared_library

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

zig_shared_library(name, deps, srcs, data, compiler_runtime, copts, csrcs, extra_docs, extra_srcs,
                   linker_script, linkopts, main, shared_lib_name, strip_debug_symbols, zigopts)

Builds a Zig shared library, produces a shared or dynamic library.

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

Suitable as a dependency to C/C++ targets.

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_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	The list of other modules or C/C++ libraries that the library target depends upon.	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	[]
compiler_runtime	Whether to include Zig compiler runtime symbols in the generated output. The default behavior is to include them in executables and shared libraries.	String	optional	"default"
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. Note, as of Zig version 0.15.1 linker-scripts require the LLVM/LLD backend to be enabled, see ziglang/zig#25069. Set zigopts=["-fllvm", "-flld"] to that end.	Label	optional	None
linkopts	Additional list of flags passed to the linker. Subject to location expansion.	List of strings	optional	[]
main	The main source file. If not set, deps must contain exactly one Zig module dependency which will be used as the root module. Note that in that case, 'srcs', 'extra_srcs' and 'csrcs' must also be empty as they are taken from the root module instead.	Label	optional	None
shared_lib_name	-	String	optional	""
strip_debug_symbols	Whether to pass '-fstrip' to the zig compiler to remove debug symbols.	Boolean	optional	False
zigopts	Additional list of flags passed to the zig compiler. Subject to location expansion. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_static_library

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

zig_static_library(name, deps, srcs, data, compiler_runtime, copts, csrcs, extra_docs, extra_srcs,
                   linker_script, linkopts, main, strip_debug_symbols, zigopts)

Builds a Zig library, produces a static archive.

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

Suitable as a dependency to C/C++ targets.

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_static_library")

zig_static_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	The list of other modules or C/C++ libraries that the library target depends upon.	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	[]
compiler_runtime	Whether to include Zig compiler runtime symbols in the generated output. The default behavior is to include them in executables and shared libraries.	String	optional	"default"
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. Note, as of Zig version 0.15.1 linker-scripts require the LLVM/LLD backend to be enabled, see ziglang/zig#25069. Set zigopts=["-fllvm", "-flld"] to that end.	Label	optional	None
linkopts	Additional list of flags passed to the linker. Subject to location expansion.	List of strings	optional	[]
main	The main source file. If not set, deps must contain exactly one Zig module dependency which will be used as the root module. Note that in that case, 'srcs', 'extra_srcs' and 'csrcs' must also be empty as they are taken from the root module instead.	Label	optional	None
strip_debug_symbols	Whether to pass '-fstrip' to the zig compiler to remove debug symbols.	Boolean	optional	False
zigopts	Additional list of flags passed to the zig compiler. Subject to location expansion. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]

zig_test

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

zig_test(name, deps, srcs, data, compiler_runtime, copts, csrcs, env, env_inherit, extra_docs,
         extra_srcs, linker_script, linkopts, main, strip_debug_symbols, test_runner, zigopts)

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	The list of other modules or C/C++ libraries that the library target depends upon.	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	[]
compiler_runtime	Whether to include Zig compiler runtime symbols in the generated output. The default behavior is to include them in executables and shared libraries.	String	optional	"default"
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. Note, as of Zig version 0.15.1 linker-scripts require the LLVM/LLD backend to be enabled, see ziglang/zig#25069. Set zigopts=["-fllvm", "-flld"] to that end.	Label	optional	None
linkopts	Additional list of flags passed to the linker. Subject to location expansion.	List of strings	optional	[]
main	The main source file. If not set, deps must contain exactly one Zig module dependency which will be used as the root module. Note that in that case, 'srcs', 'extra_srcs' and 'csrcs' must also be empty as they are taken from the root module instead.	Label	optional	None
strip_debug_symbols	Whether to pass '-fstrip' to the zig compiler to remove debug symbols.	Boolean	optional	False
test_runner	Optional Zig file to specify a custom test runner	Label	optional	None
zigopts	Additional list of flags passed to the zig compiler. Subject to location expansion. This is an advanced feature that can conflict with attributes, build settings, and other flags defined by the toolchain itself. Use this at your own risk of hitting undefined behaviors.	List of strings	optional	[]