@hermetic_launcher@hermetic_launcher//launcher:launcher_binary.bzl
Rules
launcher_binaryCreates a tiny, binary launcher that wraps another executable with its runfiles.
This rule generates a small native binary (10-68KB depending on platform) that:
- Resolves Bazel runfiles paths at runtime
- Executes the target program with embedded arguments
- Forwards additional runtime arguments
- Exports runfiles environment variables to child processes
- Works identically on Linux, macOS, and Windows
The launcher automatically detects runfiles using RUNFILES_DIR, RUNFILES_MANIFEST_FILE,
or by looking for a <binary>.runfiles/ directory adjacent to the executable.
Example - Wrapping openssl to hash a file:
load("@hermetic_launcher//launcher:launcher_binary.bzl", "launcher_binary") launcher_binary( name = "hash_file", entrypoint = "@openssl", embedded_args = [ "dgst", "-sha256", "$(rlocationpath :file_to_hash.txt)", ], data = [":file_to_hash.txt"], )
The launcher will:
- Resolve the openssl binary location through runfiles
- Resolve file_to_hash.txt location through runfiles (auto-detected from $(rlocationpath))
- Execute:
openssl dgst -sha256 /resolved/path/to/file_to_hash.txt - Export RUNFILES_DIR, RUNFILES_MANIFEST_FILE, and JAVA_RUNFILES to the child process
Runtime argument forwarding:
Additional arguments passed to the binary are forwarded to the entrypoint:
bazel run //:hash_file -- --some-extra-flag # Executes: openssl dgst -sha256 /resolved/path/to/file.txt --some-extra-flag
Automatic path transformation:
By default, the entrypoint (index 0) and any argument matching $(rlocationpath ...)
are automatically transformed through runfiles. You can customize this with transformed_args.
Cross-platform:
The same BUILD file works on Linux, macOS, and Windows. The launcher handles platform-specific
path separators and runfiles resolution automatically.
| Attribute | Type | Description |
|---|---|---|
*name | name | A unique name for this target. |
*entrypoint | label | The target executable to wrap. This is the actual program that will be executed. The entrypoint's runfiles path will be automatically resolved at runtime through the Bazel Example: |
embedded_args | list of strings | Arguments to embed in the binary that will be passed to the entrypoint. These arguments are baked into the binary at build time. They support Bazel location Arguments matching the pattern Example:
Default: [] |
transformed_args | list of integers | Explicit list of argument indices that need runtime runfiles path transformation. Index 0 is the entrypoint, index 1 is the first embedded arg, index 2 is the second, etc. Default behavior (empty list):
Custom behavior:
Disable all transformation:
Use this when you want fine-grained control over which paths are resolved through runfiles. Default: [] |
data | list of labels | Runtime dependencies (data files, scripts, etc.) needed by the entrypoint. These files and their transitive runfiles will be included in the binary's runfiles tree, Example:
Default: [] |
@hermetic_launcher@hermetic_launcher//launcher:lib.bzl
Functions & Macros
launcher.append_embedded_argParameters
*arg | |
*embedded_args | |
*transformed_args |
launcher.append_raw_transformed_argParameters
*arg | |
*embedded_args | |
*transformed_args |
launcher.append_runfileParameters
*file | |
*embedded_args | |
*transformed_args |
launcher.args_from_entrypointParameters
*executable_file |
launcher.compile_stubParameters
*ctx | |
*embedded_args | |
*transformed_args | |
*output_file | |
cfg | Default: "target" |
template_exec_group | Default: None |
launcher.to_rlocation_pathParameters
*f |