Skip to content

Commit a0a365b

Browse files
authored
Package Native, Vulkan, and GGML as an executorch-native wheel (#24069)
Summary: Add a separately installable Linux SDK wheel containing the Native runtime, Vulkan engine and shaders, and GGML CPU engine. Its CMake package lets consumers build the shipped vision runner without rebuilding the runtime, and the package coexists with `executorch`. Keep the standalone wheel recipe in `backends/native/python` and its Python wrappers alongside the runtime in `backends/native/pybindings`. CMake installs those sources into `executorch_native`; the source tree does not need a nested copy of the import package. Python execution bindings are added in the following diff. Authored with assistance from Codex. Reviewed By: SS-JIA Differential Revision: D126459370 Pull Request resolved: #24069
1 parent 724da85 commit a0a365b

12 files changed

Lines changed: 566 additions & 3 deletions

File tree

‎backends/native/examples/vision/CMakeLists.txt‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,34 @@
44
# This source code is licensed under the BSD-style license found in the
55
# LICENSE file in the root directory of this source tree.
66

7+
cmake_minimum_required(VERSION 3.24)
8+
9+
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
10+
project(native_vision_runner LANGUAGES CXX)
11+
include(GNUInstallDirs)
12+
find_package(executorch_native CONFIG REQUIRED)
13+
set(EXECUTORCH_ROOT "${executorch_native_PREFIX}/include/executorch")
14+
add_subdirectory(../runner_utils runner_utils)
15+
set(_native_vision_runtime executorch_native::runtime)
16+
17+
if(NOT TARGET gflags AND NOT TARGET gflags::gflags)
18+
find_package(gflags REQUIRED)
19+
endif()
20+
if(TARGET gflags::gflags)
21+
set(_native_runner_gflags gflags::gflags)
22+
else()
23+
set(_native_runner_gflags gflags)
24+
endif()
25+
else()
26+
set(_native_vision_runtime native_engine native_package native_runtime
27+
native_vulkan_engine
28+
)
29+
endif()
30+
731
add_executable(run_classification run_classification.cpp)
832
target_link_libraries(
9-
run_classification
10-
PRIVATE ${_native_runner_gflags} native_engine native_package
11-
native_runner_utils native_runtime native_vulkan_engine
33+
run_classification PRIVATE ${_native_runner_gflags} native_runner_utils
34+
${_native_vision_runtime}
1235
)
1336
target_compile_options(
1437
run_classification PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/EHsc>
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
install(
8+
FILES __init__.py __main__.py
9+
DESTINATION .
10+
COMPONENT executorch_native
11+
)
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
from pathlib import Path
8+
9+
10+
def cmake_prefix_path() -> str:
11+
"""Return the installed Native SDK prefix for CMake consumers."""
12+
return str(Path(__file__).resolve().parent)
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
import argparse
8+
from pathlib import Path
9+
10+
from executorch_native import cmake_prefix_path
11+
12+
13+
def main() -> None:
14+
parser = argparse.ArgumentParser(description="Locate the ExecuTorch Native SDK")
15+
paths = parser.add_mutually_exclusive_group(required=True)
16+
paths.add_argument("--cmake-prefix-path", action="store_true")
17+
paths.add_argument("--example-path", action="store_true")
18+
args = parser.parse_args()
19+
prefix = Path(cmake_prefix_path())
20+
print(prefix / "share/examples/vision" if args.example_path else prefix)
21+
22+
23+
if __name__ == "__main__":
24+
main()
Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
cmake_minimum_required(VERSION 3.26)
8+
project(executorch_native_wheel LANGUAGES C CXX)
9+
10+
if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
11+
message(FATAL_ERROR "The Native SDK wheel currently supports Linux only")
12+
endif()
13+
14+
get_filename_component(
15+
EXECUTORCH_ROOT "${CMAKE_CURRENT_LIST_DIR}/../../.." ABSOLUTE
16+
)
17+
set(BUILD_SHARED_LIBS OFF)
18+
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
19+
set(CMAKE_INSTALL_LIBDIR lib)
20+
set(EXECUTORCH_OPTIMIZE_SIZE OFF)
21+
set(EXECUTORCH_BUILD_NATIVE ON)
22+
set(EXECUTORCH_BUILD_NATIVE_VULKAN ON)
23+
set(EXECUTORCH_BUILD_NATIVE_GGML ON)
24+
set(EXECUTORCH_BUILD_NATIVE_VISION_RUNNER OFF)
25+
set(EXECUTORCH_BUILD_SHARED OFF)
26+
set(EXECUTORCH_BUILD_XNNPACK OFF)
27+
set(EXECUTORCH_BUILD_VULKAN OFF)
28+
set(EXECUTORCH_BUILD_EXECUTOR_RUNNER OFF)
29+
set(EXECUTORCH_BUILD_PYBIND OFF)
30+
set(EXECUTORCH_BUILD_TESTS OFF)
31+
set(EXECUTORCH_BUILD_CPUINFO OFF)
32+
set(EXECUTORCH_BUILD_PTHREADPOOL OFF)
33+
set(EXECUTORCH_BUILD_PORTABLE_OPS OFF)
34+
set(BUILD_TESTING OFF)
35+
foreach(
36+
feature
37+
NATIVE
38+
AVX
39+
AVX2
40+
AVX_VNNI
41+
BMI2
42+
FMA
43+
F16C
44+
AVX512
45+
AVX512_VBMI
46+
AVX512_VNNI
47+
AVX512_BF16
48+
AMX_TILE
49+
AMX_INT8
50+
AMX_BF16
51+
)
52+
set(GGML_${feature}
53+
OFF
54+
CACHE BOOL "Portable wheel CPU baseline" FORCE
55+
)
56+
endforeach()
57+
58+
set(GGML_BACKEND_DL OFF)
59+
set(GGML_CPU ON)
60+
set(GGML_OPENMP OFF)
61+
62+
add_subdirectory("${EXECUTORCH_ROOT}" executorch EXCLUDE_FROM_ALL)
63+
64+
file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/sdk.cpp" "")
65+
add_library(executorch_native_sdk SHARED "${CMAKE_CURRENT_BINARY_DIR}/sdk.cpp")
66+
target_link_libraries(
67+
executorch_native_sdk
68+
PRIVATE
69+
"$<LINK_LIBRARY:WHOLE_ARCHIVE,native_api,native_engine,native_runtime,native_package,native_graph,native_vulkan_engine,native_ggml_engine>"
70+
)
71+
target_compile_features(executorch_native_sdk INTERFACE cxx_std_20)
72+
target_include_directories(
73+
executorch_native_sdk INTERFACE $<INSTALL_INTERFACE:include>
74+
)
75+
target_link_options(
76+
executorch_native_sdk PRIVATE
77+
"LINKER:--version-script=${CMAKE_CURRENT_SOURCE_DIR}/exports.map"
78+
"LINKER:--no-undefined" "LINKER:--gc-sections"
79+
)
80+
set_target_properties(
81+
executorch_native_sdk
82+
PROPERTIES
83+
OUTPUT_NAME executorch_native
84+
EXPORT_NAME runtime
85+
INSTALL_RPATH "$ORIGIN"
86+
LINK_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/exports.map"
87+
LINK_LIBRARY_OVERRIDE
88+
"WHOLE_ARCHIVE,native_api,native_engine,native_runtime,native_package,native_graph,native_vulkan_engine,native_ggml_engine"
89+
)
90+
91+
add_subdirectory(../pybindings pybindings)
92+
93+
install(
94+
TARGETS executorch_native_sdk
95+
EXPORT ExecuTorchNativeTargets
96+
LIBRARY DESTINATION lib COMPONENT executorch_native
97+
)
98+
install(
99+
EXPORT ExecuTorchNativeTargets
100+
NAMESPACE executorch_native::
101+
DESTINATION lib/cmake/executorch_native
102+
COMPONENT executorch_native
103+
)
104+
install(
105+
FILES executorch_native-config.cmake
106+
DESTINATION lib/cmake/executorch_native
107+
COMPONENT executorch_native
108+
)
109+
install(
110+
DIRECTORY ../runtime/
111+
DESTINATION include/executorch/backends/native/runtime
112+
COMPONENT executorch_native
113+
FILES_MATCHING
114+
PATTERN "*.h"
115+
PATTERN "test" EXCLUDE
116+
PATTERN "vulkan" EXCLUDE
117+
PATTERN "ggml" EXCLUDE
118+
PATTERN "Json.h" EXCLUDE
119+
)
120+
install(
121+
FILES ../runtime/vulkan/VulkanEngine.h
122+
DESTINATION include/executorch/backends/native/runtime/vulkan
123+
COMPONENT executorch_native
124+
)
125+
install(
126+
FILES ../runtime/engine/ggml/GgmlEngine.h
127+
DESTINATION include/executorch/backends/native/runtime/engine/ggml
128+
COMPONENT executorch_native
129+
)
130+
install(
131+
DIRECTORY ../examples/vision ../examples/runner_utils
132+
DESTINATION share/examples
133+
COMPONENT executorch_native
134+
FILES_MATCHING
135+
PATTERN "CMakeLists.txt"
136+
PATTERN "run_classification.cpp"
137+
PATTERN "runner_utils.cpp"
138+
PATTERN "runner_utils.h"
139+
)
140+
install(
141+
FILES ../examples/runner_utils/runner_utils.h
142+
DESTINATION include/executorch/backends/native/examples/runner_utils
143+
COMPONENT executorch_native
144+
)
145+
install(
146+
FILES "${EXECUTORCH_ROOT}/LICENSE"
147+
DESTINATION share/licenses
148+
COMPONENT executorch_native
149+
)
150+
install(
151+
FILES "${EXECUTORCH_ROOT}/backends/native/third-party/llama.cpp/LICENSE"
152+
DESTINATION share/licenses/ggml
153+
COMPONENT executorch_native
154+
)
155+
foreach(
156+
license
157+
third-party/flatbuffers/LICENSE
158+
third-party/json/LICENSE.MIT
159+
backends/vulkan/third-party/volk/LICENSE.md
160+
backends/vulkan/third-party/Vulkan-Headers/LICENSE.md
161+
backends/vulkan/third-party/VulkanMemoryAllocator/LICENSE.txt
162+
)
163+
get_filename_component(dependency "${license}" DIRECTORY)
164+
install(
165+
FILES "${EXECUTORCH_ROOT}/${license}"
166+
DESTINATION "share/licenses/${dependency}"
167+
COMPONENT executorch_native
168+
)
169+
endforeach()
170+
171+
set(EXECUTORCH_NATIVE_EXTRA_LICENSES
172+
""
173+
CACHE STRING "License files for external libraries bundled into the wheel"
174+
)
175+
foreach(license IN LISTS EXECUTORCH_NATIVE_EXTRA_LICENSES)
176+
get_filename_component(dependency "${license}" DIRECTORY)
177+
get_filename_component(dependency "${dependency}" NAME)
178+
install(
179+
FILES "${license}"
180+
DESTINATION "share/licenses/dependencies/${dependency}"
181+
COMPONENT executorch_native
182+
)
183+
endforeach()

‎backends/native/python/README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# ExecuTorch Native SDK wheel
2+
3+
This directory contains the standalone wheel build recipe. Python sources live
4+
alongside the runtime in [`../pybindings`](../pybindings); CMake installs them as
5+
`executorch_native`. The wheel does not depend on the `executorch` distribution.
6+
7+
`executorch-native` packages the Native runtime, Vulkan engine (including compiled
8+
shaders), and GGML CPU engine. It installs into `executorch_native`, independently
9+
of the existing `executorch` distribution. It has no PyTorch dependency and does
10+
not install exporters or Python execution bindings. Export `.ptn` files using a
11+
matching version of `executorch` on the development machine.
12+
13+
The initial wheel supports Linux. It contains C++20 headers and a shared library;
14+
it is independent of the CPython ABI, but platform and C++ ABI compatibility still
15+
apply. Vulkan execution requires a system Vulkan loader and a compatible driver.
16+
17+
## Use the installed SDK
18+
19+
The SDK requires the libzip runtime. If your wheel does not bundle it, install
20+
the system package before running an SDK application, for example:
21+
22+
```sh
23+
sudo apt install libzip5
24+
```
25+
26+
The package name varies by distribution and release. Wheels repaired with
27+
`auditwheel` normally bundle libzip, as described below.
28+
29+
After obtaining a built wheel:
30+
31+
```sh
32+
python -m pip install executorch_native-*.whl
33+
cmake -S "$(python -m executorch_native --example-path)" -B vision-build \
34+
-DCMAKE_BUILD_TYPE=Release \
35+
-DCMAKE_PREFIX_PATH="$(python -m executorch_native --cmake-prefix-path)"
36+
cmake --build vision-build --parallel
37+
vision-build/run_classification --package model.ptn --input input.bin \
38+
--expected expected.bin
39+
```
40+
41+
This compiles only the runner and its small I/O utilities. The example also
42+
requires the gflags development package (for example `libgflags-dev` on Ubuntu).
43+
It needs neither an ExecuTorch checkout nor a shader compiler, GGML, or libzip
44+
development package. The wheel is a prototype; it is not yet published to PyPI.
45+
46+
Other applications can consume the same SDK:
47+
48+
```cmake
49+
find_package(executorch_native CONFIG REQUIRED)
50+
target_link_libraries(my_application PRIVATE executorch_native::runtime)
51+
```
52+
53+
Both `ptn::VulkanEngineHost` and `ptn::GgmlEngineHost` are available through this
54+
target. Native headers retain their `executorch/backends/native/...` include
55+
paths. The wheel owns no files under the `executorch` Python package and exports
56+
only the `ptn` API from its shared library, keeping bundled implementation symbols
57+
private when an application also loads ExecuTorch.
58+
59+
## Build a wheel
60+
61+
Build from a complete ExecuTorch source checkout with its pinned submodules
62+
initialized. Build dependencies are the same as the Native CMake build: a C++20
63+
compiler, libzip development files, and `glslc` from Vulkan SDK 1.4.341.1 or newer.
64+
65+
```sh
66+
python -m pip install build auditwheel patchelf
67+
python -m build --wheel backends/native/python --outdir dist/native \
68+
-Ccmake.define.EXECUTORCH_NATIVE_EXTRA_LICENSES=/path/to/libzip/LICENSE
69+
auditwheel repair dist/native/*.whl --wheel-dir dist/native/repaired
70+
```
71+
72+
Supply the license files for external libraries bundled by the build or repair
73+
step through `EXECUTORCH_NATIVE_EXTRA_LICENSES` (a semicolon-separated list).
74+
Distribute the repaired wheel: repair bundles shared dependencies such as libzip
75+
and assigns a compatible manylinux tag. For release wheels, build in the chosen
76+
manylinux image for each supported architecture; building on a newer Linux host
77+
does not establish compatibility with older systems. GGML uses portable CPU
78+
settings, with native tuning and optional x86 instruction sets disabled, rather
79+
than assuming the build machine's instruction set is available on every consumer.
80+
Keep the existing ExecuTorch release version; the wheel reads `version.txt`.
81+
82+
The build reuses existing CMake targets and installs only the Native wheel
83+
component. Building source distributions from this subdirectory is not supported;
84+
build wheels directly from the complete checkout.
85+
86+
## Validate the installed wheel
87+
88+
Generate the small test model on the build machine, then configure the tests
89+
against an installed, repaired wheel in a fresh environment:
90+
91+
```sh
92+
python backends/native/python/tests/make_fixture.py --flatc /path/to/flatc \
93+
--output /tmp/native-fixture
94+
cmake -S backends/native/python/tests -B sdk-test \
95+
-DCMAKE_PREFIX_PATH="$(python -m executorch_native --cmake-prefix-path)" \
96+
-DNATIVE_TEST_PACKAGE=/tmp/native-fixture/add.ptn
97+
cmake --build sdk-test
98+
ctest --test-dir sdk-test --output-on-failure
99+
```
100+
101+
Add `-DNATIVE_TEST_VULKAN=ON` to test both engines when a Vulkan device is
102+
available. The installed vision example also accepts this fixture with
103+
`--input /tmp/native-fixture/input.bin --expected /tmp/native-fixture/expected.bin`.
104+
The fixture generator needs `flatc`; consumers of the wheel do not.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
include("${CMAKE_CURRENT_LIST_DIR}/ExecuTorchNativeTargets.cmake")
8+
get_filename_component(
9+
executorch_native_PREFIX "${CMAKE_CURRENT_LIST_DIR}/../../.." ABSOLUTE
10+
)

‎backends/native/python/exports.map‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
global:
3+
_ZN3ptn*;
4+
_ZNK3ptn*;
5+
_ZTIN3ptn*;
6+
_ZTSN3ptn*;
7+
_ZTVN3ptn*;
8+
local: *;
9+
};

0 commit comments

Comments
 (0)