Planned Functionality

[aherrmann]

Compiler toolchain

Define the Zig compiler toolchain

• Download and register the latest Zig release for Linux #2
• Download and register any supported Zig release for all supported platforms #72
• Support Zig nightly releases. #76
• Support MacOS as host&exec platform #23
• Support a globally installed Zig compiler toolchain. #70
• Support a Nix provided Zig compiler toolchain. #71

Zig concepts and commands

Define build rules corresponding to Zig concepts and build commands taking the Starlark style guide into account

• zig_binary for zig build-exe
  • Define zig_binary for a single source Zig binary without dependencies #4
  • zig_binary should support a multi source Zig binary without dependencies #6
  • zig_binary should support a Zig binary with Zig package dependencies #9
  • zig_binary|library|test should support a Zig binary with library dependencies (.a, .so) #15
  • zig_binary|library|test should support other source inputs supported by zig build-exe #80
    (.o, .obj, .a, .lib, .so, .dll, .dylib, .s, .c, etc.)
  • Support arbitrary Zig compiler flags through a zigopts attribute. #83
  • Support extra source files / build inputs, e.g. for @embedFile. #93
• zig_package for zig ... --pkg-begin ... -pkg-end
  • Define zig_package to bundle Zig sources into a Zig package. #8
  • Support Zig packages depending on other Zig packages #11
  • Support Zig modules depending on libraries #230
• zig_library for zig build-lib
  • Define zig_library to generate a static C library (.a, .lib) #13
  • zig_library should be a valid dependency for cc-rules like cc_library. #14
  • zig_library should support generating a dynamic C library #16
• zig_test
  • Add zig_test rule to build and execute Zig test-suites. #18
    Note, zig test builds and executes Zig tests all in one by default. Use the flags --test-no-exec -femit-bin=... to just build a test-executable.
  • Consider support for cross-platform tests, i.e. executing a test binary that targets a different platform than the execution platform.
    The Zig compiler takes additional arguments --test-cmd and --test-cmd-bin. These define the command-line executed by zig test and are used to inject execution wrappers like qemu or wine to enable executing cross-platform tests. However, Bazel separates test build from test execution and the resulting test binary must be executable on the configured target platform (the compiler toolchain is only compatible with the execution platform).
    An approach that would fit better into Bazel might be a separate test (or binary) rule that takes a binary for a different target platform and generates a binary that executes qemu, wine, etc. depending on its own target platform.
• zig build-obj
  • rules_zig should support Zig's build-obj command.
    Consider whether this should be its own zig_object rule or a mode of zig_library.
• zig fmt
  • rules_zig should support Zig's fmt command for formatting tests.
    Consider whether this should be its own rule, an automatic test target, a validation action (see relevant bazel-discuss thread, or perhaps an apple_rules_lint integration.
  • rules_zig should support Zig's fmt command for automated reformatting.
• zig ast-check
  • rules_zig should support Zig's ast-check command.
    Consider whether this should be its own rule, an automatic test target, or perhaps a validation action (see relevant bazel-discuss thread).
• Support build options
  • Support Zig build modes #34
  • Distinguish target and exec configuration for build mode #37
  • Default to build mode following --compilation_mode #38
  • Support single threaded builds #44
  • Support custom linker scripts #46
  • Support cross-compilation for minimal set of targets #48
  • Support cross-compilation for all relevant targets #51
    • See cross-compilation and supported targets.
  • Support libc selection #54
  • Support generating documentation #221
  • Support build mode, target platform, libc, etc. selection per build target #39
  • Support platform specific build options. #100
  • Set or expose Zig's root-name (--name) parameter #82
• Third party dependencies
  • Support zig build for third-party dependencies #231
  • Consider package manager integration for Zig. #232
    zigmod is a community maintained package manager, pending package manager integration into the Zig compiler itself. Aquila is a package index for it. The package metadata format is specified here.
• Documentation
  • Provide a minimal description in the README. #56
  • Ensure that the generated API reference documentation is complete. #57
  • Create a small, instructive example. #58
  • Write a brief motivation in the README. #63
  • Refer to releases in the bzlmod and WORKSPACE installation instructions. #139
  • Add a user-guide. #59
  • Generate Stardoc documentation for providers #64
  • Generate Stardoc documentation for internal rules and utilities #65
• Handle Zig's global and local cache meaningfully. #87
  The global cache may be beneficial to persist and re-use across targets, at least for the same target platform. Perhaps a persistent worker could facilitate this.
  Consider whether the local cache should be shared across actions. If not, consider discarding it immediately.

Bazel concepts

• Bazel runfiles support
  • Support location expansion in appropriate attributes, e.g. zigopts or copts. #84
  • Handle data attributes in Zig rules #85
  • Create a Zig runfiles support library #86
• Support rules_cc interop.
  • zig_library should be a valid dependency for cc-rules like cc_library. #14
• Test remote execution and tightly sandboxed builds chore!: enable remote execution on CI for Linux #296
  Either using a remote execution service, or the remote worker.
  Or consider using sandboxfs.
• Build targets from a mix of sources and generated sources.
• Decide whether the main source may be duplicated across the main and srcs attributes or not and enforce the rule.
• Support the new bzlmod dependency manager.
  • Separate tests out into a separate testing workspace/module. #89
    The Bazel Central Registry has only limited capability to run tests for registered Bazel modules. In particular, local modules are very difficult, or impossible to integrate. Therefore, it's generally recommended to keep the tests on the BCR very light.
  • Define bzlmod MODULE.bazel files and run all tests with bzlmod enabled. #88
  • Configure and install the release to BCR app. #140
  • Provide a Bazel registry entry. #90

Meta

• Choose and set a license #32
• Define labels and issue/PR templates #33