1# Building with CMake 2 3ExecuTorch uses [CMake](https://cmake.org/) as its primary build system. 4Even if you don't use CMake directly, CMake can emit scripts for other format 5like Make, Ninja or Xcode. For information, see [cmake-generators(7)](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html). 6 7## Targets Built by the CMake Build System 8 9ExecuTorch's CMake build system covers the pieces of the runtime that are 10likely to be useful to embedded systems users. 11 12- `libexecutorch_core.a`: The core of the ExecuTorch runtime. Does not contain any 13 operator/kernel definitions or backend definitions. 14- `libportable_kernels.a`: The implementations of ATen-compatible operators, 15 following the signatures in `[functions.yaml](https://github.com/pytorch/executorch/blob/release/0.4/kernels/portable/functions.yaml)`. 16- `libportable_ops_lib.a`: Generated code that registers the contents 17 of `libportable_kernels.a` with the runtime. 18 - NOTE: This must be linked into your application with a flag like 19 `-Wl,-force_load` or `-Wl,--whole-archive`. It contains load-time functions 20 that automatically register the kernels, but linkers will often prune those 21 functions by default because there are no direct calls to them. 22- `executor_runner`: An example tool that runs a `.pte` program file using all 23 `1` values as inputs, and prints the outputs to stdout. It is linked with 24 `libportable_kernels.a`, so the program may use any of the operators it 25 implements. 26 27## One-time setup to prepare for CMake Build 28 29Follow the steps below to have the tools ready before using CMake to build on your machine. 30 311. If your system's version of python3 is older than 3.11: 32 - Run `pip install tomli` 333. Install CMake version 3.19 or later: 34 - Run `conda install cmake` or `pip install cmake`. 35 36 37## Configure the CMake Build 38 39Follow these steps after cloning or pulling the upstream repo, since the build 40dependencies may have changed. 41 42```bash 43# cd to the root of the executorch repo 44cd executorch 45 46# Clean cmake cache directory (cmake-out). It's a good practice to do this 47# whenever cloning or pulling the upstream repo. 48bash install_requirements.sh --clean 49``` 50 51Once this is done, you don't need to do it again until you pull from the upstream repo again, or if you modify any CMake-related files. 52 53### CMake Build Options 54 55The release build offers optimizations intended to improve performance and reduce binary size. It disables program verification and executorch logging, and adds optimizations flags. 56```bash 57CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release" 58``` 59 60To further optimize the release build for size, add: 61```bash 62CMAKE_FLAGS="$CMAKE_FLAGS -DOPTIMIZE_SIZE=ON" 63``` 64 65See [CMakeLists.txt](https://github.com/pytorch/executorch/blob/release/0.4/CMakeLists.txt) 66 67## Build the runtime components 68 69Build all targets with 70 71```bash 72# Build using the configuration that you previously generated under the 73# `cmake-out` directory. 74cmake "$CMAKE_FLAGS" -Bcmake-out . 75 76# NOTE: The `-j` argument specifies how many jobs/processes to use when 77# building, and tends to speed up the build significantly. It's typical to use 78# "core count + 1" as the `-j` value. 79cmake --build cmake-out -j9 80``` 81 82## Use an example app `executor_runner` to execute a .pte file 83 84First, generate an `add.pte` or other ExecuTorch program file using the 85instructions as described in 86[Setting up ExecuTorch](getting-started-setup.md#building-a-runtime). 87 88Then, pass it to the command line tool: 89 90```bash 91./cmake-out/executor_runner --model_path path/to/add.pte 92``` 93 94If it worked, you should see the message "Model executed successfully" followed 95by the output values. 96 97``` 98I 00:00:00.000526 executorch:executor_runner.cpp:82] Model file add.pte is loaded. 99I 00:00:00.000595 executorch:executor_runner.cpp:91] Using method forward 100I 00:00:00.000612 executorch:executor_runner.cpp:138] Setting up planned buffer 0, size 48. 101I 00:00:00.000669 executorch:executor_runner.cpp:161] Method loaded. 102I 00:00:00.000685 executorch:executor_runner.cpp:171] Inputs prepared. 103I 00:00:00.000764 executorch:executor_runner.cpp:180] Model executed successfully. 104I 00:00:00.000770 executorch:executor_runner.cpp:184] 1 outputs: 105Output 0: tensor(sizes=[1], [2.]) 106``` 107 108 109## Cross compilation 110 111Following are instruction on how to perform cross compilation for Android and iOS. 112 113### Android 114- Prerequisite: [Android NDK](https://developer.android.com/ndk), choose one of the following: 115 - Option 1: Download Android Studio by following the instructions to [install ndk](https://developer.android.com/studio/projects/install-ndk). 116 - Option 2: Download Android NDK directly from [here](https://developer.android.com/ndk/downloads). 117 118Assuming Android NDK is available, run: 119```bash 120# Run the following lines from the `executorch/` folder 121rm -rf cmake-android-out && mkdir cmake-android-out && cd cmake-android-out 122 123# point -DCMAKE_TOOLCHAIN_FILE to the location where ndk is installed 124cmake -DCMAKE_TOOLCHAIN_FILE=/Users/{user_name}/Library/Android/sdk/ndk/25.2.9519653/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a .. 125 126cd .. 127cmake --build cmake-android-out -j9 128 129adb shell mkdir -p /data/local/tmp/executorch 130# push the binary to an Android device 131adb push cmake-android-out/executor_runner /data/local/tmp/executorch 132# push the model file 133adb push add.pte /data/local/tmp/executorch 134 135adb shell "/data/local/tmp/executorch/executor_runner --model_path /data/local/tmp/executorch/add.pte" 136``` 137 138### iOS 139 140For iOS we'll build [frameworks](https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle) instead of static libraries, that will also contain the public headers inside. 141 1421. Install Xcode from the 143[Mac App Store](https://apps.apple.com/app/xcode/id497799835) and then install 144the Command Line Tools using the terminal: 145 146```bash 147xcode-select --install 148``` 149 1502. Build the frameworks: 151 152```bash 153./build/build_apple_frameworks.sh 154``` 155 156Run the above command with `--help` flag to learn more on how to build additional backends 157(like [Core ML](build-run-coreml.md), [MPS](build-run-mps.md) or XNNPACK), etc. 158Note, some backends may require additional dependencies and certain versions of Xcode and iOS. 159 1603. Copy over the generated `.xcframework` bundles to your Xcode project, link them against 161your targets and don't forget to add an extra linker flag `-all_load`. 162 163Check out the [iOS Demo App](demo-apps-ios.md) tutorial for more info. 164 165 166## Next steps 167 168You have successfully cross-compiled `executor_runner` binary to iOS and Android platforms. You can start exploring advanced features and capabilities. Here is a list of sections you might want to read next: 169 170* [Selective build](./kernel-library-selective_build) to build the runtime that links to only kernels used by the program, which can provide significant binary size savings. 171* Tutorials on building [Android](./demo-apps-android.md) and [iOS](./demo-apps-ios.md) demo apps. 172* Tutorials on deploying applications to embedded devices such as [ARM Cortex-M/Ethos-U](./executorch-arm-delegate-tutorial.md) and [XTensa HiFi DSP](./build-run-xtensa.md). 173