Add CMake targets for the native Vulkan engine and run_classification runner (#23811)

Summary:
Pull Request resolved: #23811

Add engine-independent CMake libraries for the native graph, PTN package reader, program runtime, engine interface, and standalone API. `EXECUTORCH_BUILD_NATIVE` enables the common libraries; `EXECUTORCH_BUILD_NATIVE_VULKAN` also enables `native_vulkan_engine`.

`EXECUTORCH_BUILD_NATIVE_VISION_RUNNER` (requires `EXECUTORCH_BUILD_NATIVE_VULKAN`) additionally builds the `examples/vision` classification runner as `run_classification` plus its `native_runner_utils` library. The runner links `native_vulkan_engine` and gflags and installs to `bin/`. Its existing `test_runner_utils.cpp` coverage runs as `native_runner_utils_test` under `EXECUTORCH_BUILD_TESTS`.

Authored with Codex and Muse Code.

Differential Revision: D125084367

Author: JakeStevens

CMakeLists.txt

@@ -328,6 +328,12 @@ else()
   set(BUILD_TESTING OFF)
 endif()
 
+if(EXECUTORCH_BUILD_NATIVE
+   OR EXECUTORCH_BUILD_NATIVE_VULKAN
+   OR EXECUTORCH_BUILD_NATIVE_GGML
+)
+  set(JSON_Install ON)
+endif()
 add_subdirectory(third-party)
 
 # On Apple, pybind11 SHARED extension modules must not link libpython directly.
@@ -838,14 +844,38 @@ elseif(EXECUTORCH_BUILD_CUDA)
          "find_dependency(CUDAToolkit)\n"
   )
 endif()
+if(EXECUTORCH_BUILD_NATIVE
+   OR EXECUTORCH_BUILD_NATIVE_VULKAN
+   OR EXECUTORCH_BUILD_NATIVE_GGML
+)
+  string(APPEND _executorch_backend_dependencies
+         "find_dependency(libzip CONFIG)\n"
+         "find_dependency(nlohmann_json CONFIG)\n"
+  )
+endif()
+if(EXECUTORCH_BUILD_NATIVE_GGML)
+  string(APPEND _executorch_backend_dependencies
+         "find_dependency(ggml 0.24 CONFIG)\n"
+  )
+endif()
+if(EXECUTORCH_BUILD_NATIVE
+   OR EXECUTORCH_BUILD_NATIVE_VULKAN
+   OR EXECUTORCH_BUILD_NATIVE_GGML
+   OR EXECUTORCH_BUILD_VULKAN
+)
+  string(APPEND _executorch_backend_dependencies "find_dependency(Threads)\n")
+endif()
 configure_file(
   tools/cmake/executorch-backend-dependencies.cmake.in
   ${CMAKE_CURRENT_BINARY_DIR}/executorch-backend-dependencies.cmake @ONLY
 )
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/executorch-backend-dependencies.cmake
         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ExecuTorch
 )
-if(EXECUTORCH_BUILD_VULKAN OR EXECUTORCH_BUILD_VGF)
+if(EXECUTORCH_BUILD_VULKAN
+   OR EXECUTORCH_BUILD_VGF
+   OR EXECUTORCH_BUILD_NATIVE_VULKAN
+)
   add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/backends/vulkan_shared)
 endif()
 
@@ -1686,6 +1716,13 @@ if(EXECUTORCH_BUILD_VULKAN)
   list(APPEND _executorch_backends vulkan_backend vulkan_schema)
 endif()
 
+if(EXECUTORCH_BUILD_NATIVE
+   OR EXECUTORCH_BUILD_NATIVE_VULKAN
+   OR EXECUTORCH_BUILD_NATIVE_GGML
+)
+  add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/backends/native)
+endif()
+
 if(EXECUTORCH_BUILD_WEBGPU)
   add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/backends/webgpu)
   list(APPEND _executorch_backends webgpu_backend)

