|
| 1 | +# ExecuTorch Build Presets |
| 2 | + |
| 3 | +Build presets are a collection of cmake arguments that configure flavors of ExecuTorch libraries. Build presets are intended to help answer questions like: |
| 4 | + |
| 5 | +- "How do I build the ET library used in the pip wheel?" → use [pybind.cmake](./pybind.cmake) |
| 6 | +- "How do I build the iOS library?" → use [ios.cmake](./ios.cmake) |
| 7 | +- "How do I build what's required to run an LLM?" → use [llm.cmake](./llm.cmake) |
| 8 | + |
| 9 | +## Why? |
| 10 | + |
| 11 | +See: https://github.com/pytorch/executorch/discussions/10661. tl;dr instead of turning on multiple opaque/unknown flags, you can reduce it to: |
| 12 | + |
| 13 | +```bash |
| 14 | +$ cmake --preset macos |
| 15 | +$ cmake --build cmake-out -j100 --target executor_runner |
| 16 | +``` |
| 17 | + |
| 18 | +## Working with Presets |
| 19 | + |
| 20 | +> [!TIP] |
| 21 | +> Configurable presets options and their default values are stored in [default.cmake](./default.cmake). |
| 22 | +
|
| 23 | +### Within ExecuTorch |
| 24 | + |
| 25 | +If you're developing ExecuTorch directly, you can use the `cmake --preset` command: |
| 26 | + |
| 27 | +```bash |
| 28 | +# List all the presets buildable on your machine |
| 29 | +$ cmake --list-presets |
| 30 | + |
| 31 | +# Build a preset |
| 32 | +$ cmake --preset llm |
| 33 | + |
| 34 | +# Build a preset with one-off configuration change |
| 35 | +$ cmake -DEXECUTORCH_BUILD_MPS=OFF --preset llm |
| 36 | +``` |
| 37 | + |
| 38 | +The cmake presets roughly map to the ExecuTorch presets and are explicitly listed in [CMakePresets.json](../../../CMakePresets.json). Note that you are encouraged to rely on presets when build locally and adding build/tests in CI — CI should do what a developer would do and nothing more! |
| 39 | + |
| 40 | +### Including ExecuTorch as Third-party Library |
| 41 | + |
| 42 | +#### Choose a built-in preset |
| 43 | + |
| 44 | +You can include ExecuTorch like any other cmake project in your project: |
| 45 | +```cmake |
| 46 | +add_subdirectory(executorch) |
| 47 | +``` |
| 48 | +However, note that since a preset isn't specified, it will use the [default](./default.cmake) options. This likely not what you want — you likely want to use a preset. Check for presets available in [tools/cmake/preset](.) and explicitly choose which preset to use: |
| 49 | + |
| 50 | +```cmake |
| 51 | +set(EXECUTORCH_BUILD_PRESET_FILE executorch/tools/cmake/preset/llm.cmake) |
| 52 | +add_subdirectory(executorch) |
| 53 | +``` |
| 54 | + |
| 55 | +Even when using a preset, you can explicitly override specific preset configurations: |
| 56 | + |
| 57 | +```cmake |
| 58 | +set(EXECUTORCH_BUILD_PRESET_FILE executorch/tools/cmake/preset/llm.cmake) |
| 59 | +
|
| 60 | +# Although llm.cmake might have turned on `EXECUTORCH_BUILD_MPS`, you can turn if off |
| 61 | +set(EXECUTORCH_BUILD_MPS OFF) |
| 62 | +
|
| 63 | +add_subdirectory(executorch) |
| 64 | +``` |
| 65 | + |
| 66 | +#### Creating your own preset |
| 67 | + |
| 68 | +Preset files are just cmake files that turn on/off ExecuTorch configs. For example if we want to build the runner with a CoreML backend, create your cmake preset file (i.e. `my_projects_custom_preset.cmake`): |
| 69 | + |
| 70 | +```cmake |
| 71 | +# File: my_projects_custom_preset.cmake |
| 72 | +
|
| 73 | +set_overridable_option(EXECUTORCH_BUILD_COREML ON) |
| 74 | +set_overridable_option(EXECUTORCH_BUILD_EXECUTOR_RUNNER ON) |
| 75 | +``` |
| 76 | + |
| 77 | +We use `set_overridable_option` so that it allows the option to be overriden via the command line using `-D`. Feel free to use the standard `set(...)` function to prevent overriding options. |
| 78 | + |
| 79 | +Once the preset is created, set `EXECUTORCH_BUILD_PRESET_FILE` before adding ExecuTorch: |
| 80 | + |
| 81 | +```cmake |
| 82 | +set(EXECUTORCH_BUILD_PRESET_FILE my_projects_custom_preset.cmake) |
| 83 | +add_subdirectory(executorch) |
| 84 | +``` |
0 commit comments