feat: add runtime_executable adapter for foreign_cc binaries

jsun-splunk · jsun-splunk · commit 72a88a1b03bd · 2026-06-30T09:44:48.000Z
Introduce a `runtime_executable` rule for turning selected foreign_cc
binary outputs into executable Bazel targets. This cannot live directly
on the existing foreign_cc rules because foreign_cc outputs are not
always expected to contain a binary, so those rules cannot always expose
an executable.

The adapted executable may require `runtime_library_search_directories =
"enabled"` on the producing foreign_cc target when it depends directly
or transitively on foreign_cc-produced shared libraries.

`runtime_executable` is a more Bazel-native version of `runnable_binary`
because it exposes the executable through `DefaultInfo.files_to_run` for
downstream consumers. The API is intentionally kept similar to
`runnable_binary`. For now, it cannot completely replace
`runnable_binary` because `runtime_library_search_directories` defaults
to `"disabled"` to minimize blast radius while these features mature.
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -89,6 +89,16 @@ stardoc(
     ],
 )
 
+stardoc(
+    name = "runtime_executable_docs",
+    out = "src/runtime_executable.md",
+    input = "@rules_foreign_cc//foreign_cc:runtime_executable.bzl",
+    deps = [
+        ":rules_cc_deps",
+        "@rules_foreign_cc//foreign_cc:runtime_executable",
+    ],
+)
+
 DOCS_TARGETS = [
     ":cmake_docs",
     ":ninja_docs",
@@ -97,6 +107,7 @@ DOCS_TARGETS = [
     ":meson_docs",
     ":msbuild_docs",
     ":providers_docs",
+    ":runtime_executable_docs",
 ]
 
 build_test(
diff --git a/docs/docs.bzl b/docs/docs.bzl
@@ -12,11 +12,13 @@ load(
     _meson = "meson",
     _meson_with_requirements = "meson_with_requirements",
     _ninja = "ninja",
+    _runtime_executable = "runtime_executable",
 )
 load(
     "@rules_foreign_cc//foreign_cc:providers.bzl",
     _ForeignCcArtifactInfo = "ForeignCcArtifactInfo",
     _ForeignCcDepsInfo = "ForeignCcDepsInfo",
+    _ForeignCcRuntimeExecutableInfo = "ForeignCcRuntimeExecutableInfo",
 )
 load("@rules_foreign_cc//foreign_cc:repositories.bzl", _rules_foreign_cc_dependencies = "rules_foreign_cc_dependencies")
 load("@rules_foreign_cc//foreign_cc/built_tools:cmake_build.bzl", _cmake_tool = "cmake_tool")
@@ -44,7 +46,9 @@ native_tool_toolchain = _native_tool_toolchain
 ninja = _ninja
 ninja_tool = _ninja_tool
 rules_foreign_cc_dependencies = _rules_foreign_cc_dependencies
+runtime_executable = _runtime_executable
 
 ForeignCcArtifactInfo = _ForeignCcArtifactInfo
 ForeignCcDepsInfo = _ForeignCcDepsInfo
+ForeignCcRuntimeExecutableInfo = _ForeignCcRuntimeExecutableInfo
 ToolInfo = _ToolInfo
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -12,3 +12,4 @@
         - [meson](meson.md)
         - [msbuild](msbuild.md)
         - [ninja](ninja.md)
+        - [runtime_executable](runtime_executable.md)
diff --git a/docs/src/rules.md b/docs/src/rules.md
@@ -5,5 +5,6 @@
 - [make](./make.md)
 - [meson](./meson.md)
 - [ninja](./ninja.md)
+- [runtime_executable](./runtime_executable.md)
 
 For additional rules/macros/providers, see the [full API in one page](./flatten.md).
diff --git a/examples/integration_tests/runtime_executable/BUILD.bazel b/examples/integration_tests/runtime_executable/BUILD.bazel
@@ -0,0 +1,27 @@
+load("@rules_foreign_cc//foreign_cc:defs.bzl", "runtime_executable")
+load("@rules_shell//shell:sh_test.bzl", "sh_test")
+
+runtime_executable(
+    name = "openssl_runtime_executable",
+    binary = select({
+        "@rules_cc//cc/compiler:msvc-cl": "openssl.exe",
+        "//conditions:default": "openssl",
+    }),
+    foreign_cc_target = "@openssl//:openssl",
+)
+
+sh_test(
+    name = "openssl_help_test",
+    size = "small",
+    srcs = ["openssl_help_test.sh"],
+    args = ["$(rlocationpath :openssl_runtime_executable)"],
+    data = [
+        ":openssl_runtime_executable",
+        "@bazel_tools//tools/bash/runfiles",
+    ],
+)
+
+test_suite(
+    name = "tests",
+    tests = [":openssl_help_test"],
+)
diff --git a/examples/integration_tests/runtime_executable/openssl_help_test.sh b/examples/integration_tests/runtime_executable/openssl_help_test.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+set +u
+f=bazel_tools/tools/bash/runfiles/runfiles.bash
+source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "${RUNFILES_MANIFEST_FILE:-/dev/null}" | cut -d ' ' -f 2-)" 2>/dev/null || \
+  source "$0.runfiles/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "$0.runfiles_manifest" | cut -d ' ' -f 2-)" 2>/dev/null || {
+    echo >&2 "cannot find $f"
+    exit 1
+  }
+set -u
+
+if [[ "$#" -ne 1 ]]; then
+  echo "usage: $0 <openssl-runfile-path>" >&2
+  exit 1
+fi
+
+openssl="$(rlocation "$1")"
+if [[ -z "$openssl" || ! -x "$openssl" ]]; then
+  echo "openssl runtime executable is not executable: $1" >&2
+  exit 1
+fi
+
+exec "$openssl" help
diff --git a/examples/third_party/openssl/BUILD.openssl.bazel b/examples/third_party/openssl/BUILD.openssl.bazel
@@ -116,10 +116,14 @@ configure_make(
             "install_name_tool -id @rpath/libcrypto.1.1.dylib $$INSTALLDIR/lib/libcrypto.1.1.dylib",
             "install_name_tool -change $$BUILD_TMPDIR/openssl/lib/libcrypto.1.1.dylib @rpath/libcrypto.1.1.dylib $$INSTALLDIR/lib/libssl.1.1.dylib",
             "install_name_tool -change $$INSTALLDIR/lib/libcrypto.1.1.dylib @rpath/libcrypto.1.1.dylib $$INSTALLDIR/lib/libssl.1.1.dylib",
+            "install_name_tool -change $$BUILD_TMPDIR/openssl/lib/libssl.1.1.dylib @rpath/libssl.1.1.dylib $$INSTALLDIR/bin/openssl",
+            "install_name_tool -change $$BUILD_TMPDIR/openssl/lib/libcrypto.1.1.dylib @rpath/libcrypto.1.1.dylib $$INSTALLDIR/bin/openssl",
         ]),
         "//conditions:default": "",
     }),
     resource_size = "enormous",