backends/native/CMakeLists.txt

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+cmake_minimum_required(VERSION 3.24)
+
+if(NOT EXECUTORCH_ROOT)
+  get_filename_component(
+    EXECUTORCH_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE
+  )
+endif()
+
+include(GNUInstallDirs)
+include(${EXECUTORCH_ROOT}/tools/cmake/Utils.cmake)
+
+if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
+  set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+endif()
+
+find_package(Threads REQUIRED)
+find_package(libzip CONFIG REQUIRED)
+if(NOT TARGET nlohmann_json::nlohmann_json)
+  find_package(nlohmann_json CONFIG REQUIRED)
+endif()
+
+add_subdirectory(runtime)
+
+if(EXECUTORCH_BUILD_NATIVE_VULKAN)
+  add_subdirectory(runtime/vulkan)
+endif()
+
+if(EXECUTORCH_BUILD_NATIVE_GGML)
+  add_subdirectory(runtime/engine/ggml)
+endif()
+
+install(
+  DIRECTORY runtime/
+  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/executorch/backends/native/runtime
+  FILES_MATCHING
+  PATTERN "*.h"
+  PATTERN "test" EXCLUDE
+  PATTERN "vulkan" EXCLUDE
+  PATTERN "ggml" EXCLUDE
+)
+
+if(EXECUTORCH_BUILD_NATIVE_VISION_RUNNER)
+  if(NOT EXECUTORCH_BUILD_NATIVE_VULKAN)
+    message(
+      FATAL_ERROR
+        "EXECUTORCH_BUILD_NATIVE_VISION_RUNNER requires EXECUTORCH_BUILD_NATIVE_VULKAN=ON"
+    )
+  endif()
+  add_subdirectory(examples)
+endif()
+
+if(EXECUTORCH_BUILD_TESTS)
+  add_subdirectory(test)
+endif()

backends/native/README.md

