Improve docs on CMake variables and options * Improve description of IREE-specific CMake Options and Variables * Add section on Frequently-used CMake Variables * Add links from building with CMake docs * Revise style (use sections instead of bullet points) Closes https://github.com/google/iree/pull/2260 COPYBARA_INTEGRATE_REVIEW=https://github.com/google/iree/pull/2260 from iml130:docs 4f191f0627d1f827f7f0887ad38b086e183a3504 PiperOrigin-RevId: 317737818
diff --git a/docs/GetStarted/cmake_options_and_variables.md b/docs/GetStarted/cmake_options_and_variables.md index 899fa19..2676efe 100644 --- a/docs/GetStarted/cmake_options_and_variables.md +++ b/docs/GetStarted/cmake_options_and_variables.md
@@ -1,74 +1,96 @@ -# IREE-specific CMake Options and Variables +# CMake Options and Variables + +## Frequently-used CMake Variables + +#### `CMAKE_BUILD_TYPE`:STRING + +Sets the build type. Possible values are `Release`, `Debug`, +`RelWithDebInfo`/`FastBuild` and `MinSizeRel`. If unset, build type is set to +`Release`. + +#### `CMAKE_<LANG>_COMPILER`:STRING + +This is the command that will be used as the `<LANG>` compiler, which are `C` +and `CXX` in IREE. These variables are set to compile IREE with `clang` or +rather `clang++`. Once set, these variables can not be changed. + +## IREE-specific CMake Options and Variables This gives a brief explanation of IREE specific CMake options and variables. -* `IREE_ENABLE_RUNTIME_TRACING`:BOOL +#### `IREE_ENABLE_RUNTIME_TRACING`:BOOL - Enables instrumented runtime tracing. Defaults to `OFF`. +Enables instrumented runtime tracing. Defaults to `OFF`. -* `IREE_ENABLE_MLIR`:BOOL +#### `IREE_ENABLE_MLIR`:BOOL - Enables MLIR/LLVM dependencies. Defaults to `ON`. +Enables MLIR/LLVM dependencies. Defaults to `ON`. MLIR/LLVM dependencies are +required when building the IREE compiler components. Therefore, the option is +automatically set to `ON` if `IREE_BUILD_COMPILER` is set to `ON`. -* `IREE_ENABLE_EMITC`:BOOL +#### `IREE_ENABLE_EMITC`:BOOL - Enables MLIR EmitC dependencies. Defaults to OFF. Requires that - `IREE_ENABLE_MLIR` is set to `ON`. +Enables the build of the out-of-tree MLIR dialect EmitC. Defaults to `OFF`. To +build the EmitC dialect, `IREE_ENABLE_MLIR` must be set to `ON`. -* `IREE_BUILD_COMPILER`:BOOL +#### `IREE_BUILD_COMPILER`:BOOL - Builds the IREE compiler. Defaults to `ON`. +Builds the IREE compiler. Defaults to `ON`. -* `IREE_BUILD_TESTS`:BOOL +#### `IREE_BUILD_TESTS`:BOOL - Builds IREE unit tests. Defaults to `ON`. +Builds IREE unit tests. Defaults to `ON`. -* `IREE_BUILD_DOCS`:BOOL +#### `IREE_BUILD_DOCS`:BOOL - Builds IREE documentation. Defaults to `OFF`. +Builds IREE documentation. Defaults to `OFF`. -* `IREE_BUILD_SAMPLES`:BOOL +#### `IREE_BUILD_SAMPLES`:BOOL - Builds IREE sample projects. Defaults to `ON`. +Builds IREE sample projects. Defaults to `ON`. -* `IREE_BUILD_DEBUGGER`:BOOL +#### `IREE_BUILD_DEBUGGER`:BOOL - Builds the IREE debugger app. Defaults to `OFF`. +Builds the IREE debugger app. Defaults to `OFF`. -* `IREE_BUILD_PYTHON_BINDINGS`:BOOL +#### `IREE_BUILD_PYTHON_BINDINGS`:BOOL - Builds the IREE python bindings Defaults to `OFF`. +Builds the IREE python bindings. Defaults to `OFF`. -* `IREE_BUILD_EXPERIMENTAL`:BOOL +#### `IREE_BUILD_EXPERIMENTAL`:BOOL - Builds experimental projects. Defaults to `OFF`. +Builds experimental projects. Defaults to `OFF`. -* `IREE_HAL_DRIVERS_TO_BUILD`:STRING +#### `IREE_HAL_DRIVERS_TO_BUILD`:STRING - *This does not have any effect at the moment, but will be supported in the - future!* Semicolon-separated list of HAL drivers to build, or `all` for - building all HAL drivers. Case-insensitive. Defaults to `all`. Example: - `-DIREE_HAL_DRIVERS_TO_BUILD="Vulkan;VMLA"`. +*This does not have any effect at the moment, but will be supported in the +future!* Semicolon-separated list of HAL drivers to build, or `all` for building +all HAL drivers. Case-insensitive. Defaults to `all`. Example: +`-DIREE_HAL_DRIVERS_TO_BUILD="Vulkan;VMLA"`. -* `IREE_TARGET_BACKENDS_TO_BUILD`:STRING +#### `IREE_TARGET_BACKENDS_TO_BUILD`:STRING - *This does not have any effect at the moment, but will be supported in the - future!* Semicolon-separated list of HAL drivers to build, or `all` for - building all HAL drivers. Case-insensitive. Defaults to `all`. Example: - `-DIREE_HAL_DRIVERS_TO_BUILD="Vulkan_SPIRV;VMLA"`. +*This does not have any effect at the moment, but will be supported in the +future!* Semicolon-separated list of HAL drivers to build, or `all` for building +all HAL drivers. Case-insensitive. Defaults to `all`. Example: +`-DIREE_HAL_DRIVERS_TO_BUILD="Vulkan_SPIRV;VMLA"`. -* `IREE_ENABLE_LLD`:BOOL +#### `IREE_ENABLE_LLD`:BOOL - Use lld when linking. Defaults to `OFF`. +Use lld when linking. Defaults to `OFF`. This option is equivalent to +`-DIREE_USE_LINKER=lld`. The option `IREE_ENABLE_LLD` and `IREE_USE_LINKER` can +not be set at the same time. -* `IREE_MLIR_DEP_MODE`:STRING +#### `IREE_MLIR_DEP_MODE`:STRING - Defines the MLIR dependency mode. Case-sensitive. Can be `BUNDLED`, - `DISABLED` or `INSTALLED`. Defaults to `BUNDLED`. If set to `INSTALLED`, the - variable `MLIR_DIR` needs to be passed and that LLVM needs to be compiled - with `LLVM_ENABLE_RTTI` set to `ON`. +Defines the MLIR dependency mode. Case-sensitive. Can be `BUNDLED`, `DISABLED` +or `INSTALLED`. Defaults to `BUNDLED`. If set to `INSTALLED`, the variable +`MLIR_DIR` needs to be passed and that LLVM needs to be compiled with +`LLVM_ENABLE_RTTI` set to `ON`. -* `MLIR_DIR`:STRING +## MLIR-specific CMake Options and Variables - Specifies the path where to look for the installed MLIR/LLVM packages. - Required if `IREE_MLIR_DEP_MODE` is set to `INSTALLED`. +#### `MLIR_DIR`:STRING + +Specifies the path where to look for the installed MLIR/LLVM packages. Required +if `IREE_MLIR_DEP_MODE` is set to `INSTALLED`.
diff --git a/docs/GetStarted/getting_started_linux_cmake.md b/docs/GetStarted/getting_started_linux_cmake.md index 190ce9a..ed7856e 100644 --- a/docs/GetStarted/getting_started_linux_cmake.md +++ b/docs/GetStarted/getting_started_linux_cmake.md
@@ -78,7 +78,8 @@ > Tip:<br> > The root > [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt) -> file has options for configuring which parts of the project to enable. +> file has options for configuring which parts of the project to enable.<br> +> These are further documented in [CMake Options and Variables](cmake_options_and_variables.md). Build all targets:
diff --git a/docs/GetStarted/getting_started_macos_cmake.md b/docs/GetStarted/getting_started_macos_cmake.md index 1fc6777..59d22e8 100644 --- a/docs/GetStarted/getting_started_macos_cmake.md +++ b/docs/GetStarted/getting_started_macos_cmake.md
@@ -78,7 +78,8 @@ > Tip:<br> > The root > [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt) -> file has options for configuring which parts of the project to enable. +> file has options for configuring which parts of the project to enable.<br> +> These are further documented in [CMake Options and Variables](cmake_options_and_variables.md). Build all targets:
diff --git a/docs/GetStarted/getting_started_windows_cmake.md b/docs/GetStarted/getting_started_windows_cmake.md index 445d790..77d4fe4 100644 --- a/docs/GetStarted/getting_started_windows_cmake.md +++ b/docs/GetStarted/getting_started_windows_cmake.md
@@ -76,7 +76,8 @@ > Tip:<br> > The root > [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt) -> file has options for configuring which parts of the project to enable. +> file has options for configuring which parts of the project to enable.<br> +> These are further documented in [CMake Options and Variables](cmake_options_and_variables.md). Build all targets: