[docs] Update and harmonize guids for deployment (iree-org#18762)

This updates and harmonizes the guides for the different deployment configurations. Several identical sections are provided as snippets. * Updates docs regarding ROCm support * Adds a subsection on downloading the runtime from a release * Adds instructions on checking for CUDA and ROCm support This superseds iree-org#18173 and iree-org#18655.
haftkhanbot · Oct 16, 2024 · c6056d1 · c6056d1
1 parent f9fa934
commit c6056d1
Show file tree

Hide file tree

Showing 8 changed files with 133 additions and 102 deletions.
diff --git a/docs/website/docs/guides/deployment-configurations/cpu.md b/docs/website/docs/guides/deployment-configurations/cpu.md
@@ -46,35 +46,7 @@ Python packages are regularly published to
 [Python Bindings](../../reference/bindings/python.md) page for more details.
 The core `iree-compiler` package includes the LLVM-based CPU compiler:
 
-=== "Stable releases"
-
-    Stable release packages are
-    [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
-
-    ``` shell
-    python -m pip install iree-compiler
-    ```
-
-=== ":material-alert: Nightly releases"
-
-    Nightly releases are published on
-    [GitHub releases](https://github.com/iree-org/iree/releases).
-
-    ``` shell
-    python -m pip install \
-      --find-links https://iree.dev/pip-release-links.html \
-      --upgrade iree-compiler
-    ```
-
-!!! tip
-    `iree-compile` is installed to your python module installation path. If you
-    pip install with the user mode, it is under `${HOME}/.local/bin`, or
-    `%APPDATA%Python` on Windows. You may want to include the path in your
-    system's `PATH` environment variable:
-
-    ```shell
-    export PATH=${HOME}/.local/bin:${PATH}
-    ```
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
 
 #### :material-hammer-wrench: Build the compiler from source
 
@@ -101,15 +73,19 @@ along with the appropriate executable loaders for your application.
 You can check for CPU support by looking for the `local-sync` and `local-task`
 drivers:
 
-```console hl_lines="4 5"
-$ iree-run-module --list_drivers
-
-        cuda: CUDA (dynamic)
-  local-sync: Local execution using a lightweight inline synchronous queue
-  local-task: Local execution using the IREE multithreading task system
-      vulkan: Vulkan 1.x (dynamic)
+```console hl_lines="5 6"
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md"
 ```
 
+#### :octicons-package-16: Download the runtime from a release
+
+Python packages are regularly published to
+[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+[Python Bindings](../../reference/bindings/python.md) page for more details.
+The core `iree-runtime` package includes the local CPU HAL drivers:
+
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
+
 #### :material-hammer-wrench: Build the runtime from source
 
 Please make sure you have followed the

diff --git a/docs/website/docs/guides/deployment-configurations/gpu-cuda.md b/docs/website/docs/guides/deployment-configurations/gpu-cuda.md
@@ -33,35 +33,7 @@ Python packages are regularly published to
 [Python Bindings](../../reference/bindings/python.md) page for more details.
 The core `iree-compiler` package includes the CUDA compiler:
 
-=== "Stable releases"
-
-    Stable release packages are
-    [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
-
-    ``` shell
-    python -m pip install iree-compiler
-    ```
-
-=== ":material-alert: Nightly releases"
-
-    Nightly releases are published on
-    [GitHub releases](https://github.com/iree-org/iree/releases).
-
-    ``` shell
-    python -m pip install \
-      --find-links https://iree.dev/pip-release-links.html \
-      --upgrade iree-compiler
-    ```
-
-!!! tip
-    `iree-compile` is installed to your python module installation path. If you
-    pip install with the user mode, it is under `${HOME}/.local/bin`, or
-    `%APPDATA%Python` on Windows. You may want to include the path in your
-    system's `PATH` environment variable:
-
-    ```shell
-    export PATH=${HOME}/.local/bin:${PATH}
-    ```
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
 
 #### :material-hammer-wrench: Build the compiler from source
 
@@ -78,6 +50,29 @@ the IREE compiler, then enable the CUDA compiler target with the
 
 Next you will need to get an IREE runtime that includes the CUDA HAL driver.
 
+You can check for CUDA support by looking for a matching driver and device:
+
+```console hl_lines="3"
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md"
+```
+
+```console hl_lines="3"
+$ iree-run-module --list_devices
+
+  cuda://GPU-00000000-1111-2222-3333-444444444444
+  local-sync://
+  local-task://
+```
+
+#### :octicons-package-16: Download the runtime from a release
+
+Python packages are regularly published to
+[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+[Python Bindings](../../reference/bindings/python.md) page for more details.
+The core `iree-runtime` package includes the CUDA HAL driver:
+
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
+
 #### :material-hammer-wrench: Build the runtime from source
 
 Please make sure you have followed the

diff --git a/docs/website/docs/guides/deployment-configurations/gpu-rocm.md b/docs/website/docs/guides/deployment-configurations/gpu-rocm.md
@@ -30,7 +30,12 @@ or [Linux](https://rocm.docs.amd.com/en/latest/deploy/linux/quick_start.html).
 
 #### :octicons-package-16: Download the compiler from a release
 
-!!! note "Currently ROCm is **NOT supported** for the Python interface."
+Python packages are regularly published to
+[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+[Python Bindings](../../reference/bindings/python.md) page for more details.
+The core `iree-compiler` package includes the ROCm compiler:
+
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
 
 #### :material-hammer-wrench: Build the compiler from source
 
@@ -47,6 +52,29 @@ the IREE compiler, then enable the ROCm compiler target with the
 
 Next you will need to get an IREE runtime that includes the HIP HAL driver.
 
+You can check for HIP support by looking for a matching driver and device:
+
+```console hl_lines="4"
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md"
+```
+
+```console hl_lines="3"
+$ iree-run-module --list_devices
+
+  hip://GPU-00000000-1111-2222-3333-444444444444
+  local-sync://
+  local-task://
+```
+
+#### :octicons-package-16: Download the runtime from a release
+
+Python packages are regularly published to
+[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+[Python Bindings](../../reference/bindings/python.md) page for more details.
+The core `iree-runtime` package includes the HIP HAL driver:
+
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
+
 #### :material-hammer-wrench: Build the runtime from source
 
 Please make sure you have followed the

diff --git a/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md b/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md
@@ -83,35 +83,7 @@ Python packages are regularly published to
 [Python Bindings](../../reference/bindings/python.md) page for more details.
 The core `iree-compiler` package includes the SPIR-V compiler:
 
-=== "Stable releases"
-
-    Stable release packages are
-    [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
-
-    ``` shell
-    python -m pip install iree-compiler
-    ```
-
-=== ":material-alert: Nightly releases"
-
-    Nightly releases are published on
-    [GitHub releases](https://github.com/iree-org/iree/releases).
-
-    ``` shell
-    python -m pip install \
-      --find-links https://iree.dev/pip-release-links.html \
-      --upgrade iree-compiler
-    ```
-
-!!! tip
-    `iree-compile` is installed to your python module installation path. If you
-    pip install with the user mode, it is under `${HOME}/.local/bin`, or
-    `%APPDATA%Python` on Windows. You may want to include the path in your
-    system's `PATH` environment variable:
-
-    ```shell
-    export PATH=${HOME}/.local/bin:${PATH}
-    ```
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
 
 #### :material-hammer-wrench: Build the compiler from source
 
@@ -135,13 +107,8 @@ Next you will need to get an IREE runtime that supports the Vulkan HAL driver.
 
 You can check for Vulkan support by looking for a matching driver and device:
 
-```console hl_lines="6"
-$ iree-run-module --list_drivers
-
-        cuda: CUDA (dynamic)
-  local-sync: Local execution using a lightweight inline synchronous queue
-  local-task: Local execution using the IREE multithreading task system
-      vulkan: Vulkan 1.x (dynamic)
+```console hl_lines="7"
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md"
 ```
 
 ```console hl_lines="6"
@@ -153,6 +120,15 @@ $ iree-run-module --list_devices
   vulkan://00000000-1111-2222-3333-444444444444
 ```
 
+#### :octicons-package-16: Download the runtime from a release
+
+Python packages are regularly published to
+[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+[Python Bindings](../../reference/bindings/python.md) page for more details.
+The core `iree-runtime` package includes the Vulkan HAL drivers:
+
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
+
 #### :material-hammer-wrench: Build the runtime from source
 
 Please make sure you have followed the

diff --git a/...e/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md b/...e/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md
@@ -0,0 +1,29 @@
+=== "Stable releases"
+
+    Stable release packages are
+    [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+
+    ``` shell
+    python -m pip install iree-compiler iree-runtime
+    ```
+
+=== ":material-alert: Nightly releases"
+
+    Nightly releases are published on
+    [GitHub releases](https://github.com/iree-org/iree/releases).
+
+    ``` shell
+    python -m pip install \
+      --find-links https://iree.dev/pip-release-links.html \
+      --upgrade iree-compiler iree-runtime
+    ```
+
+!!! tip
+    `iree-compile` and other tools are installed to your python module
+    installation path. If you pip install with the user mode, it is under
+    `${HOME}/.local/bin`, or `%APPDATA%Python` on Windows. You may want to
+    include the path in your system's `PATH` environment variable:
+
+    ```shell
+    export PATH=${HOME}/.local/bin:${PATH}
+    ```
diff --git a/.../docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md b/.../docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md
@@ -0,0 +1,7 @@
+$ iree-run-module --list_drivers
+
+        cuda: NVIDIA CUDA HAL driver (via dylib)
+         hip: HIP HAL driver (via dylib)
+  local-sync: Local execution using a lightweight inline synchronous queue
+  local-task: Local execution using the IREE multithreading task system
+      vulkan: Vulkan 1.x (dynamic)
diff --git a/...te/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md b/...te/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md
@@ -0,0 +1,19 @@
+=== "Stable releases"
+
+    Stable release packages are
+    [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+
+    ``` shell
+    python -m pip install iree-runtime
+    ```
+
+=== ":material-alert: Nightly releases"
+
+    Nightly releases are published on
+    [GitHub releases](https://github.com/iree-org/iree/releases).
+
+    ``` shell
+    python -m pip install \
+      --find-links https://iree.dev/pip-release-links.html \
+      --upgrade iree-runtime
+    ```
diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml
@@ -80,6 +80,7 @@ extra_css:
 exclude_docs: |
   *.gz
   assets/images/README.md
+  **/snippets/*.md
 
 copyright: Copyright &copy; 2024 The IREE Authors