Skip to content

Commit 16f8d8c

Browse files
authored
Create a README for build presets (#11548)
### Summary TSIA ### Test plan N/A cc @larryliu0820
1 parent 72a095f commit 16f8d8c

File tree

1 file changed

+84
-0
lines changed

1 file changed

+84
-0
lines changed

tools/cmake/preset/README.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
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

Comments
 (0)