Ship a linkable shared runtime and make the Python bindings use it by shoumikhin · Pull Request #21514 · pytorch/executorch

shoumikhin · 2026-07-31T06:23:26Z

Today pip install executorch gives you the Python half of ExecuTorch but
nothing a C++ application can link. The wheel installs a header subset and an
executorch-config.cmake, but that config only locates the Python extension so
custom-op builds can compile against it: it defines no runtime library and no
CMake targets. Writing a small C++ program that loads and runs a .pte means
cloning the repo, syncing submodules, and building from source.

This change ships the runtime as a real library and exposes it through
find_package, so a standalone application needs nothing but the wheel:

find_package(executorch REQUIRED)
target_link_libraries(my_app PRIVATE executorch::runtime)

executorch::runtime is an imported target whose location is resolved relative
to the config file itself, so the package stays relocatable and no path from the
machine that built the wheel is baked into it. A consumer picks up the wheel's
library directory in its RUNPATH, plus $ORIGIN-relative entries so an
application deployed next to a copy of the runtime keeps working without
LD_LIBRARY_PATH.

The Python extensions have to move to the shared runtime in the same change.
Backends register themselves into a single process-wide table owned by the
runtime, and that table is only process-wide if exactly one loaded library
defines it. The Python extension statically embeds the runtime today, so adding a
shared library beside it would give a process two independent registries, and a
backend could register into the one nobody reads. The extensions therefore link
the shared runtime instead of whole-archiving the static libraries, leaving
exactly one registry owner for both the Python and C++ paths.

Getting that right needs two linker details. The shared runtime is named through
a link option rather than an ordinary dependency, because CMake orders link
libraries so a static archive precedes what it depends on, which would let the
archive satisfy the runtime symbols first. It is also wrapped in
--no-as-needed, because a shared library with no already-referenced symbol at
the point it appears on the link line can be dropped, and a later static archive
would then supply the registry after all.

Registration still happens through static initializers exactly as before. No new
plugin or loader ABI is introduced.

The shared runtime is Linux-only for the wheel. macOS C++ consumers are served by
the existing Swift package distribution, and the runtime has no export
annotations for a Windows DLL. Every other build keeps linking the static
libraries, because the new behavior is gated on the existing
EXECUTORCH_BUILD_SHARED option, so iOS, Android, and embedded builds are
unaffected.

Test plan:

The wheel smoke test now covers this on Linux, so it is checked in CI rather than
only by hand. It asserts that exactly one shipped library defines the backend
registry, builds a standalone C++ program that only calls
find_package(executorch) and links executorch::runtime, runs it without
LD_LIBRARY_PATH, and checks the resulting binary depends on the shipped runtime
with a relocatable RUNPATH. The check was confirmed to fail when a second
registry definition is introduced deliberately. The wheel workflows now also run
when any CMakeLists.txt or anything under tools/cmake changes, since those
files decide what the wheel contains.

Built the wheel from a clean checkout on Linux x86_64 and on Linux aarch64, then
verified each against a fresh virtual environment with a normal
dependency-resolving install:

nm -DC across every shipped shared object shows exactly one definition of the
registry entry points; the Python extensions import them rather than defining
their own.
A C++ program whose CMake only calls find_package(executorch) and links
executorch::runtime compiles against the installed wheel with no source
checkout, then loads a .pte and lists its methods.
readelf -d on that program lists the versioned runtime in DT_NEEDED with
$ORIGIN-relative RUNPATH entries, and it runs without LD_LIBRARY_PATH.
A C++ binary that links only executorch::runtime and loads the Python
extension sees the backends that extension registered, which is the
one-registry property stated above.
import executorch, the registered backend list, and .pte execution through
the Python bindings are unchanged, with outputs matching eager PyTorch.
With EXECUTORCH_BUILD_SHARED off, the Python extension still builds
self-contained and no shared runtime is produced, so the previous behavior is
intact.
Configured with CMake 3.28 as well as 3.31, since the project supports 3.24 and
up and the two differ in how strictly they treat link features.

[ghstack-poisoned]

shoumikhin · 2026-07-31T06:23:27Z

Stack from ghstack (oldest at bottom):

-> Ship a linkable shared runtime and make the Python bindings use it #21514

pytorch-bot · 2026-07-31T06:23:30Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21514

📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 4 New Failures, 2 Pending, 2 Unrelated Failures, 47 Unclassified Failures

As of commit b741e2d with merge base d632341 ():

