[acecilia]

Problem

rb_bundle_install compiles native gem extensions (json, prism, ffi, ...) against arbitrary host system components. On macOS mkmf resolves clang and the SDK through xcrun, but other bundles need CC, PKG_CONFIG_PATH, CMAKE, ... — the set of possible host dependencies is unbounded.

Consumers that need to control these values today face two dead ends:

• The env tag attribute only accepts static strings.
• Delegating resolution to the host's ambient environment is non-hermetic and invisible to the action cache: a toolchain change does not invalidate cached compiled extensions.

Solution

Optional env_file attribute on the bundle_fetch tag: a label pointing to a file with KEY=VALUE lines. The repository rule reads the file at evaluation time on the building machine and bakes the resolved values into the generated env as a plain static dict — the generated BUILD stays fully static, no load() of consumer starlark, no symbol conventions.

# MODULE.bazel
ruby.bundle_fetch(
    name = "ruby_bundle",
    env_file = "@ruby_build_env//:env",
    ...
)

The referenced file is produced by a single dedicated consumer repository rule that composes the whole installation environment (here one resolving the Xcode pinned by the project):

# Bazel/repository_rules/ruby_build_env.bzl
def _ruby_build_env_impl(ctx):
    result = ctx.execute(["zsh", "-c", str(ctx.path(ctx.attr._print_developer_dir_script))])
    ctx.file("env", "DEVELOPER_DIR=%s\n" % result.stdout)  # e.g. DEVELOPER_DIR=/Applications/Xcode-27.1.0.app
    ctx.file("BUILD.bazel", 'exports_files(["env"])')

Because the file is a label input to the repository rule:

• values are resolved inside the build graph (no ambient env, no dependence on how bazel was invoked),
• content changes re-run the repository, and the new static values change the rb_bundle_install action key, so compiled native extensions are correctly invalidated (Xcode bump → recompile),
• per-machine values keep remote caches from sharing entries across differently-provisioned hosts.

The mechanism is provider-agnostic: the consumer rule decides what the environment contains (DEVELOPER_DIR today, PKG_CONFIG_PATH or a pinned CC tomorrow), with rules_ruby baking in no system knowledge.

Alternatives considered

• repository_rule(environ = [...]): mirrors Bazel's native mechanism, but the variable list is a static per-rule declaration — a generic ruleset would need a hardcoded variable vocabulary, and values would depend on the ambient environment of the invocation.

Testing

examples/gem exercises env_file end-to-end: env_file_check_test asserts the value lands in the generated bundle repository (verified locally: passes with the correct value, fails with a tampered one), and the executed bundle_install_*.sh contains export RULES_RUBY_ENV_FILE_TEST=exercised. Also validated in a large consumer repo: DEVELOPER_DIR reaches the install script via a use_repo_rule repository, and changing the file content re-runs the bundle install action.