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`.
