Update selective build example + CI for top-level targets

Author: GregoryComer

examples/selective_build/README.md

@@ -1,5 +1,7 @@
 # Selective Build Examples
-To optimize binary size of ExecuTorch runtime, selective build can be used. This folder contains examples to select only the operators needed for ExecuTorch build. This example will demonstrate the CMake build.
+To optimize binary size of ExecuTorch runtime, selective build can be used. This folder contains examples to select only the operators needed for ExecuTorch build.
+
+These examples showcase two flows - the simple way, using CMake options to configure the framework build, and an advanced flow - showcasing user-defined kernel targets including custom operators.
 
 ## How to run
 
@@ -12,12 +14,20 @@ cd executorch
 bash examples/selective_build/test_selective_build.sh cmake
 ```
 
+## Selective Build APIs
+
+As mentioned above, these examples showcases two flows for enabling kernel selective build - via CMake options or via a user-defined
+kernel target. When building the code in this directory, the `EXECUTORCH_EXAMPLE_DEFINE_CUSTOM_TARGET` CMake option controls which
+approach is used. When unset or set to `OFF`, the
+
+### CMake Options
+
 Check out `CMakeLists.txt` for demo of selective build APIs:
 1. `SELECT_ALL_OPS`: Select all ops from the dependency kernel libraries, register all of them into ExecuTorch runtime.
 2. `SELECT_OPS_LIST`: Only select operators from a list.
 3. `SELECT_OPS_YAML`: Only select operators from a yaml file.
-4. `SELECT_OPS_FROM_MODEL`: Only select operators from a from an exported model pte.
-5. `DTYPE_SELECTIVE_BUILD`: Enable rebuild of `portable_kernels` to use dtype selection. Currently only supported for `SELECTED_OPS_FROM_MODEL` API and `portable_kernels` lib.
+4. `SELECT_OPS_MODEL`: Only select operators from a from an exported model pte.
+5. `DTYPE_SELECTIVE_BUILD`: Enable rebuild of `portable_kernels` to use dtype selection. Currently only supported for `SELECTED_OPS_MODEL` API and `portable_kernels` lib.
 
 Other configs:
 - `MAX_KERNEL_NUM=N`: Only allocate memory for N operators.

examples/selective_build/CMakeLists.txt renamed to examples/selective_build/advanced/CMakeLists.txt

@@ -37,56 +37,39 @@ set(_common_compile_options -Wno-deprecated-declarations -fPIC
                             -ffunction-sections -fdata-sections
 )
 
-# Let files say "include <executorch/path/to/header.h>".
-set(_common_include_directories ${EXECUTORCH_ROOT}/..)
-
-find_package(executorch CONFIG REQUIRED)
-find_package(
-  gflags REQUIRED PATHS ${CMAKE_CURRENT_BINARY_DIR}/../../third-party
-)
-
-target_include_directories(
-  executorch_core INTERFACE ${_common_include_directories}
-)
+add_subdirectory(${EXECUTORCH_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/executorch)
 
 # ------------------------------ OPTIONS BEGIN -------------------------------
 
-# Option to register ops from yaml file
-option(EXECUTORCH_SELECT_OPS_YAML "Register all the ops from a given yaml file"
-       OFF
-)
-
-# Option to register op list
-option(EXECUTORCH_SELECT_OPS_LIST "Register a list of ops, separated by comma"
-       OFF
-)
-
 # Selective build options.
-option(EXECUTORCH_SELECT_ALL_OPS
+option(EXECUTORCH_EXAMPLE_SELECT_ALL_OPS
        "Whether to register all ops defined in portable kernel library." OFF
 )
 
-# Option to enable parsing ops and dtypes directly from model pte file
-option(EXECUTORCH_SELECT_OPS_FROM_MODEL
-       "Enable op selection from pte during build." OFF
+option(
+  EXECUTORCH_EXAMPLE_USE_CUSTOM_OPS
+  "Whether to include custom ops in the example."
+  OFF
 )
 
-# Option to enable dtype selective build. Note: must be using selective build
-# model API.
-option(EXECUTORCH_DTYPE_SELECTIVE_BUILD "Enable dtype selective build." OFF)
+# Note that the following options are defined by the core framework and are also
+# used by this example when defining a custom operator target:
+#
+# EXECUTORCH_SELECT_OPS_YAML EXECUTORCH_SELECT_OPS_LIST
+# EXECUTORCH_SELECT_OPS_MODEL EXECUTORCH_DTYPE_SELECTIVE_BUILD
+
 # ------------------------------- OPTIONS END --------------------------------
 
 #
 # The `_<target>_srcs` lists are defined by executorch_load_build_variables.
 #
 executorch_load_build_variables()
 
-#
-# select_build_lib: C++ library to register selected ops in custom kernel
-# library
-#
+# For advanced use cases, we can define a custom operator target. This is
+# useful when using custom operators.
 set(_kernel_lib)
-if(EXECUTORCH_SELECT_OPS_YAML)
+
+if(EXECUTORCH_EXAMPLE_USE_CUSTOM_OPS)
   set(_custom_ops_yaml
       ${EXECUTORCH_ROOT}/examples/portable/custom_ops/custom_ops.yaml
   )
@@ -116,7 +99,7 @@ gen_selected_ops(
   INCLUDE_ALL_OPS
   "${EXECUTORCH_SELECT_ALL_OPS}"
   OPS_FROM_MODEL
-  "${EXECUTORCH_SELECT_OPS_FROM_MODEL}"
+  "${EXECUTORCH_SELECT_OPS_MODEL}"
   DTYPE_SELECTIVE_BUILD
   "${EXECUTORCH_DTYPE_SELECTIVE_BUILD}"
 )
@@ -143,6 +126,9 @@ gen_operators_lib(
   "${EXECUTORCH_DTYPE_SELECTIVE_BUILD}"
 )
 
+executorch_target_link_options_shared_lib(select_build_lib)
+set(selected_kernel_target select_build_lib)
+
 list(TRANSFORM _executor_runner__srcs PREPEND "${EXECUTORCH_ROOT}/")
 
 #
@@ -154,8 +140,8 @@ if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
   target_link_options_gc_sections(selective_build_test)
 endif()
 target_link_libraries(
-  selective_build_test PRIVATE executorch_core extension_evalue_util
-                               extension_runner_util gflags select_build_lib
+  selective_build_test
+  PRIVATE executorch_core extension_evalue_util extension_runner_util
+          gflags::gflags ${selected_kernel_target}
 )
-executorch_target_link_options_shared_lib(select_build_lib)
 target_compile_options(selective_build_test PUBLIC ${_common_compile_options})

examples/selective_build/basic/CMakeLists.txt

@@ -0,0 +1,77 @@
+# 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.
+
+#
+# Simple CMake build system for selective build demo.
+#
+# ### Editing this file ###
+#
+# This file should be formatted with
+# ~~~
+# cmake-format -i CMakeLists.txt
+# ~~~
+# It should also be cmake-lint clean.
+#
+cmake_minimum_required(VERSION 3.19)
+project(selective_build_example)
+
+set(EXECUTORCH_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../..)
+set(TORCH_ROOT ${EXECUTORCH_ROOT}/third-party/pytorch)
+
+include(${EXECUTORCH_ROOT}/tools/cmake/Utils.cmake)
+include(${EXECUTORCH_ROOT}/tools/cmake/Codegen.cmake)
+
+if(NOT PYTHON_EXECUTABLE)
+  resolve_python_executable()
+endif()
+
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+  # Can't set to 11 due to executor_runner.cpp make_unique
+endif()
+
+set(_common_compile_options -Wno-deprecated-declarations -fPIC
+                            -ffunction-sections -fdata-sections
+)
+
+add_subdirectory(${EXECUTORCH_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/executorch)
+
+# ------------------------------ OPTIONS BEGIN -------------------------------
+
+# The following options are defined by the core framework and are also used in
+# the generated kernel target.
+#
+# EXECUTORCH_SELECT_OPS_YAML EXECUTORCH_SELECT_OPS_LIST
+# EXECUTORCH_SELECT_OPS_MODEL EXECUTORCH_DTYPE_SELECTIVE_BUILD
+
+# ------------------------------- OPTIONS END --------------------------------
+
+#
+# The `_<target>_srcs` lists are defined by executorch_load_build_variables.
+#
+executorch_load_build_variables()
+
+# For most use cases, we can configure the ExecuTorch kernel library build
+# using the EXECUTORCH_SELECT_OPS_* variables. This will reflect in the
+# executorch_kernels target, which includes the configured kernel libraries,
+# including selective build, where supported.
+
+list(TRANSFORM _executor_runner__srcs PREPEND "${EXECUTORCH_ROOT}/")
+
+#
+# selective_build_test: test binary to allow different operator libraries to
+# link to
+#
+add_executable(selective_build_test ${_executor_runner__srcs})
+if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
+  target_link_options_gc_sections(selective_build_test)
+endif()
+target_link_libraries(
+  selective_build_test
+  PRIVATE executorch_core extension_evalue_util extension_runner_util
+          gflags::gflags executorch_kernels
+)
+target_compile_options(selective_build_test PUBLIC ${_common_compile_options})

examples/selective_build/test_selective_build.sh

@@ -85,35 +85,11 @@ test_buck2_select_ops_from_yaml() {
 }
 
 # CMake examples; test in OSS. Check the README for more information.
-test_cmake_select_all_ops() {
-    echo "Exporting MobilenetV3"
-    ${PYTHON_EXECUTABLE} -m examples.portable.scripts.export --model_name="mv3"
-
-    local example_dir=examples/selective_build
-    local build_dir=cmake-out/${example_dir}
-    rm -rf ${build_dir}
-    retry cmake -DCMAKE_BUILD_TYPE=Release \
-            -DEXECUTORCH_SELECT_ALL_OPS=ON \
-            -DCMAKE_INSTALL_PREFIX=cmake-out \
-            -DPYTHON_EXECUTABLE="$PYTHON_EXECUTABLE" \
-            -B${build_dir} \
-            ${example_dir}
-
-    echo "Building ${example_dir}"
-    cmake --build ${build_dir} -j9 --config Release
-
-    echo 'Running selective build test'
-    ${build_dir}/selective_build_test --model_path="./mv3.pte"
-
-    echo "Removing mv3.pte"
-    rm "./mv3.pte"
-}
-
 test_cmake_select_ops_in_list() {
     echo "Exporting MobilenetV2"
     ${PYTHON_EXECUTABLE} -m examples.portable.scripts.export --model_name="mv2"
 
-    local example_dir=examples/selective_build
+    local example_dir=examples/selective_build/basic
     local build_dir=cmake-out/${example_dir}
     # set MAX_KERNEL_NUM=22: 19 primops, add, mul
     rm -rf ${build_dir}
@@ -141,11 +117,12 @@ aten,aten::clone.out" \
 test_cmake_select_ops_in_yaml() {
     echo "Exporting custom_op_1"
     ${PYTHON_EXECUTABLE} -m examples.portable.custom_ops.custom_ops_1
-    local example_dir=examples/selective_build
+    local example_dir=examples/selective_build/advanced
     local build_dir=cmake-out/${example_dir}
     rm -rf ${build_dir}
     retry cmake -DCMAKE_BUILD_TYPE=Release \
-            -DEXECUTORCH_SELECT_OPS_YAML=ON \
+            -DEXECUTORCH_EXAMPLE_USE_CUSTOM_OPS=ON \
+            -DEXECUTORCH_EXAMPLE_DEFINE_CUSTOM_TARGET=ON \
             -DCMAKE_INSTALL_PREFIX=cmake-out \
             -DPYTHON_EXECUTABLE="$PYTHON_EXECUTABLE" \
             -B${build_dir} \
@@ -166,11 +143,11 @@ test_cmake_select_ops_in_model() {
     local model_export_name="${model_name}.pte"
     echo "Exporting ${model_name}"
     ${PYTHON_EXECUTABLE} -m examples.portable.scripts.export --model_name="${model_name}"
-    local example_dir=examples/selective_build
+    local example_dir=examples/selective_build/basic
     local build_dir=cmake-out/${example_dir}
     rm -rf ${build_dir}
     retry cmake -DCMAKE_BUILD_TYPE="$CMAKE_BUILD_TYPE" \
-            -DEXECUTORCH_SELECT_OPS_FROM_MODEL="./${model_export_name}" \
+            -DEXECUTORCH_SELECT_OPS_MODEL="./${model_export_name}" \
             -DEXECUTORCH_DTYPE_SELECTIVE_BUILD=ON \
             -DEXECUTORCH_OPTIMIZE_SIZE=ON \
             -DCMAKE_INSTALL_PREFIX=cmake-out \
@@ -206,7 +183,6 @@ fi
 if [[ $1 == "cmake" ]];
 then
     cmake_install_executorch_lib $CMAKE_BUILD_TYPE
-    test_cmake_select_all_ops
     test_cmake_select_ops_in_list
     test_cmake_select_ops_in_yaml
     test_cmake_select_ops_in_model