rules_binary_toolchain creates Bazel toolchains and runnable targets for
packaged executable binaries. Archive entries can include runtime files,
which the generated binary targets expose through Bazel runfiles.
This is the multi-page printable view of this section. Click here to print.
Rules binary toolchain
Bazel toolchains for packaged executable binaries
- 1:
- 2:
- 3: Bzl
1 -
project-dns Specification
Purpose
Record the retirement of rules_binary_toolchain landing infrastructure while preserving
its reusable Bazel module.
Requirements
Requirement: Keep landing infrastructure retired
The module SHALL follow the tools boundary and SHALL have no dedicated landing DNS declarations, Terraform root, or operational source exports.
Scenario: Inspect the module after landing retirement
- WHEN the module is consumed from
tools/rules_binary_toolchain - THEN its reusable Bazel rules remain available without landing infrastructure.
2 -
Rules binary toolchain
Purpose
Provide Bazel toolchains and runnable targets for packaged executable binaries,
including their runtime files. This source baseline was observed on 2026-09-08
at revision 550d7e79b1f5fdbc2b6017b75178471d6914082f.
Sources: project description, lock parsing, module extension, archive repositories, and runnable wrapper.
Requirements
Requirement: Select archives from the declared toolchain lock
The module extension SHALL resolve a requested toolchain by name and version from its JSON lock and create repositories for the matching archives.
Scenario: A requested toolchain has no matching archive
- WHEN the requested toolchain is absent or has no archive matching its locked version
- THEN extension evaluation fails with a diagnostic instead of selecting another version.
Requirement: Verify downloaded archive integrity
Archive repository download and download-and-extract actions SHALL compare the reported integrity against the action’s declared integrity and fail on mismatch.
Scenario: Downloaded content differs from its lock entry
- WHEN a download reports an integrity value different from the lock action
- THEN repository creation fails with the expected and observed integrity values.
Requirement: Preserve runtime files in generated binary targets
Generated native binary and filegroup targets SHALL include the files selected
by each binary’s runtime_files glob patterns, in addition to the executable.
Runnable toolchain wrappers SHALL merge the selected toolchain’s runfiles and
declared data runfiles.
Scenario: A packaged executable needs an adjacent runtime asset
- WHEN an archive declares a runtime asset through
runtime_files - THEN the native binary carries that asset in its data, the filegroup exposes it, and a wrapper carries the toolchain runfiles into execution.
Requirement: Forward wrapper arguments and environment
The runnable wrapper SHALL expand declared location and make-variable arguments,
append invocation arguments, and expose the declared env through
RunEnvironmentInfo.
Scenario: A caller supplies additional command arguments
- WHEN a generated wrapper is invoked with arguments after its configured arguments
- THEN the selected toolchain binary receives both argument sets in that order.
3 - Bzl
Bazel code
Archive binaries
Each archive binaries entry requires a name and path. It can also set
runtime_files to a list of Bazel glob patterns relative to the unpacked
archive. The generated <name>_native_binary exposes matching files as
runfiles; <name>_filegroup exposes the binary and those same files.
Omit runtime_files when the binary needs no extra runtime files.