+    runtime_library_search_directories = "enabled",
+    shared_ldflags_vars = ["SHLIB_LDFLAGS"],
     target_compatible_with = select({
         "@platforms//os:windows": ["@platforms//:incompatible"],
         "//conditions:default": [],
diff --git a/foreign_cc/BUILD.bazel b/foreign_cc/BUILD.bazel
@@ -97,6 +97,7 @@ bzl_library(
         ":meson",
         ":msbuild",
         ":ninja",
+        ":runtime_executable",
         ":utils",
     ],
 )
@@ -212,3 +213,14 @@ bzl_library(
     srcs = ["providers.bzl"],
     visibility = ["//visibility:public"],
 )
+
+bzl_library(
+    name = "runtime_executable",
+    srcs = ["runtime_executable.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":providers",
+        "@bazel_skylib//lib:shell",
+        "@rules_shell//shell:rules_bzl",
+    ],
+)
diff --git a/foreign_cc/defs.bzl b/foreign_cc/defs.bzl
@@ -11,6 +11,7 @@ load(":make.bzl", _make = "make", _make_variant = "make_variant")
 load(":meson.bzl", _meson = "meson", _meson_with_requirements = "meson_with_requirements")
 load(":msbuild.bzl", _msbuild = "msbuild")
 load(":ninja.bzl", _ninja = "ninja")
+load(":runtime_executable.bzl", _runtime_executable = "runtime_executable")
 load(":utils.bzl", _runnable_binary = "runnable_binary")
 
 boost_build = _boost_build
@@ -25,3 +26,4 @@ meson_with_requirements = _meson_with_requirements
 msbuild = _msbuild
 ninja = _ninja
 runnable_binary = _runnable_binary
+runtime_executable = _runtime_executable
diff --git a/foreign_cc/private/BUILD.bazel b/foreign_cc/private/BUILD.bazel
@@ -2,6 +2,7 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 exports_files([
     "runnable_binary_wrapper.sh",
+    "runtime_executable_wrapper.sh.tpl",
     "settings.sh.in",
 ])
 
@@ -150,7 +151,9 @@ bzl_library(
     name = "transitions",
     srcs = ["transitions.bzl"],
     visibility = ["//foreign_cc:__subpackages__"],
-    deps = ["//foreign_cc:providers"],
+    deps = [
+        "//foreign_cc:providers",
+    ],
 )
 
 bzl_library(
diff --git a/foreign_cc/private/framework.bzl b/foreign_cc/private/framework.bzl
@@ -8,7 +8,7 @@ load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "find_cpp_toolchain")
 load("@rules_cc//cc:defs.bzl", "CcInfo", "cc_common")
 load("@rules_cc//cc/common:cc_shared_library_info.bzl", "CcSharedLibraryInfo")
-load("//foreign_cc:providers.bzl", "ForeignCcArtifactInfo", "ForeignCcDepsInfo")
+load("//foreign_cc:providers.bzl", "ForeignCcArtifactInfo", "ForeignCcDepsInfo", "ForeignCcRuntimeExecutableInfo")
 load("//foreign_cc/private:detect_root.bzl", "filter_containing_dirs_from_inputs")
 load("//foreign_cc/private:resource_sets.bzl", "SIZE_ATTRIBUTES", "get_resource_env_vars")
 load(
@@ -686,6 +686,22 @@ def cc_external_rule_impl(ctx, attrs):
             [externally_built],
             transitive = _get_transitive_artifacts(attrs.deps),
         )),
