hermetic_launcherAPI docs @0.0.2

@hermetic_launcher@hermetic_launcher//launcher:launcher_binary.bzl

Rules

launcher_binary

Creates 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:

  1. Resolve the openssl binary location through runfiles
  2. Resolve file_to_hash.txt location through runfiles (auto-detected from $(rlocationpath))
  3. Execute: openssl dgst -sha256 /resolved/path/to/file_to_hash.txt
  4. 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.

AttributeTypeDescription
*namename

A unique name for this target.

*entrypointlabel

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
runfiles mechanism. This must be an executable target (e.g., a binary, a script, or another
launcher_binary).

Example: entrypoint = "@python_3_11//:python" or entrypoint = "//tools:my_tool"

embedded_argslist 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
expansion (e.g., $(rlocationpath), $(location), $(execpath)).

Arguments matching the pattern $(rlocationpath ...) are automatically detected and marked
for runtime path transformation unless you explicitly set transformed_args.

Example:

embedded_args = [ "--config", "$(rlocationpath :config.yaml)", # Auto-detected for transformation "--mode=production", # Literal string, not transformed ]
Default: []
transformed_argslist 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):

  • Entrypoint (index 0) is always transformed
  • Any argument matching $(rlocationpath ...) is transformed
  • Other arguments are passed as literal strings

Custom behavior:
Set explicit indices to transform:

transformed_args = [0, 2, 5] # Transform entrypoint, 2nd arg, and 5th arg

Disable all transformation:

transformed_args = [-1] # Special value: no transformation at all

Use this when you want fine-grained control over which paths are resolved through runfiles.

Default: []
datalist 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,
making them available at runtime. Use $(rlocationpath) to reference these files in
embedded_args.

Example:

data = [ ":config.yaml", "//data:test_fixtures", "@some_external//:data_files", ]
Default: []

@hermetic_launcher@hermetic_launcher//launcher:lib.bzl

Functions & Macros

launcher.append_embedded_arg
Parameters
*arg
*embedded_args
*transformed_args
launcher.append_raw_transformed_arg
Parameters
*arg
*embedded_args
*transformed_args
launcher.append_runfile
Parameters
*file
*embedded_args
*transformed_args
launcher.args_from_entrypoint
Parameters
*executable_file
launcher.compile_stub
Parameters
*ctx
*embedded_args
*transformed_args
*output_file
cfg
Default: "target"
template_exec_group
Default: None
launcher.to_rlocation_path
Parameters
*f