NEW FAILURES - The following jobs have failed:

nightly / link-check / lint-urls (gh)
nightly / link-check / lint-xrefs (gh)
periodic / test-models-linux (cmake, ds_cnn, portable, linux.2xlarge, 90) / linux-job (gh)
RuntimeError: Command docker exec -t 6645cdff250e70e26936eec71abdcb38a709fc8626ff0da16efa60d2893e0e13 /exec failed with exit code 134
periodic / test-models-linux (cmake, yolo26, portable, linux.2xlarge, 90) / linux-job (gh)
RuntimeError: Command docker exec -t d912255176455697ed9735204656d600a2704d43c71c2ce527ba90558f5d5270 /exec failed with exit code 1

UNCLASSIFIED FAILURES - DrCI could not classify the following jobs because the workflow did not run on the merge base. The failures may be pre-existing on trunk or introduced by this PR:

Build Aarch64 Linux Wheels / pytorch/executorch / build-wheel-py3_10-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Aarch64 Linux Wheels / pytorch/executorch / build-wheel-py3_11-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Aarch64 Linux Wheels / pytorch/executorch / build-wheel-py3_12-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Aarch64 Linux Wheels / pytorch/executorch / build-wheel-py3_13-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Aarch64 Linux Wheels / pytorch/executorch / build-wheel-py3_14-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
pyarrow
Build Aarch64 Linux Wheels / pytorch/executorch / upload / upload-wheel-py3_10-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Aarch64 Linux Wheels / pytorch/executorch / upload / upload-wheel-py3_11-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Aarch64 Linux Wheels / pytorch/executorch / upload / upload-wheel-py3_12-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Aarch64 Linux Wheels / pytorch/executorch / upload / upload-wheel-py3_13-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Aarch64 Linux Wheels / pytorch/executorch / upload / upload-wheel-py3_14-cpu-aarch64 (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Linux Wheels / pytorch/executorch / build-manywheel-py3_10-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Linux Wheels / pytorch/executorch / build-manywheel-py3_11-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Linux Wheels / pytorch/executorch / build-manywheel-py3_12-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Linux Wheels / pytorch/executorch / build-manywheel-py3_13-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
undefined reference to std::_Sp_counted_base<(__gnu_cxx::_Lock_policy)2>::_M_release_last_use_cold()'`
Build Linux Wheels / pytorch/executorch / build-manywheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
pyarrow
Build Linux Wheels / pytorch/executorch / upload / upload-manywheel-py3_10-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Linux Wheels / pytorch/executorch / upload / upload-manywheel-py3_11-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Linux Wheels / pytorch/executorch / upload / upload-manywheel-py3_12-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Linux Wheels / pytorch/executorch / upload / upload-manywheel-py3_13-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Linux Wheels / pytorch/executorch / upload / upload-manywheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build macOS Wheels / pytorch/executorch / build-wheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
pyarrow
Build macOS Wheels / pytorch/executorch / upload / upload-wheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Build Windows Wheels / pytorch/executorch / build-wheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
pyarrow
Build Windows Wheels / pytorch/executorch / upload / upload-wheel-py3_14-cpu (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
Unable to download artifact(s): Artifact not found
Test CUDA Builds / export-model-cuda-artifact (facebook, dinov2-small-imagenet1k-1-layer, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (google, gemma-3-4b-it, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (google, gemma-3-4b-it, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (mistralai, Voxtral-Mini-3B-2507, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (mistralai, Voxtral-Mini-3B-2507, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (mistralai, Voxtral-Mini-3B-2507, quantized-int4-weight-only) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (mistralai, Voxtral-Mini-4B-Realtime-2602, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (nvidia, diar_streaming_sortformer_4spk-v2, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (nvidia, parakeet-tdt, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (nvidia, parakeet-tdt, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (openai, whisper-large-v3-turbo, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (openai, whisper-large-v3-turbo, quantized-int4-weight-only) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (openai, whisper-small, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (Qwen, Qwen3-0.6B, non-quantized) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (Qwen, Qwen3-0.6B, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (SocialLocalMobile, Qwen3.5-35B-A3B-HQQ-INT4, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / export-model-cuda-artifact (unsloth, gemma-4-31B-it-GGUF, quantized-int4-tile-packed) / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / test-executorch-cuda-build-12.6 / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / test-executorch-cuda-build-13.0 / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / test-models-cuda / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / unittest-cuda / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test CUDA Builds / unittest-cuda-runtime / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch
Test Vulkan Backend (specialized runners) / test-vulkan-nvidia / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
executorch

FLAKY - The following jobs failed but were likely due to flakiness present on trunk:

pull / unittest-editable / windows / windows-job (gh) (detected as infra flaky with no log or failing log classifier)
Test CUDA Builds / check-all-cuda-builds (gh) (detected as infra flaky with no log or failing log classifier)

This comment was automatically generated by Dr. CI and updates every 15 minutes.

github-actions · 2026-07-31T06:24:14Z

This PR needs a `release notes:` label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

Copilot

🟡 Not ready to approve

The new shared-runtime linking logic uses GNU ld-specific flags without platform guards, which can break builds when EXECUTORCH_BUILD_SHARED is enabled on non-ELF toolchains.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR makes the ExecuTorch wheel usable as a C++ SDK by shipping a linkable shared runtime (libexecutorch.so) and exposing it via find_package(executorch) as executorch::runtime, while also updating the Python extensions to link against that shared runtime to preserve a single process-wide backend registry.

Changes:

Add a consolidated shared runtime target (executorch_shared / libexecutorch.so) and update multiple extension/tool targets to resolve runtime symbols from it.
Extend the wheel CMake package config to provide an imported target executorch::runtime resolved relative to the installed wheel for relocatable consumption.
Add CI wheel smoke coverage that verifies single-registry behavior and that a standalone C++ app can build/run via only find_package(executorch) + executorch::runtime.

File summaries

File	Description
tools/cmake/Utils.cmake	Adds helper to force linking against the shared runtime early on the link line.
tools/cmake/preset/pybind.cmake	Enables `EXECUTORCH_BUILD_SHARED` for the Linux pybind preset to ship the shared runtime in wheels.
tools/cmake/executorch-wheel-config.cmake	Exposes `executorch::runtime` imported target and keeps legacy `_portable_lib` discovery.
tools/cmake/Codegen.cmake	Avoids linking `executorch_core` when shared runtime is enabled; forces shared runtime resolution.
setup.py	Installs the shared runtime SONAME into the wheel and expands header install coverage for runtime-linked extensions.
kernels/quantized/CMakeLists.txt	Adds wheel-runtime-relative RPATH when shared runtime is enabled.
extension/training/CMakeLists.txt	Switches pybind training module to shared runtime path and fixes RPATH for wheel layout.
extension/llm/runner/CMakeLists.txt	Forces shared runtime resolution and adjusts RPATH when shared runtime is enabled.
extension/llm/custom_ops/CMakeLists.txt	Ensures wheel-built artifact has correct RPATH and resolves runtime from shared library.
devtools/etdump/CMakeLists.txt	Avoids `executorch` whole-archive when shared runtime is present; links shared runtime instead.
devtools/bundled_program/CMakeLists.txt	Avoids whole-archive duplication by linking shared runtime when enabled.
codegen/tools/CMakeLists.txt	Makes selective_build resolve runtime via shared library and sets wheel-relative RPATH.
CMakeLists.txt	Defines `executorch_shared` earlier and updates pybind/utility targets to avoid embedding duplicate registries.
.github/workflows/build-wheels-*.yml	Expands workflow path triggers to include CMakeLists and `tools/cmake/`.
.ci/scripts/wheel/test_linux.py	Runs the new C++ SDK wheel test as part of Linux wheel smoke tests.
.ci/scripts/wheel/test_linux_aarch64.py	Runs the new C++ SDK wheel test as part of aarch64 Linux wheel smoke tests.
.ci/scripts/wheel/test_cpp_sdk.py	New test that validates single-registry and that a standalone C++ app can link/run via the wheel.

Review details

Files reviewed: 20/20 changed files
Comments generated: 2
Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[ghstack-poisoned]

Today `pip install executorch` gives you the Python half of ExecuTorch but nothing a C++ application can link. The wheel installs a header subset and an `executorch-config.cmake`, but that config only locates the Python extension so custom-op builds can compile against it: it defines no runtime library and no CMake targets. Writing a small C++ program that loads and runs a `.pte` means cloning the repo, syncing submodules, and building from source. This change ships the runtime as a real library and exposes it through `find_package`, so a standalone application needs nothing but the wheel: find_package(executorch REQUIRED) target_link_libraries(my_app PRIVATE executorch::runtime) `executorch::runtime` is an imported target whose location is resolved relative to the config file itself, so the package stays relocatable and no path from the machine that built the wheel is baked into it. A consumer picks up the wheel's library directory in its RUNPATH, plus `$ORIGIN`-relative entries so an application deployed next to a copy of the runtime keeps working without `LD_LIBRARY_PATH`. The Python extensions have to move to the shared runtime in the same change. Backends register themselves into a single process-wide table owned by the runtime, and that table is only process-wide if exactly one loaded library defines it. The Python extension statically embeds the runtime today, so adding a shared library beside it would give a process two independent registries, and a backend could register into the one nobody reads. The extensions therefore link the shared runtime instead of whole-archiving the static libraries, leaving exactly one registry owner for both the Python and C++ paths. Getting that right needs two linker details. The shared runtime is named through a link option rather than an ordinary dependency, because CMake orders link libraries so a static archive precedes what it depends on, which would let the archive satisfy the runtime symbols first. It is also wrapped in `--no-as-needed`, because a shared library with no already-referenced symbol at the point it appears on the link line can be dropped, and a later static archive would then supply the registry after all. Registration still happens through static initializers exactly as before. No new plugin or loader ABI is introduced. The shared runtime is Linux-only for the wheel. macOS C++ consumers are served by the existing Swift package distribution, and the runtime has no export annotations for a Windows DLL. Every other build keeps linking the static libraries, because the new behavior is gated on the existing `EXECUTORCH_BUILD_SHARED` option, so iOS, Android, and embedded builds are unaffected. Test plan: The wheel smoke test now covers this on Linux, so it is checked in CI rather than only by hand. It asserts that exactly one shipped library defines the backend registry, builds a standalone C++ program that only calls `find_package(executorch)` and links `executorch::runtime`, runs it without `LD_LIBRARY_PATH`, and checks the resulting binary depends on the shipped runtime with a relocatable RUNPATH. The check was confirmed to fail when a second registry definition is introduced deliberately. The wheel workflows now also run when any `CMakeLists.txt` or anything under `tools/cmake` changes, since those files decide what the wheel contains. Built the wheel from a clean checkout on Linux x86_64 and on Linux aarch64, then verified each against a fresh virtual environment with a normal dependency-resolving install: - `nm -DC` across every shipped shared object shows exactly one definition of the registry entry points; the Python extensions import them rather than defining their own. - A C++ program whose CMake only calls `find_package(executorch)` and links `executorch::runtime` compiles against the installed wheel with no source checkout, then loads a `.pte` and lists its methods. - `readelf -d` on that program lists the versioned runtime in `DT_NEEDED` with `$ORIGIN`-relative RUNPATH entries, and it runs without `LD_LIBRARY_PATH`. - A C++ binary that links only `executorch::runtime` and loads the Python extension sees the backends that extension registered, which is the one-registry property stated above. - `import executorch`, the registered backend list, and `.pte` execution through the Python bindings are unchanged, with outputs matching eager PyTorch. - With `EXECUTORCH_BUILD_SHARED` off, the Python extension still builds self-contained and no shared runtime is produced, so the previous behavior is intact. - Configured with CMake 3.28 as well as 3.31, since the project supports 3.24 and up and the two differ in how strictly they treat link features. ghstack-source-id: ab9b01b ghstack-comment-id: 5139976402 Pull-Request: #21514

shoumikhin · 2026-07-31T06:51:54Z

Good catch, fixed in the latest push.

Both of these were real. The whole-archive loop used to go through
$<LINK_LIBRARY:WHOLE_ARCHIVE,...>, which CMake maps to the right flag per
platform, and switching to raw flags lost that. There is now a small
executorch_target_whole_archive helper next to the existing kernel-link helpers
that picks --whole-archive, -force_load, or /WHOLEARCHIVE based on the
platform, and the shared-runtime helper only adds --no-as-needed on ELF
platforms. No raw GNU flag is emitted outside those two helpers now.

Worth noting the option that reaches this code is only turned on for Linux today,
so this is about not breaking someone who enables it by hand rather than a live
failure. Verified by building the wheel and running the wheel checks on Linux
x86_64 and aarch64 after the change.

Copilot

🟡 Not ready to approve

The new executorch::runtime CMake config has correctness/robustness issues (duplicate target definition risk and unconditional Python failure path) that can break consumers during configuration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (3)

tools/cmake/executorch-wheel-config.cmake:121

With the new executorch::runtime target, a pure C++ consumer should be able to configure successfully even if python3 isn't available on PATH. Right now the unconditional execute_process(${PYTHON_EXECUTABLE} ...) followed by FATAL_ERROR prevents using the shared runtime without Python. Consider treating EXT_SUFFIX lookup as best-effort when the shared runtime was found, and skip _portable_lib discovery in that case.

find_library(
  _portable_lib_LIBRARY
  NAMES _portable_lib${EXT_SUFFIX}
  PATHS "${_executorch_package_root}/extension/pybindings/"
)

tools/cmake/executorch-wheel-config.cmake:121

find_library() will also search default system locations, which can accidentally pick up a different _portable_lib<EXT_SUFFIX> (e.g., from another install) and silently mix headers/libs. Since this config is meant to bind to the wheel it lives in, add NO_DEFAULT_PATH to restrict the search to the wheel directory.

find_library(
  _portable_lib_LIBRARY
  NAMES _portable_lib${EXT_SUFFIX}
  PATHS "${_executorch_package_root}/extension/pybindings/"
)

tools/cmake/executorch-wheel-config.cmake:68

executorch-config.cmake can be processed more than once in a single configure (e.g., multiple find_package(executorch) calls via subprojects). Unconditionally calling add_library(executorch::runtime ...) will then error with a duplicate target name. Guard the add_library call with if(NOT TARGET executorch::runtime) but still apply the target properties afterward.

This issue also appears in the following locations of the same file:

line 117
line 117

  add_library(executorch::runtime SHARED IMPORTED)
  set_target_properties(
    executorch::runtime
    PROPERTIES IMPORTED_LOCATION "${_executorch_runtime_library}"
               INTERFACE_INCLUDE_DIRECTORIES "${EXECUTORCH_INCLUDE_DIRS}"

Files reviewed: 20/20 changed files
Comments generated: 0 new
Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[ghstack-poisoned]

Today `pip install executorch` gives you the Python half of ExecuTorch but nothing a C++ application can link. The wheel installs a header subset and an `executorch-config.cmake`, but that config only locates the Python extension so custom-op builds can compile against it: it defines no runtime library and no CMake targets. Writing a small C++ program that loads and runs a `.pte` means cloning the repo, syncing submodules, and building from source. This change ships the runtime as a real library and exposes it through `find_package`, so a standalone application needs nothing but the wheel: find_package(executorch REQUIRED) target_link_libraries(my_app PRIVATE executorch::runtime) `executorch::runtime` is an imported target whose location is resolved relative to the config file itself, so the package stays relocatable and no path from the machine that built the wheel is baked into it. A consumer picks up the wheel's library directory in its RUNPATH, plus `$ORIGIN`-relative entries so an application deployed next to a copy of the runtime keeps working without `LD_LIBRARY_PATH`. The Python extensions have to move to the shared runtime in the same change. Backends register themselves into a single process-wide table owned by the runtime, and that table is only process-wide if exactly one loaded library defines it. The Python extension statically embeds the runtime today, so adding a shared library beside it would give a process two independent registries, and a backend could register into the one nobody reads. The extensions therefore link the shared runtime instead of whole-archiving the static libraries, leaving exactly one registry owner for both the Python and C++ paths. Getting that right needs two linker details. The shared runtime is named through a link option rather than an ordinary dependency, because CMake orders link libraries so a static archive precedes what it depends on, which would let the archive satisfy the runtime symbols first. It is also wrapped in `--no-as-needed`, because a shared library with no already-referenced symbol at the point it appears on the link line can be dropped, and a later static archive would then supply the registry after all. Registration still happens through static initializers exactly as before. No new plugin or loader ABI is introduced. The shared runtime is Linux-only for the wheel. macOS C++ consumers are served by the existing Swift package distribution, and the runtime has no export annotations for a Windows DLL. Every other build keeps linking the static libraries, because the new behavior is gated on the existing `EXECUTORCH_BUILD_SHARED` option, so iOS, Android, and embedded builds are unaffected. Test plan: The wheel smoke test now covers this on Linux, so it is checked in CI rather than only by hand. It asserts that exactly one shipped library defines the backend registry, builds a standalone C++ program that only calls `find_package(executorch)` and links `executorch::runtime`, runs it without `LD_LIBRARY_PATH`, and checks the resulting binary depends on the shipped runtime with a relocatable RUNPATH. The check was confirmed to fail when a second registry definition is introduced deliberately. The wheel workflows now also run when any `CMakeLists.txt` or anything under `tools/cmake` changes, since those files decide what the wheel contains. Built the wheel from a clean checkout on Linux x86_64 and on Linux aarch64, then verified each against a fresh virtual environment with a normal dependency-resolving install: - `nm -DC` across every shipped shared object shows exactly one definition of the registry entry points; the Python extensions import them rather than defining their own. - A C++ program whose CMake only calls `find_package(executorch)` and links `executorch::runtime` compiles against the installed wheel with no source checkout, then loads a `.pte` and lists its methods. - `readelf -d` on that program lists the versioned runtime in `DT_NEEDED` with `$ORIGIN`-relative RUNPATH entries, and it runs without `LD_LIBRARY_PATH`. - A C++ binary that links only `executorch::runtime` and loads the Python extension sees the backends that extension registered, which is the one-registry property stated above. - `import executorch`, the registered backend list, and `.pte` execution through the Python bindings are unchanged, with outputs matching eager PyTorch. - With `EXECUTORCH_BUILD_SHARED` off, the Python extension still builds self-contained and no shared runtime is produced, so the previous behavior is intact. - Configured with CMake 3.28 as well as 3.31, since the project supports 3.24 and up and the two differ in how strictly they treat link features. ghstack-source-id: 401229a ghstack-comment-id: 5139976402 Pull-Request: #21514

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Update

5416595

[ghstack-poisoned]

shoumikhin requested a review from larryliu0820 as a code owner July 31, 2026 06:23

Copilot AI review requested due to automatic review settings July 31, 2026 06:23

shoumikhin requested a review from kirklandsign as a code owner July 31, 2026 06:23

shoumikhin temporarily deployed to cadence July 31, 2026 06:23 — with GitHub Actions Inactive

meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Jul 31, 2026

Copilot started reviewing on behalf of shoumikhin July 31, 2026 06:24 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Comment thread tools/cmake/Utils.cmake

Comment thread CMakeLists.txt Outdated

shoumikhin had a problem deploying to cadence July 31, 2026 06:47 — with GitHub Actions Error

Update

008351d

[ghstack-poisoned]

Copilot AI review requested due to automatic review settings July 31, 2026 06:51

shoumikhin temporarily deployed to cadence July 31, 2026 06:51 — with GitHub Actions Inactive

Copilot started reviewing on behalf of shoumikhin July 31, 2026 06:51 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

shoumikhin temporarily deployed to cadence July 31, 2026 07:19 — with GitHub Actions Inactive

Update

b741e2d

[ghstack-poisoned]

Copilot AI review requested due to automatic review settings July 31, 2026 14:53

Copilot AI reviewed Jul 31, 2026

shoumikhin temporarily deployed to cadence July 31, 2026 14:54 — with GitHub Actions Inactive

shoumikhin added ciflow/periodic ciflow/trunk labels Jul 31, 2026

shoumikhin added ciflow/binaries ciflow/binaries/all Release PRs with this label will build wheels for all python versions ciflow/nightly ciflow/cuda labels Jul 31, 2026

pytorch-bot Bot temporarily deployed to cadence July 31, 2026 15:08 Inactive

shoumikhin temporarily deployed to cadence July 31, 2026 15:23 — with GitHub Actions Inactive

pytorch-bot Bot temporarily deployed to cadence July 31, 2026 15:32 Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Ship a linkable shared runtime and make the Python bindings use it - #21514

Ship a linkable shared runtime and make the Python bindings use it#21514
shoumikhin wants to merge 3 commits into
mainfrom
gh/shoumikhin/78/head

shoumikhin commented Jul 31, 2026

Uh oh!

shoumikhin commented Jul 31, 2026 •

edited

Loading

Uh oh!

pytorch-bot Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

shoumikhin commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

shoumikhin commented Jul 31, 2026

Uh oh!

shoumikhin commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pytorch-bot Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21514

❌ 4 New Failures, 2 Pending, 2 Unrelated Failures, 47 Unclassified Failures

Uh oh!

github-actions Bot commented Jul 31, 2026

This PR needs a release notes: label

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Not ready to approve

Uh oh!

Uh oh!

Uh oh!

shoumikhin commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Not ready to approve

Suppressed comments (3)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shoumikhin commented Jul 31, 2026 •

edited

Loading

pytorch-bot Bot commented Jul 31, 2026 •

edited

Loading

This PR needs a `release notes:` label