@@ -0,0 +1,112 @@
+# Native runtime CMake targets
+
+Enable `EXECUTORCH_BUILD_NATIVE=ON` to build the shared native runtime, or
+`EXECUTORCH_BUILD_NATIVE_VULKAN=ON` to build it together with the Vulkan engine.
+`EXECUTORCH_BUILD_NATIVE_GGML=ON` builds it together with the GGML engine.
+All three options default to `OFF`; the engine options can be enabled together.
+
+The native runtime requires C++20, a host `flatc`, the vendored FlatBuffers and
+nlohmann JSON headers, and an installed libzip package with the `libzip::zip`
+CMake target. Set `CMAKE_PREFIX_PATH` to the libzip installation if necessary.
+Native Vulkan also requires the Vulkan submodules and `glslc`, as described in
+the [Vulkan build instructions](../vulkan/README.md).
+
+From the ExecuTorch checkout:
+
+```sh
+cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
+  -DEXECUTORCH_BUILD_NATIVE_VULKAN=ON
+cmake --build cmake-out --target native_api native_vulkan_engine
+cmake --install cmake-out --prefix install
+```
+
+## Shared targets
+
+| Target | Contents |
+| --- | --- |
+| `native_graph` | Graph IR, graph utilities, and memory planning |
+| `native_package` | PTN archive, safetensors, and owned byte readers |
+| `native_runtime` | Program deserialization, validation, and method metadata |
+| `native_engine` | Engine host, context, and executable interfaces |
+| `native_api` | Engine-independent `Model`, `Session`, and tensor API |
+| `native_vulkan_passes` | Native graph rewrites for Vulkan |
+| `native_vulkan_engine` | Vulkan host and executable implementation |
+| `native_ggml_engine` | GGML host, graph lowering, and executable implementation |
+| `vulkan_compute_api` | Vulkan device, allocator, and command API |
+| `vulkan_graph_runtime` | ComputeGraph, operator registrations, and shaders |
+
+The common native targets have no dependency on the ExecuTorch executor or a
+specific engine. New engines link `native_engine` and implement its interfaces.
+Applications link `native_api` and the engines they use. The Vulkan engine and
+the existing `vulkan_backend` delegate share `vulkan_graph_runtime`; its static
+operator and shader registrations are retained automatically when linking.
+
+All library targets are installed in `ExecuTorchTargets`. For example:
+
+```cmake
+find_package(executorch CONFIG REQUIRED)
+target_link_libraries(my_app PRIVATE native_api native_vulkan_engine)
+```
+
+With `EXECUTORCH_BUILD_TESTS=ON`, `native_runtime_test` covers the shared runtime
+and API. `native_vulkan_passes_test` covers the Vulkan graph rewrites without
+requiring a GPU. When the vision runner below is enabled,
+`native_runner_utils_test` covers its shared runner utilities. Run these with
+`ctest --test-dir cmake-out -R native_`.
+
+## GGML engine
+
+Native GGML requires an installed GGML 0.24 or newer package providing
+`ggml::ggml`, built with `GGML_CPU=ON` and `GGML_BACKEND_DL=OFF`. For example,
+build the GGML sources from llama.cpp revision
+`60081bb2b5b3294165a4d67c5cbeebe74c868014` (the version used by the Buck build):
+
+```sh
+cmake -S /path/to/llama.cpp/ggml -B ggml-build \
+  -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PWD/ggml-install" \
+  -DGGML_CPU=ON -DGGML_BACKEND_DL=OFF \
+  -DGGML_BUILD_TESTS=OFF -DGGML_BUILD_EXAMPLES=OFF
+cmake --build ggml-build --parallel
+cmake --install ggml-build
+cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
+  -DEXECUTORCH_BUILD_NATIVE_GGML=ON -DEXECUTORCH_BUILD_TESTS=ON \
+  -DCMAKE_PREFIX_PATH="$PWD/ggml-install"
+cmake --build cmake-out --target native_api native_ggml_engine native_ggml_engine_test
+ctest --test-dir cmake-out -R native_ggml_engine_test --output-on-failure
+cmake --install cmake-out --prefix install
+```
+
+Applications link `native_api` and `native_ggml_engine`, then create a
+`ptn::GgmlEngineHost`. Its default device is CPU. For GPU execution, build GGML
+with the desired backend (for example, `GGML_CUDA=ON`, `GGML_HIP=ON`, or
+`GGML_METAL=ON`) and set `ptn::GgmlEngineOptions::device` to
+`ptn::GgmlDevice::Gpu`. The GGML package supplies the backend libraries and their
+dependencies. CPU support is required even when selecting a GPU.
+
+`EXECUTORCH_BUILD_TESTS=ON` adds `native_ggml_engine_test`, which runs the existing
+CPU engine tests, including quantized linear execution, graph caching, and
+mutable buffers.
+
+## Vision classification runner
+
+Enable `EXECUTORCH_BUILD_NATIVE_VISION_RUNNER=ON` together with
+`EXECUTORCH_BUILD_NATIVE_VULKAN=ON` to build `run_classification` from
+`examples/vision`. The runner additionally requires gflags; an OSS build uses
+the vendored copy, and other builds resolve an installed gflags package.
+Running the runner requires a Vulkan device.
+
+```sh
+cmake -S . -B cmake-out -DCMAKE_BUILD_TYPE=Release \
+  -DEXECUTORCH_BUILD_NATIVE_VULKAN=ON \
+  -DEXECUTORCH_BUILD_NATIVE_VISION_RUNNER=ON
+cmake --build cmake-out --target run_classification
+cmake --install cmake-out --prefix install
+install/bin/run_classification \
+  --package mv2.ptn --input mv2_input.bin \
+  --expected mv2_expected.bin --categories categories.txt
+```
+
+Export the `.ptn`, input, reference logits, and labels with
+[`export.py`](../../examples/native/vision/export.py). The runner prints the
+top-5 logits and, when `--expected` is given, exits nonzero if the logits
+differ from the reference beyond `--rtol`/`--atol` (both default to `1e-3`).

backends/native/examples/CMakeLists.txt

@@ -0,0 +1,8 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+add_subdirectory(runner_utils)
+add_subdirectory(vision)

backends/native/examples/runner_utils/CMakeLists.txt

@@ -0,0 +1,15 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+add_library(native_runner_utils STATIC runner_utils.cpp)
+target_compile_features(native_runner_utils PUBLIC cxx_std_20)
+target_compile_options(
+  native_runner_utils PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/EHsc>
+                              $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-fexceptions>
+)
+target_include_directories(
+  native_runner_utils PUBLIC $<BUILD_INTERFACE:${EXECUTORCH_ROOT}/..>
+)

backends/native/examples/vision/CMakeLists.txt