+        ForeignCcRuntimeExecutableInfo(
+            binaries = {
+                attrs.out_binaries[i]: outputs.out_binary_files[i]
+                for i in range(len(attrs.out_binaries))
+            },
+            runtime_files = depset(direct = (
+                ([outputs.out_include_dir] if outputs.out_include_dir else []) +
+                outputs.libraries.shared_libraries +
+                outputs.data_dirs +
+                outputs.data_files
+            ), transitive = [
+                dep[ForeignCcRuntimeExecutableInfo].runtime_files
+                for dep in attrs.deps
+                if ForeignCcRuntimeExecutableInfo in dep
+            ]),
+        ),
         CcInfo(
             compilation_context = out_cc_info.compilation_context,
             linking_context = out_cc_info.linking_context,
diff --git a/foreign_cc/private/runtime_executable_wrapper.sh.tpl b/foreign_cc/private/runtime_executable_wrapper.sh.tpl
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+# --- begin runfiles.bash initialization v3 ---
+# Copy-pasted from the Bazel Bash runfiles library v3.
+set -uo pipefail; set +e; f=bazel_tools/tools/bash/runfiles/runfiles.bash
+
+# This wrapper needs to resolve its selected foreign_cc binary from its own
+# runfiles. When this wrapper is invoked by another Bazel-built tool, the parent
+# may export RUNFILES_DIR or RUNFILES_MANIFEST_FILE for the parent's runfiles
+# tree. Prefer the runfiles tree or manifest adjacent to $0 before sourcing
+# runfiles.bash.
+#
+# For example, a parent tool may invoke this wrapper with
+# RUNFILES_DIR=.../parent_tool.runfiles. If we keep that inherited value,
+# rlocation will look for the selected binary in the parent tool's runfiles
+# instead of this wrapper's runfiles.
+if [[ -d "$0.runfiles" ]]; then
+  export RUNFILES_DIR="$0.runfiles"
+  unset RUNFILES_MANIFEST_FILE
+elif [[ -f "$0.runfiles_manifest" ]]; then
+  export RUNFILES_MANIFEST_FILE="$0.runfiles_manifest"
+  unset RUNFILES_DIR
+elif [[ -f "$0.exe.runfiles_manifest" ]]; then
+  export RUNFILES_MANIFEST_FILE="$0.exe.runfiles_manifest"
+  unset RUNFILES_DIR
+fi
+
+# shellcheck disable=SC1090
+source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "${RUNFILES_MANIFEST_FILE:-/dev/null}" | cut -f2- -d' ')" 2>/dev/null || \
+  source "$0.runfiles/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "$0.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "$0.exe.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  { echo>&2 "ERROR: cannot find $f"; exit 1; }; f=; set -e
+# --- end runfiles.bash initialization v3 ---
+
+runfiles_export_envvars
+
+binary=""
+for candidate in %{binary_runfile_paths}; do
+  candidate_binary="$(rlocation "$candidate" 2>/dev/null || true)"
+  if [[ -n "$candidate_binary" && -x "$candidate_binary" ]]; then
+    binary="$candidate_binary"
+    break
+  fi
+done
+
+if [[ -z "$binary" ]]; then
+  printf '%s\n' %{failure_message} >&2
+  exit 1
+fi
+
+exec "$binary" "$@"
diff --git a/foreign_cc/private/runtime_library_search_directories.bzl b/foreign_cc/private/runtime_library_search_directories.bzl
@@ -179,6 +179,7 @@ def runtime_library_search_directories(ctx, outputs):
       contains runtime library search directories for that link action kind, or
       None when runtime library search directory derivation is disabled.
     """
+    d_attrs = _declared_runtime_attrs(ctx)
 
     d_attrs = _declared_runtime_attrs(ctx)
     if not _runtime_library_search_directories_requested(ctx):
diff --git a/foreign_cc/private/transitions.bzl b/foreign_cc/private/transitions.bzl
@@ -1,7 +1,7 @@
 """This file contains rules for configuration transitions"""
 
 load("@rules_cc//cc:defs.bzl", "CcInfo")
-load("//foreign_cc:providers.bzl", "ForeignCcDepsInfo")
+load("//foreign_cc:providers.bzl", "ForeignCcDepsInfo", "ForeignCcRuntimeExecutableInfo")
 
 def _extra_toolchains_transition_impl(settings, attrs):
     t = getattr(attrs, "extra_toolchain", None)
@@ -18,12 +18,15 @@ _extra_toolchains_transition = transition(
 
 def _extra_toolchains_transitioned_foreign_cc_target_impl(ctx):
     # Return the providers from the transitioned foreign_cc target
-    return [
+    providers = [
         ctx.attr.target[DefaultInfo],
         ctx.attr.target[CcInfo],
         ctx.attr.target[ForeignCcDepsInfo],
         ctx.attr.target[OutputGroupInfo],
     ]
+    if ForeignCcRuntimeExecutableInfo in ctx.attr.target:
+        providers.append(ctx.attr.target[ForeignCcRuntimeExecutableInfo])
+    return providers
 
 extra_toolchains_transitioned_foreign_cc_target = rule(
     doc = "A rule for adding an extra toolchain to consider when building the given target",
diff --git a/foreign_cc/providers.bzl b/foreign_cc/providers.bzl
@@ -23,3 +23,11 @@ Instances of ForeignCcArtifactInfo are encapsulated in a depset [ForeignCcDepsIn
         "lib_dir_name": "Lib directory, relative to install directory",
     },
 )
+
+ForeignCcRuntimeExecutableInfo = provider(
+    doc = """Provider exposing declared foreign_cc runtime files for executable adapters.""",
+    fields = {
+        "binaries": "Dictionary mapping exact out_binaries entries to declared binary Files.",
+        "runtime_files": "Depset of declared foreign_cc outputs needed at runtime.",
+    },
+)
diff --git a/foreign_cc/runtime_executable.bzl b/foreign_cc/runtime_executable.bzl
diff --git a/test/BUILD.bazel b/test/BUILD.bazel
diff --git a/test/runtime_executable_inherited_runfiles_test.sh b/test/runtime_executable_inherited_runfiles_test.sh
diff --git a/test/runtime_executable_shell_quoting_test.sh b/test/runtime_executable_shell_quoting_test.sh
diff --git a/test/runtime_executable_test.bzl b/test/runtime_executable_test.bzl
