@@ -57,5 +57,116 @@ An engine rejects a method whose semantics it cannot fully honor.
5757| Vulkan | ` runtime/vulkan/ ` | Builds on the ET-VK ` ComputeGraph ` and shaders. |
5858| ggml | ` runtime/engine/ggml/ ` | CPU, CUDA, HIP, and Metal variants. |
5959
60- The runtime currently builds only with Meta's internal Buck setup; there is no
61- open-source build yet.
60+ ## Building with CMake
61+
62+ Enable ` EXECUTORCH_BUILD_NATIVE=ON ` to build the shared native runtime. With it,
63+ ` EXECUTORCH_BUILD_NATIVE_VULKAN=ON ` adds the Vulkan engine and
64+ ` EXECUTORCH_BUILD_NATIVE_GGML=ON ` adds the GGML engine. All three options default
65+ to ` OFF ` ; the engine options are ignored unless ` EXECUTORCH_BUILD_NATIVE=ON ` and
66+ can be enabled together.
67+
68+ The native runtime requires C++20, a host ` flatc ` , the vendored FlatBuffers and
69+ nlohmann JSON headers, and an installed libzip package with the ` libzip::zip `
70+ CMake target. Set ` CMAKE_PREFIX_PATH ` to the libzip installation if necessary.
71+ Native Vulkan also requires the Vulkan submodules and ` glslc ` , as described in
72+ the [ Vulkan build instructions] ( ../vulkan/README.md ) .
73+
74+ From the ExecuTorch checkout:
75+
76+ ``` sh
77+ cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
78+ -DEXECUTORCH_BUILD_NATIVE=ON -DEXECUTORCH_BUILD_NATIVE_VULKAN=ON
79+ cmake --build cmake-out --target native_api native_vulkan_engine
80+ cmake --install cmake-out --prefix install
81+ ```
82+
83+ ### Shared targets
84+
85+ | Target | Contents |
86+ | --- | --- |
87+ | ` native_graph ` | Graph IR, graph utilities, and memory planning |
88+ | ` native_package ` | PTN archive, safetensors, and owned byte readers |
89+ | ` native_runtime ` | Program deserialization, validation, and method metadata |
90+ | ` native_engine ` | Engine host, context, and executable interfaces |
91+ | ` native_api ` | Engine-independent ` Model ` , ` Session ` , and tensor API |
92+ | ` native_vulkan_passes ` | Native graph rewrites for Vulkan |
93+ | ` native_vulkan_engine ` | Vulkan host and executable implementation |
94+ | ` native_ggml_engine ` | GGML host, graph lowering, and executable implementation |
95+ | ` vulkan_compute_api ` | Vulkan device, allocator, and command API |
96+ | ` vulkan_graph_runtime ` | ComputeGraph, operator registrations, and shaders |
97+
98+ The common native targets have no dependency on the ExecuTorch executor or a
99+ specific engine. New engines link ` native_engine ` and implement its interfaces.
100+ Applications link ` native_api ` and the engines they use. The Vulkan engine and
101+ the existing ` vulkan_backend ` delegate share ` vulkan_graph_runtime ` ; its static
102+ operator and shader registrations are retained automatically when linking.
103+
104+ All library targets are installed in ` ExecuTorchTargets ` . For example:
105+
106+ ``` cmake
107+ find_package(executorch CONFIG REQUIRED)
108+ target_link_libraries(my_app PRIVATE native_api native_vulkan_engine)
109+ ```
110+
111+ With ` EXECUTORCH_BUILD_TESTS=ON ` , ` native_runtime_test ` covers the shared runtime
112+ and API. ` native_vulkan_passes_test ` covers the Vulkan graph rewrites without
113+ requiring a GPU. When the vision runner below is enabled,
114+ ` native_runner_utils_test ` covers its shared runner utilities. Run these with
115+ ` ctest --test-dir cmake-out -R native_ ` .
116+
117+ ### GGML engine
118+
119+ Native GGML builds the GGML subtree of the llama.cpp submodule at
120+ ` backends/native/third-party/llama.cpp ` , pinned to
121+ ` 620d2225cc436ab0b001e3200e590e3b286ef9ab ` . This matches the Buck dependency
122+ used to validate this CMake integration. The build requires ` GGML_CPU=ON `
123+ and ` GGML_BACKEND_DL=OFF ` , which are the defaults.
124+
125+ ``` sh
126+ git submodule update --init backends/native/third-party/llama.cpp
127+ cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
128+ -DEXECUTORCH_BUILD_NATIVE=ON -DEXECUTORCH_BUILD_NATIVE_GGML=ON \
129+ -DEXECUTORCH_BUILD_TESTS=ON
130+ cmake --build cmake-out --target native_api native_ggml_engine native_ggml_engine_test
131+ ctest --test-dir cmake-out -R native_ggml_engine_test --output-on-failure
132+ cmake --install cmake-out --prefix install
133+ ```
134+
135+ Applications link ` native_api ` and ` native_ggml_engine ` , then create a
136+ ` ptn::GgmlEngineHost ` . Its default device is CPU. For GPU execution, configure
137+ ExecuTorch with the desired GGML backend (for example, ` GGML_CUDA=ON ` ,
138+ ` GGML_HIP=ON ` , or ` GGML_METAL=ON ` ) and set ` ptn::GgmlEngineOptions::device ` to
139+ ` ptn::GgmlDevice::Gpu ` . CPU support is required even when selecting a GPU.
140+
141+ The CMake installation includes the GGML libraries and package configuration.
142+ It also copies the submodule's upstream MIT license, including its copyright
143+ notice, to ` share/licenses/executorch/ggml/LICENSE ` under the installation
144+ prefix (or the corresponding ` CMAKE_INSTALL_DATADIR ` location).
145+
146+ ` EXECUTORCH_BUILD_TESTS=ON ` adds ` native_ggml_engine_test ` , which runs the existing
147+ CPU engine tests, including quantized linear execution, graph caching, and
148+ mutable buffers.
149+
150+ ### Vision classification runner
151+
152+ Enable ` EXECUTORCH_BUILD_NATIVE_VISION_RUNNER=ON ` together with
153+ ` EXECUTORCH_BUILD_NATIVE_VULKAN=ON ` to build ` run_classification ` from
154+ ` examples/vision ` . The runner additionally requires gflags; an OSS build uses
155+ the vendored copy, and other builds resolve an installed gflags package.
156+ Running the runner requires a Vulkan device.
157+
158+ ``` sh
159+ cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
160+ -DEXECUTORCH_BUILD_NATIVE=ON -DEXECUTORCH_BUILD_NATIVE_VULKAN=ON \
161+ -DEXECUTORCH_BUILD_NATIVE_VISION_RUNNER=ON
162+ cmake --build cmake-out --target run_classification
163+ cmake --install cmake-out --prefix install
164+ install/bin/run_classification \
165+ --package mv2.ptn --input mv2_input.bin \
166+ --expected mv2_expected.bin --categories categories.txt
167+ ```
168+
169+ Export the ` .ptn ` , input, reference logits, and labels with
170+ [ ` export.py ` ] ( ../../examples/native/vision/export.py ) . The runner prints the
171+ top-5 logits and, when ` --expected ` is given, exits nonzero if the logits
172+ differ from the reference beyond ` --rtol ` /` --atol ` (both default to ` 1e-3 ` ).
0 commit comments