Simplify Out-Of-Process JIT case (#940)

vgvassilev · web-flow · commit 2da895b42fad · 2026-04-26T19:06:07.000+03:00
* [jit] Self-contain the OOP-JIT runtime in CppInterOp's distribution.

Out-of-process JIT needs `liborc_rt*.a` (fed to
`IncrementalExecutorBuilder::OrcRuntimePath`) and
`llvm-jitlink-executor`. Upstream's auto-discovery validates the
runtime path against `parent_path(D.Dir)`, which only matches when
`libclangCppInterOp.so` lives inside the LLVM install tree -- test
binaries under `&lt;build&gt;/unittests/...` trip the safety check.

Bundle both artifacts under `&lt;libdir&gt;/cppinterop-rt/` via a new
`FindLLVMOrcRuntime` cmake module and configure_file/install rules,
and hand the paths to `IncrementalExecutorBuilder` directly with a
no-op `UpdateOrcRuntimePathCB`. The locations are baked at build
time (`CPPINTEROP_RUNTIME_{BUILD,INSTALL}_DIR`); when the runtime
parts are missing the OOP path falls back to in-process JIT with a
logged warning. Relocatable-install support (sysadmin-overridable
runtime dir, `dladdr`-based self-DSO probe) is a separate follow-up
PR layered on top of this baked probe.

Drops the now-unused `LLVM_BUILT_WITH_OOP_JIT` cmake option and the
`LLVM_BINARY_LIB_DIR` define (its only consumer was the old
hand-built executor path); README, InstallationAndUsage.rst, and
DevelopersDocumentation.rst are updated to describe auto-detection.

* [ci] Build the bundled OOP-JIT runtime in non-cling LLVM&gt;=22 caches.

Activates the bundling design from `[jit] Self-contain the OOP-JIT
runtime in CppInterOp's distribution.`:

- `Build_LLVM/action.yml`: for non-cling rows with `clang-runtime
  &gt;= 22`, set `LLVM_ENABLE_PROJECTS="clang;compiler-rt"` and ninja
  `llvm-jitlink-executor` plus every `orc_rt*` target ninja exposes
  (other compiler-rt components are turned off so build cost is
  bounded to the ORC runtime). The matrix `llvm_enable_projects`
  override is no longer load-bearing: the projects list is now
  picked entirely from `NEED_OOP`.
- `Build_and_Test_CppInterOp/action.yml`: drop
  `-DLLVM_BUILT_WITH_OOP_JIT`; CppInterOp auto-detects via
  `find_package(LLVMOrcRuntime)`. The Valgrind suppression file
  selection moves from `matrix.oop-jit` to `clang-runtime &gt;= 22`,
  matching the auto-detect condition that now drives OOP at
  runtime. Adds two post-build assertions: (a) the typed-test
  fixtures registered match the source-side gate -- the
  `OutOfProcessJIT` fixture must NOT be present on `clang-runtime
  &lt;= 21`, catching accidental regressions of the
  `LLVM_VERSION_MAJOR &gt; 21` guard in `unittests/CppInterOp/Utils.h`;
  (b) an install-layout smoke test that installs into a scratch
  prefix and asserts `&lt;libdir&gt;/cppinterop-rt/liborc_rt.a` is
  shipped and `llvm-jitlink-executor` retains its executable bit,
  catching install(FILES/PROGRAMS) destination/mode regressions.
- `main.yml`: drop the `-oop` cache-key suffix and the `oop-jit`
  matrix dimension along with its rows. `osx26-arm-clang-llvm22-oop`
  was a duplicate of `osx26-arm-clang-llvm22` once the OOP knob
  retired; `ubu24-x86-gcc12-llvm22-oop-vg` was unique only for its
  Valgrind axis and is renamed to `ubu24-x86-gcc12-llvm22-vg`. OOP
  and in-process rows on the same axes now share a cache slot;
  existing entries match the new key but need a refresh to gain
  the runtime parts -- transitional rows fall back to in-process
  JIT with a logged warning.
diff --git a/.github/actions/Build_LLVM/action.yml b/.github/actions/Build_LLVM/action.yml
@@ -23,7 +23,7 @@ runs:
         mkdir build
         if [[ "${cling_on}" == "ON" ]]; then
           cd build
-          cmake -DLLVM_ENABLE_PROJECTS="${{ matrix.llvm_enable_projects || 'clang' }}" \
+          cmake -DLLVM_ENABLE_PROJECTS="clang" \
                 -DLLVM_EXTERNAL_PROJECTS=cling                     \
                 -DLLVM_EXTERNAL_CLING_SOURCE_DIR=../../cling       \
                 -DLLVM_TARGETS_TO_BUILD="${{ matrix.llvm_targets_to_build || 'host;NVPTX' }}" \
@@ -39,8 +39,32 @@ runs:
           ninja LLVMOrcDebugging -j ${{ env.ncpus }}
           ninja clingInterpreter -j ${{ env.ncpus }}
         else
+          # Non-cling, LLVM >= 22: bundle the OOP-JIT runtime into the
+          # cache. compiler-rt is enabled with everything except the
+          # ORC runtime turned off so the build stays cheap.
+          NEED_OOP=0
+          if [[ "${{ matrix.clang-runtime }}" -ge 22 ]]; then
+            NEED_OOP=1
+          fi
+          if [[ "${NEED_OOP}" == "1" ]]; then
+            PROJECTS="clang;compiler-rt"
+            COMPILER_RT_FLAGS=(
+              -DCOMPILER_RT_BUILD_BUILTINS=OFF
+              -DCOMPILER_RT_BUILD_LIBFUZZER=OFF
+              -DCOMPILER_RT_BUILD_PROFILE=OFF
+              -DCOMPILER_RT_BUILD_MEMPROF=OFF
+              -DCOMPILER_RT_BUILD_SANITIZERS=OFF
+              -DCOMPILER_RT_BUILD_XRAY=OFF
+              -DCOMPILER_RT_BUILD_GWP_ASAN=OFF
+              -DCOMPILER_RT_BUILD_CTX_PROFILE=OFF
+            )
+          else
+            PROJECTS="clang"
+            COMPILER_RT_FLAGS=()
+          fi
+
           cd build
-          cmake -DLLVM_ENABLE_PROJECTS="${{ matrix.llvm_enable_projects || 'clang' }}" \
+          cmake -DLLVM_ENABLE_PROJECTS="${PROJECTS}" \
                 -DLLVM_TARGETS_TO_BUILD="${{ matrix.llvm_targets_to_build || 'host;NVPTX' }}"  \
                 -DCMAKE_BUILD_TYPE=Release                          \
                 -DLLVM_ENABLE_ASSERTIONS=ON                         \
@@ -53,15 +77,17 @@ runs:
                 -DLLVM_USE_SANITIZER="${{ matrix.sanitizer }}"  \
                 -DLLVM_INCLUDE_EXAMPLES=OFF                     \
                 -DLLVM_INCLUDE_TESTS=OFF                        \
+                "${COMPILER_RT_FLAGS[@]}" \
                 ../llvm
           ninja clang clangInterpreter clangStaticAnalyzerCore
-          if [[ "${{ matrix.oop-jit }}" == "On" ]]; then
-            if [[ "${{ matrix.os }}" == macos* ]]; then
-              SUFFIX="_osx"
-            elif [[ "${{ matrix.os }}" == ubuntu* ]]; then
-              SUFFIX="-x86_64"
-            fi
-            ninja llvm-jitlink-executor orc_rt${SUFFIX} -j ${{ env.ncpus }}       
+          if [[ "${NEED_OOP}" == "1" ]]; then
+            # orc_rt's per-target ninja target name varies; find it by
+            # asking ninja for everything matching `orc_rt*`. Building
+            # the executor unconditionally is safe -- it's always a
+            # valid target when compiler-rt is in the build.
+            OOP_TARGETS=$(ninja -t targets all 2>/dev/null | \
+              awk -F: '/^orc_rt[^:]*:/{print $1}' | sort -u | tr '\n' ' ')
+            ninja llvm-jitlink-executor ${OOP_TARGETS} -j ${{ env.ncpus }}
           fi
           cd ./tools/
           rm -rf $(find . -maxdepth 1 ! -name "clang" ! -name ".")
@@ -110,7 +136,7 @@ runs:
         if ( "${{ matrix.cling }}" -imatch "On" )
         {
           cd build
-          cmake -DLLVM_ENABLE_PROJECTS="${{ matrix.llvm_enable_projects || 'clang' }}" `
+          cmake -DLLVM_ENABLE_PROJECTS="clang" `
                 -DLLVM_EXTERNAL_PROJECTS=cling                `
                 -DLLVM_EXTERNAL_CLING_SOURCE_DIR="$env:CLING_DIR"   `
                 -DLLVM_TARGETS_TO_BUILD="${{ matrix.llvm_targets_to_build || 'host;NVPTX' }}" `
@@ -129,7 +155,7 @@ runs:
         {
           cd build
           echo "Apply clang${{ matrix.clang-runtime }}-*.patch patches:"
-          cmake -DLLVM_ENABLE_PROJECTS="${{ matrix.llvm_enable_projects || 'clang' }}"                   `
+          cmake -DLLVM_ENABLE_PROJECTS="clang"                   `
                 -DLLVM_TARGETS_TO_BUILD="${{ matrix.llvm_targets_to_build || 'host;NVPTX' }}"          `
                 -DCMAKE_BUILD_TYPE=Release                          `
                 -DLLVM_ENABLE_ASSERTIONS=ON                         `
diff --git a/.github/actions/Build_and_Test_CppInterOp/action.yml b/.github/actions/Build_and_Test_CppInterOp/action.yml
@@ -54,7 +54,6 @@ runs:
                 -DCODE_COVERAGE=${{ env.CODE_COVERAGE }}     \
                 -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR       \
                 -DLLVM_ENABLE_WERROR=On                      \
-                -DLLVM_BUILT_WITH_OOP_JIT=${{ matrix.oop-jit }} \
                 ../
         fi
         docs_on=$(echo "${{ matrix.documentation }}" | tr '[:lower:]' '[:upper:]')
@@ -63,10 +62,57 @@ runs:
           cmake --build . --target sphinx-cppinterop --parallel ${{ env.ncpus }}
         else
           cmake --build . --target check-cppinterop --parallel ${{ env.ncpus }}
+          # Verify the source-side `LLVM_VERSION_MAJOR > 21 &&
+          # !defined(_WIN32)` gate in unittests/CppInterOp/Utils.h:
+          # `InProcessJIT` always registers; `OutOfProcessJIT` must
+          # not register on clang-runtime <= 21. Missing OOP fixture
+          # on clang-runtime >= 22 is currently allowed (transitional;
+          # tighten to required once every cache row is rebuilt with
+          # compiler-rt).
+          TESTS_BIN=unittests/CppInterOp/bin/${{ env.BUILD_TYPE }}/CppInterOpTests
+          if [[ -x "${TESTS_BIN}" ]]; then
+            FIXTURES=$("${TESTS_BIN}" --gtest_list_tests 2>/dev/null | \
+              grep '^CppInterOpTest/' || true)
+            if ! echo "${FIXTURES}" | grep -q '^CppInterOpTest/InProcessJIT'; then
+              echo "FAIL: InProcessJIT fixture missing -- typed-test setup broken"
+              exit 1
+            fi
+            if [[ "${{ matrix.clang-runtime }}" -lt 22 ]]; then
+              if echo "${FIXTURES}" | grep -q '^CppInterOpTest/OutOfProcessJIT'; then
+                echo "FAIL: OutOfProcessJIT fixture registered on clang-runtime=${{ matrix.clang-runtime }}; LLVM_VERSION_MAJOR>21 source gate broken"
+                exit 1
+              fi
+            fi
+          fi
+          # Install-layout smoke test: install into a scratch prefix
+          # and assert the bundled runtime parts ship to
+          # `<libdir>/cppinterop-rt/` with the right modes. Catches
+          # install(FILES/PROGRAMS) destination/exec-bit regressions
+          # the in-tree path doesn't see.
+          INSTALL_DIR="${RUNNER_TEMP:-/tmp}/cppinterop-install-check"
+          rm -rf "${INSTALL_DIR}"
+          cmake --install . --prefix "${INSTALL_DIR}" >/dev/null
+          ls "${INSTALL_DIR}"/lib/libclangCppInterOp.* >/dev/null 2>&1 || \
+            { echo "FAIL: libclangCppInterOp not installed"; exit 1; }
+          if [[ -d "${INSTALL_DIR}/lib/cppinterop-rt" ]]; then
+            test -f "${INSTALL_DIR}/lib/cppinterop-rt/liborc_rt.a" || \
+              { echo "FAIL: liborc_rt.a missing from install"; exit 1; }
+            test -x "${INSTALL_DIR}/lib/cppinterop-rt/llvm-jitlink-executor" || \
+              { echo "FAIL: llvm-jitlink-executor missing or not executable"; exit 1; }
+            echo "OK: bundled OOP runtime installed under lib/cppinterop-rt/"
+          elif [[ "${{ matrix.clang-runtime }}" -lt 22 ]]; then
+            echo "OK: lib/cppinterop-rt/ absent, expected for clang-runtime <= 21"
+          else
+            echo "INFO: lib/cppinterop-rt/ absent on clang-runtime=${{ matrix.clang-runtime }} (transitional cache row without compiler-rt)"
+          fi
           os="${{ matrix.os }}"
           if [[ "${os}" != "macos"* && "${{ matrix.Valgrind }}" == "On" ]]; then
             CLANG_VERSION="${{ matrix.clang-runtime }}"
-            if [[ "${{ matrix.oop-jit }}" == "On" ]]; then
+            if [[ "${CLANG_VERSION}" -ge 22 ]]; then
+              # OOP-JIT runs by default on LLVM 22+ where the bundled
+              # runtime is available; OOP introduces extra valgrind
+              # noise (fork/exec, pipes) that the suppression file
+              # filters out.
               SUPPRESSION_FILE="../etc/clang${CLANG_VERSION}-valgrind.supp"
               valgrind --show-error-list=yes --track-origins=yes --error-exitcode=1 \
                 --show-leak-kinds=definite,possible \
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -74,7 +74,6 @@ jobs:
       matrix:
         # Rows omit fields that match these defaults (applied in
         # Build_LLVM and in the setup-python step):
-        #   llvm_enable_projects: "clang"
         #   llvm_targets_to_build: "host;NVPTX"
         #   python-version:       '3.14'
         include:
@@ -91,24 +90,15 @@ jobs:
             compiler: gcc-12
             clang-runtime: '22'
             coverage: true
-          - name: ubu24-x86-gcc12-llvm22-oop-vg
+          - name: ubu24-x86-gcc12-llvm22-vg
             os: ubuntu-24.04
             compiler: gcc-12
             clang-runtime: '22'
-            llvm_enable_projects: "clang;compiler-rt"
-            oop-jit: On
             Valgrind: On
           # MacOS Arm
           - { name: osx26-arm-clang-llvm22, os: macos-26, compiler: clang, clang-runtime: '22', llvm_targets_to_build: host }
           - { name: osx26-arm-clang-llvm21-cppyy, os: macos-26, compiler: clang, clang-runtime: '21', cppyy: On, llvm_targets_to_build: host }
           - { name: osx26-arm-clang-cling-llvm20-cppyy, os: macos-26, compiler: clang, clang-runtime: '20', cling: On, cppyy: On, root-llvm-tag: *root_llvm_tag }
-          - name: osx26-arm-clang-llvm22-oop
-            os: macos-26
-            compiler: clang
-            clang-runtime: '22'
-            llvm_enable_projects: "clang;compiler-rt"
-            llvm_targets_to_build: host
-            oop-jit: On
           # MacOS X86
           - { name: osx26-x86-clang-llvm21-cppyy, os: macos-26-intel, compiler: clang, clang-runtime: '21', cppyy: On, llvm_targets_to_build: host }
           - { name: osx26-x86-clang-cling-llvm20-cppyy, os: macos-26-intel, compiler: clang, clang-runtime: '20', cling: On, cppyy: On, root-llvm-tag: *root_llvm_tag }
@@ -136,7 +126,7 @@ jobs:
         path: |
           llvm-project
           ${{ matrix.cling=='On' && 'cling' || '' }}
-        key: ${{ env.CLING_HASH }}-${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-clang-${{ matrix.clang-runtime }}-${{ matrix.root-llvm-tag || 'none' }}.x-patch-${{ hashFiles(format('patches/llvm/clang{0}-*.patch', matrix.clang-runtime)) || 'none' }}${{ matrix.oop-jit == 'On' && '-oop' || '' }}${{ matrix.sanitizer || '' }}
+        key: ${{ env.CLING_HASH }}-${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-clang-${{ matrix.clang-runtime }}-${{ matrix.root-llvm-tag || 'none' }}.x-patch-${{ hashFiles(format('patches/llvm/clang{0}-*.patch', matrix.clang-runtime)) || 'none' }}${{ matrix.sanitizer || '' }}
     - name: Setup default Build Type
       uses: ./.github/actions/Miscellaneous/Select_Default_Build_Type
 
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -339,16 +339,52 @@ include_directories(SYSTEM ${LLVM_INCLUDE_DIRS})
 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
 add_definitions(${LLVM_DEFINITIONS_LIST})
 
-string(REGEX REPLACE "/lib/cmake/llvm$" "" LLVM_BINARY_LIB_DIR "${LLVM_DIR}")
-add_definitions(-DLLVM_BINARY_LIB_DIR="${LLVM_BINARY_LIB_DIR}")
+# Bundle the ORC runtime + executor inside CppInterOp's distribution
+# so the OOP-JIT path is self-contained: no extra package to install,
+# no resource-dir scan in the host's clang tree at runtime. Paths are
+# baked at build time (CPPINTEROP_RUNTIME_{BUILD,INSTALL}_DIR in
+# Compatibility.h) and probed via fs::exists.
+set(CPPINTEROP_RUNTIME_SUBDIR "cppinterop-rt")
+set(CPPINTEROP_RUNTIME_BUILDTREE_DIR
+    "${CMAKE_BINARY_DIR}/lib/${CPPINTEROP_RUNTIME_SUBDIR}")
+
+if(LLVM_VERSION_MAJOR GREATER 21)
+  find_package(LLVMOrcRuntime QUIET MODULE)
+endif()
 
-if(LLVM_BUILT_WITH_OOP_JIT)
-  if((CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64") OR
-     (CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|aarch64|arm64"))
-    add_definitions(-DLLVM_BUILT_WITH_OOP_JIT)
-  else()
-    message(FATAL_ERROR "LLVM_BUILT_WITH_OOP_JIT is only supported on MacOS arm64 or Linux (x86_64/aarch64). Build aborted.")
-  endif()
+if(LLVMOrcRuntime_FOUND)
+  message(STATUS "CppInterOp OOP-JIT runtime:")
+  message(STATUS "  orc_rt:   ${LLVMOrcRuntime_LIBRARY}")
+  message(STATUS "  executor: ${LLVMOrcRuntime_EXECUTOR}")
+
+  file(MAKE_DIRECTORY "${CPPINTEROP_RUNTIME_BUILDTREE_DIR}")
+  configure_file("${LLVMOrcRuntime_LIBRARY}"
+                 "${CPPINTEROP_RUNTIME_BUILDTREE_DIR}/liborc_rt.a"
+                 COPYONLY)
+  configure_file("${LLVMOrcRuntime_EXECUTOR}"
+                 "${CPPINTEROP_RUNTIME_BUILDTREE_DIR}/llvm-jitlink-executor"
+                 COPYONLY)
+
+  install(FILES "${LLVMOrcRuntime_LIBRARY}"
+          DESTINATION "${CMAKE_INSTALL_LIBDIR}/${CPPINTEROP_RUNTIME_SUBDIR}"
+          RENAME liborc_rt.a)
+  install(PROGRAMS "${LLVMOrcRuntime_EXECUTOR}"
+          DESTINATION "${CMAKE_INSTALL_LIBDIR}/${CPPINTEROP_RUNTIME_SUBDIR}"
+          RENAME llvm-jitlink-executor)
+
+  # Bake build-tree and install-tree runtime locations into the library
+  # so it can locate the bundled parts at runtime without dladdr or any
+  # platform-specific self-DSO discovery.
+  add_definitions(
+    "-DCPPINTEROP_RUNTIME_BUILD_DIR=\"${CPPINTEROP_RUNTIME_BUILDTREE_DIR}\""
+    "-DCPPINTEROP_RUNTIME_INSTALL_DIR=\"${CMAKE_INSTALL_FULL_LIBDIR}/${CPPINTEROP_RUNTIME_SUBDIR}\"")
+elseif(LLVM_VERSION_MAJOR GREATER 21)
+  message(STATUS
+    "CppInterOp: OOP-JIT runtime (liborc_rt + llvm-jitlink-executor) "
+    "not found in ${LLVM_LIBRARY_DIR}. Out-of-process JIT support will "
+    "be unavailable. To enable it, build LLVM with compiler-rt and "
+    "ninja the llvm-jitlink-executor + orc_rt* targets, or install a "
+    "compiler-rt package that ships them.")
 endif()
 
 # If the llvm sources are present add them with higher priority.
diff --git a/README.md b/README.md
@@ -213,9 +213,11 @@ cmake -DBUILD_SHARED_LIBS=ON -DLLVM_DIR=$LLVM_DIR/build/lib/cmake/llvm -DClang_D
 cmake --build . --target install --parallel $(nproc --all)
 ```
 
-and
-
-> Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+> Out-of-process JIT auto-enables when CppInterOp is built against
+> LLVM 22+ with compiler-rt's ORC runtime available
+> (`liborc_rt*.a` and `llvm-jitlink-executor`). When detected, the
+> two artifacts are bundled under `<libdir>/cppinterop-rt/` so the
+> distribution is self-contained.
 
 #### Testing CppInterOp
 
diff --git a/cmake/FindLLVMOrcRuntime.cmake b/cmake/FindLLVMOrcRuntime.cmake
@@ -0,0 +1,51 @@
+# Locates the ORC runtime archive (compiler-rt's `orc_rt`) and the
+# `llvm-jitlink-executor` binary inside the LLVM tree we are linking
+# against. Used to bundle them into CppInterOp's distribution so the
+# OOP-JIT path works without an external `compiler-rt` install.
+#
+# Expects find_package(LLVM) to have run already (provides the input
+# variables below).
+#
+# Inputs:
+#   LLVM_LIBRARY_DIR
+#   LLVM_TOOLS_BINARY_DIR
+#   LLVM_VERSION_MAJOR
+#
+# Output cache variables:
+#   LLVMOrcRuntime_FOUND
+#   LLVMOrcRuntime_LIBRARY    Path to libclang_rt.orc_rt*.a / liborc_rt*.a
+#   LLVMOrcRuntime_EXECUTOR   Path to llvm-jitlink-executor
+
+include(FindPackageHandleStandardArgs)
+
+# compiler-rt installs into `clang/<ver>/lib/<triple>/`; the triple
+# subdir is host-derived (`darwin`, `x86_64-unknown-linux-gnu`, etc.).
+# Enumerate them at configure time rather than hard-coding the triple.
+file(GLOB _orc_hint_dirs LIST_DIRECTORIES TRUE
+  "${LLVM_LIBRARY_DIR}/clang/${LLVM_VERSION_MAJOR}/lib/*")
+
+# NAMES covers the spread of compiler-rt archive names across versions
+# and platforms: `libclang_rt.orc_rt.a` (modern, per-triple subdir),
+# `liborc_rt.a` (legacy unsuffixed), and the arch/OS-suffixed variants
+# `_osx` (macOS universal), `-x86_64`, `-aarch64`. NO_DEFAULT_PATH so
+# we never pick up a system-installed orc_rt with a different ABI than
+# the LLVM we're linking against.
+find_library(LLVMOrcRuntime_LIBRARY
+  NAMES
+    clang_rt.orc_rt
+    orc_rt
+    orc_rt_osx
+    orc_rt-x86_64
+    orc_rt-aarch64
+  HINTS ${_orc_hint_dirs}
+  NO_DEFAULT_PATH)
+
+find_program(LLVMOrcRuntime_EXECUTOR
+  NAMES llvm-jitlink-executor
+  HINTS "${LLVM_TOOLS_BINARY_DIR}"
+  NO_DEFAULT_PATH)
+
+find_package_handle_standard_args(LLVMOrcRuntime
+  REQUIRED_VARS LLVMOrcRuntime_LIBRARY LLVMOrcRuntime_EXECUTOR)
+
+mark_as_advanced(LLVMOrcRuntime_LIBRARY LLVMOrcRuntime_EXECUTOR)
diff --git a/docs/DevelopersDocumentation.rst b/docs/DevelopersDocumentation.rst
@@ -292,7 +292,11 @@ commands on Linux and MacOS
 
 .. note::
 
-   Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+   Out-of-process JIT auto-enables when CppInterOp is built against
+   LLVM 22+ with compiler-rt's ORC runtime available
+   (``liborc_rt*.a`` and ``llvm-jitlink-executor``). When detected,
+   the two artifacts are bundled under ``<libdir>/cppinterop-rt/`` so
+   the distribution is self-contained.
 
 and
 
diff --git a/docs/InstallationAndUsage.rst b/docs/InstallationAndUsage.rst
@@ -294,7 +294,11 @@ commands on Linux and MacOS
 
 .. note::
 
-   Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+   Out-of-process JIT auto-enables when CppInterOp is built against
+   LLVM 22+ with compiler-rt's ORC runtime available
+   (``liborc_rt*.a`` and ``llvm-jitlink-executor``). When detected,
+   the two artifacts are bundled under ``<libdir>/cppinterop-rt/`` so
+   the distribution is self-contained.
 
 and
 
diff --git a/lib/CppInterOp/Compatibility.h b/lib/CppInterOp/Compatibility.h
diff --git a/lib/CppInterOp/CppInterOpInterpreter.h b/lib/CppInterOp/CppInterOpInterpreter.h
diff --git a/unittests/CppInterOp/Utils.h b/unittests/CppInterOp/Utils.h