@@ -0,0 +1,33 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+if(NOT EXECUTORCH_BUILD_NATIVE_VULKAN)
+  message(
+    FATAL_ERROR "run_classification requires EXECUTORCH_BUILD_NATIVE_VULKAN=ON"
+  )
+endif()
+
+if(NOT TARGET gflags AND NOT TARGET gflags::gflags)
+  find_package(gflags REQUIRED)
+endif()
+if(TARGET gflags::gflags)
+  set(_native_vision_gflags gflags::gflags)
+else()
+  set(_native_vision_gflags gflags)
+endif()
+
+add_executable(run_classification run_classification.cpp)
+target_link_libraries(
+  run_classification
+  PRIVATE ${_native_vision_gflags} native_engine native_package
+          native_runner_utils native_runtime native_vulkan_engine
+)
+target_compile_options(
+  run_classification PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/EHsc>
+                             $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-fexceptions>
+)
+
+install(TARGETS run_classification RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

backends/native/runtime/CMakeLists.txt

@@ -0,0 +1,96 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+set(_native_schema_dir
+    ${CMAKE_CURRENT_BINARY_DIR}/include/executorch/backends/native/runtime
+)
+set(_native_schema_header ${_native_schema_dir}/native_graph_generated.h)
+add_custom_command(
+  OUTPUT ${_native_schema_header}
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${_native_schema_dir}
+  COMMAND
+    flatc --cpp --cpp-std c++11 --gen-mutable --scoped-enums -o
+    ${_native_schema_dir}
+    ${CMAKE_CURRENT_SOURCE_DIR}/../serialization/native_graph.fbs
+  DEPENDS flatc ${CMAKE_CURRENT_SOURCE_DIR}/../serialization/native_graph.fbs
+  COMMENT "Generating native graph schema"
+  VERBATIM
+)
+add_library(native_graph_schema INTERFACE ${_native_schema_header})
+target_include_directories(
+  native_graph_schema
+  INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
+    $<BUILD_INTERFACE:${EXECUTORCH_ROOT}/third-party/flatbuffers/include>
+)
+add_custom_target(native_graph_schema_gen DEPENDS ${_native_schema_header})
+add_dependencies(native_graph_schema native_graph_schema_gen)
+
+add_library(
+  native_graph
+  graph/Argument.cpp
+  graph/Graph.cpp
+  graph/MemoryPlanning.cpp
+  graph/Node.cpp
+  graph/Scalar.cpp
+  graph/TensorMeta.cpp
+  graph/Value.cpp
+  graph/utils/GraphUtils.cpp
+)
+
+add_library(native_reference_gguf_kquant utils/ReferenceGgufKQuant.cpp)
+target_link_libraries(native_reference_gguf_kquant PRIVATE Threads::Threads)
+
+add_library(
+  native_package deserialize/OwnedBytes.cpp deserialize/Package.cpp
+                 deserialize/SafeTensorsReader.cpp deserialize/ZipReader.cpp
+)
+target_link_libraries(
+  native_package
+  PUBLIC native_graph
+  PRIVATE libzip::zip nlohmann_json::nlohmann_json Threads::Threads
+)
+
+add_library(
+  native_runtime Deserialize.cpp Program.cpp MethodMeta.cpp TensorInfo.cpp
+                 Validation.cpp
+)
+target_link_libraries(
+  native_runtime
+  PUBLIC native_graph native_package
+  PRIVATE $<BUILD_INTERFACE:native_graph_schema> Threads::Threads
+)
+add_dependencies(native_runtime native_graph_schema_gen)
+
+add_library(native_engine engine/Engine.cpp)
+target_link_libraries(native_engine PUBLIC native_runtime)
+
+add_library(native_api api/Model.cpp)
+target_link_libraries(native_api PUBLIC native_engine)
+
+foreach(target native_graph native_reference_gguf_kquant native_package
+               native_runtime native_engine native_api
+)
+  add_library(executorch::${target} ALIAS ${target})
+  target_compile_features(${target} PUBLIC cxx_std_20)
+  target_compile_options(
+    ${target} PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/EHsc>
+                      $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-fexceptions>
+  )
+  target_include_directories(
+    ${target} PUBLIC $<BUILD_INTERFACE:${EXECUTORCH_ROOT}/..>
+                     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+  )
+endforeach()
+
+install(
+  TARGETS native_graph native_reference_gguf_kquant native_package
+          native_runtime native_engine native_api
+  EXPORT ExecuTorchTargets
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)