Update canonical build from source docs to reflect actual usage. (#6696)
Both myself and our users have been falling down the hole of using an unsupported generator and fat fingering development options when we just want to be copy/pasting. I think how I have this laid out strike a balance.
Co-authored-by: Scott Todd <scotttodd@google.com>
diff --git a/docs/website/docs/building-from-source/android.md b/docs/website/docs/building-from-source/android.md
index 967e95f..2a113d8 100644
--- a/docs/website/docs/building-from-source/android.md
+++ b/docs/website/docs/building-from-source/android.md
@@ -42,7 +42,7 @@
Build and install on your host machine:
``` shell
-cmake -B ../iree-build/ \
+cmake -GNinja -B ../iree-build/ \
-DCMAKE_INSTALL_PREFIX=../iree-build/install \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
.
@@ -56,7 +56,7 @@
=== "Linux and MacOS"
``` shell
- cmake -B ../iree-build-android/ \
+ cmake -GNinja -B ../iree-build-android/ \
-DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK?}/build/cmake/android.toolchain.cmake" \
-DIREE_HOST_BINARY_ROOT="$PWD/../iree-build/install" \
-DANDROID_ABI="arm64-v8a" \
@@ -69,7 +69,7 @@
=== "Windows"
``` shell
- cmake -B ../iree-build-android/ \
+ cmake -GNinja -B ../iree-build-android/ \
-DCMAKE_TOOLCHAIN_FILE="%ANDROID_NDK%/build/cmake/android.toolchain.cmake" \
-DIREE_HOST_BINARY_ROOT="%CD%/../iree-build/install" \
-DANDROID_ABI="arm64-v8a" \
diff --git a/docs/website/docs/building-from-source/getting-started.md b/docs/website/docs/building-from-source/getting-started.md
index dfc010f..574d073 100644
--- a/docs/website/docs/building-from-source/getting-started.md
+++ b/docs/website/docs/building-from-source/getting-started.md
@@ -9,21 +9,29 @@
=== "Linux and MacOS"
- <!-- TODO(scotttodd): annotation about gcc vs clang -->
+ 1. Install a compiler/linker (typically "clang" and "lld" package).
- ``` shell
- sudo apt install cmake clang
- export CC=clang
- export CXX=clang++
- ```
+ 2. Install [CMake](https://cmake.org/download/) (typically "cmake" package).
+
+ 3. Install [Ninja](https://ninja-build.org/) (typically "ninja-build"
+ package).
+
+On a relatively recent Debian/Ubuntu:
+
+``` shell
+sudo apt install cmake ninja-build clang lld
+```
=== "Windows"
- 1. Install CMake from the
+ 1. Install MSVC from Visual Studio or "Tools for Visual Studio" on the
+ [official downloads page](https://visualstudio.microsoft.com/downloads/)
+
+ 2. Install CMake from the
[official downloads page](https://cmake.org/download/)
- 2. Install MSVC from Visual Studio or "Tools for Visual Studio" on the
- [official downloads page](https://visualstudio.microsoft.com/downloads/)
+ 3. Install Ninja either from the
+ [official site](https://ninja-build.org/).
!!! note
You will need to initialize MSVC by running `vcvarsall.bat` to use it
@@ -44,8 +52,38 @@
Configure then build all targets using CMake:
+Configure CMake:
+
+=== "Linux and MacOS"
+
+ ``` shell
+ # Recommended for simple development using clang and lld:
+ cmake -GNinja -B ../iree-build/ -S . \
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ -DIREE_ENABLE_ASSERTIONS=ON \
+ -DCMAKE_C_COMPILER=clang \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -DIREE_ENABLE_LLD=ON
+
+ # Alternately, with system compiler and your choice of CMake generator:
+ # cmake -B ../iree-build/ -S .
+
+ # Additional quality of life CMake flags:
+ # Enable ccache:
+ # -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+ ```
+
+=== "Windows"
+
+ ``` shell
+ cmake -GNinja -B ../iree-build/ -S . \
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ -DIREE_ENABLE_ASSERTIONS=ON
+ ```
+
+Build:
+
``` shell
-cmake -B ../iree-build/ -DCMAKE_BUILD_TYPE=RelWithDebInfo .
cmake --build ../iree-build/
```
@@ -59,12 +97,8 @@
for general details.
???+ Tip
- Most IREE Core devs use [Ninja](https://ninja-build.org/) as the CMake
- generator. The benefit is that it works the same across all platforms and
- automatically takes advantage of parallelism. to use it, add a `-GNinja`
- argument to your initial cmake command (and make sure to install
- `ninja-build` from either your favorite OS package manager, or generically
- via `python -m pip install ninja`).
+ You are welcome to try different CMake generators, but IREE devs and CIs
+ exclusively use [Ninja](https://ninja-build.org/).
## What's next?
diff --git a/docs/website/docs/building-from-source/optional-features.md b/docs/website/docs/building-from-source/optional-features.md
index 95aac4a..d124060 100644
--- a/docs/website/docs/building-from-source/optional-features.md
+++ b/docs/website/docs/building-from-source/optional-features.md
@@ -87,6 +87,7 @@
``` shell
cmake \
+ -GNinja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DIREE_BUILD_PYTHON_BINDINGS=ON \
-DPython3_EXECUTABLE="$(which python)" \
@@ -102,7 +103,7 @@
=== "Windows"
``` powershell
- cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DIREE_BUILD_PYTHON_BINDINGS=ON .
+ cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DIREE_BUILD_PYTHON_BINDINGS=ON .
cmake --build .
# Add bindings\python to PYTHONPATH and use the API.
diff --git a/docs/website/docs/building-from-source/riscv.md b/docs/website/docs/building-from-source/riscv.md
index 9ad552e..3d172f6 100644
--- a/docs/website/docs/building-from-source/riscv.md
+++ b/docs/website/docs/building-from-source/riscv.md
@@ -55,7 +55,7 @@
Build and install on your host machine:
``` shell
-cmake -B ../iree-build/ \
+cmake -GNinja -B ../iree-build/ \
-DCMAKE_INSTALL_PREFIX=../iree-build/install \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
.
@@ -72,7 +72,7 @@
#### RISC-V 64-bit Linux target
```shell
-cmake -B ../iree-build-riscv/ \
+cmake -GNinja -B ../iree-build-riscv/ \
-DCMAKE_TOOLCHAIN_FILE="./build_tools/cmake/riscv.toolchain.cmake" \
-DIREE_HOST_BINARY_ROOT=$(realpath ../iree-build-host/install) \
-DRISCV_CPU=rv64 \
