[docs] Refresh package install instructions across the website. (#19393)
Assorted documentation updates following some recent release
infrastructure work and improvements to the
[`setup_venv.py`](https://github.com/iree-org/iree/blob/main/build_tools/pkgci/setup_venv.py)
script:
* Mention "development packages" next to "stable releases" and "nightly
pre-releases", per
https://github.com/iree-org/iree/pull/19362#discussion_r1871947915
* Could keep that scoped to one page... but duplicating it across pages
helps with discoverability. Definitely open to hearing more opinions on
this.
* Converted package names into links to pypi where applicable, like
[`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
* Removed references to https://pypi.org/user/google-iree-pypi-deploy/.
That account is no longer a good reference for which projects are
relevant. We could use an [organization
account](https://docs.pypi.org/organization-accounts/) for a similar
purpose.
* Adjusted icons used in several places
Before | After
-- | --
|
* Misc proofreading and style tweaksdiff --git a/build_tools/pkgci/setup_venv.py b/build_tools/pkgci/setup_venv.py
index 8e709fa..7f18900 100755
--- a/build_tools/pkgci/setup_venv.py
+++ b/build_tools/pkgci/setup_venv.py
@@ -148,19 +148,19 @@
workflow_run_output = subprocess.check_output(workflow_run_args)
workflow_run_json_output = json.loads(workflow_run_output)
latest_run = workflow_run_json_output["workflow_runs"][0]
- print(f"Found workflow run: {latest_run['html_url']}")
+ print(f"\nFound workflow run: {latest_run['html_url']}")
return latest_run["id"]
def get_latest_workflow_run_id_for_ref(ref: str) -> int:
- print(f"Normalizing ref: {ref}")
+ print(f"Finding workflow run for ref: {ref}")
normalized_ref = (
subprocess.check_output(["git", "rev-parse", ref], cwd=REPO_ROOT)
.decode()
.strip()
)
- print(f"Using normalized ref: {normalized_ref}")
+ print(f" Using normalized ref: {normalized_ref}")
workflow_run_args = [
"gh",
"api",
@@ -170,14 +170,14 @@
"X-GitHub-Api-Version: 2022-11-28",
f"{BASE_API_PATH}/actions/workflows/pkgci.yml/runs?head_sha={normalized_ref}",
]
- print(f"Running command to list workflow runs:\n {' '.join(workflow_run_args)}")
+ print(f"\nRunning command to list workflow runs:\n {' '.join(workflow_run_args)}")
workflow_run_output = subprocess.check_output(workflow_run_args)
workflow_run_json_output = json.loads(workflow_run_output)
if workflow_run_json_output["total_count"] == 0:
raise RuntimeError("Workflow did not run at this commit")
latest_run = workflow_run_json_output["workflow_runs"][-1]
- print(f"Found workflow run: {latest_run['html_url']}")
+ print(f"\nFound workflow run: {latest_run['html_url']}")
return latest_run["id"]
@@ -203,7 +203,7 @@
rec["name"]: f"{BASE_API_PATH}/actions/artifacts/{rec['id']}/zip"
for rec in data["artifacts"]
}
- print("Found artifacts:")
+ print("\nFound artifacts:")
for k, v in artifacts.items():
print(f" {k}: {v}")
return artifacts
@@ -309,7 +309,7 @@
wheels.append(
find_wheel_for_variants(args, artifact_prefix, package_stem, variant)
)
- print("Installing wheels:", wheels)
+ print("\nInstalling wheels:", wheels)
# Set up venv.
venv_path = args.venv_dir
@@ -341,6 +341,9 @@
print(f"Running command: {' '.join([str(c) for c in cmd])}")
subprocess.check_call(cmd)
+ print(f"\nvenv setup complete at '{venv_path}'. Activate it with")
+ print(f" source {venv_path}/bin/activate")
+
return 0
diff --git a/docs/website/docs/building-from-source/getting-started.md b/docs/website/docs/building-from-source/getting-started.md
index 5e57cce..a773c97 100644
--- a/docs/website/docs/building-from-source/getting-started.md
+++ b/docs/website/docs/building-from-source/getting-started.md
@@ -431,7 +431,7 @@
python -c "import iree.runtime; help(iree.runtime)"
```
-Using IREE's ML framework importers requires a few extra steps:
+Using IREE's TensorFlow/TFLite importers requires a few extra steps:
``` shell
# Install test requirements
diff --git a/docs/website/docs/developers/design-docs/cuda-hal-driver.md b/docs/website/docs/developers/design-docs/cuda-hal-driver.md
index 2b89ebf..ec17254 100644
--- a/docs/website/docs/developers/design-docs/cuda-hal-driver.md
+++ b/docs/website/docs/developers/design-docs/cuda-hal-driver.md
@@ -52,7 +52,7 @@
#### Async allocation
-The CUDA HAL drivers supports async allocation
+The CUDA HAL driver supports async allocation
(`iree_hal_device_queue_alloca()` and `iree_hal_device_queue_dealloca()`)
via [CUDA stream ordered memory allocation][cuda-stream-ordered-alloc].
diff --git a/docs/website/docs/developers/design-docs/hip-hal-driver.md b/docs/website/docs/developers/design-docs/hip-hal-driver.md
index adcfa62..3564192 100644
--- a/docs/website/docs/developers/design-docs/hip-hal-driver.md
+++ b/docs/website/docs/developers/design-docs/hip-hal-driver.md
@@ -52,7 +52,7 @@
#### Async allocation
-The HIP HAL drivers supports async allocation
+The HIP HAL driver supports async allocation
(`iree_hal_device_queue_alloca()` and `iree_hal_device_queue_dealloca()`)
via HIP stream ordered memory allocation.
diff --git a/docs/website/docs/guides/deployment-configurations/cpu.md b/docs/website/docs/guides/deployment-configurations/cpu.md
index b3c8937..d9667f0 100644
--- a/docs/website/docs/guides/deployment-configurations/cpu.md
+++ b/docs/website/docs/guides/deployment-configurations/cpu.md
@@ -39,12 +39,12 @@
### Get the IREE compiler
-#### :octicons-package-16: Download the compiler from a release
+#### :octicons-download-16: Download the compiler from a release
-Python packages are regularly published to
-[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+Python packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-compiler` package includes the LLVM-based CPU compiler:
+The core [`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/)
+package includes the LLVM-based CPU compiler:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
@@ -77,12 +77,12 @@
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-run-module-driver-list.md"
```
-#### :octicons-package-16: Download the runtime from a release
+#### :octicons-download-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 packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-runtime` package includes the local CPU HAL drivers:
+The core [`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
+package includes the local CPU HAL drivers:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
diff --git a/docs/website/docs/guides/deployment-configurations/gpu-cuda.md b/docs/website/docs/guides/deployment-configurations/gpu-cuda.md
index 1ff00a3..4dc1298 100644
--- a/docs/website/docs/guides/deployment-configurations/gpu-cuda.md
+++ b/docs/website/docs/guides/deployment-configurations/gpu-cuda.md
@@ -26,12 +26,12 @@
### Get the IREE compiler
-#### :octicons-package-16: Download the compiler from a release
+#### :octicons-download-16: Download the compiler from a release
-Python packages are regularly published to
-[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+Python packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-compiler` package includes the CUDA compiler:
+The core [`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/)
+package includes the CUDA compiler:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
@@ -64,12 +64,12 @@
local-task://
```
-#### :octicons-package-16: Download the runtime from a release
+#### :octicons-download-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 packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-runtime` package includes the CUDA HAL driver:
+The core [`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
+package includes the CUDA HAL driver:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
diff --git a/docs/website/docs/guides/deployment-configurations/gpu-rocm.md b/docs/website/docs/guides/deployment-configurations/gpu-rocm.md
index 0773e3f..8d5d234 100644
--- a/docs/website/docs/guides/deployment-configurations/gpu-rocm.md
+++ b/docs/website/docs/guides/deployment-configurations/gpu-rocm.md
@@ -28,12 +28,12 @@
### Get the IREE compiler
-#### :octicons-package-16: Download the compiler from a release
+#### :octicons-download-16: Download the compiler from a release
-Python packages are regularly published to
-[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+Python packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-compiler` package includes the ROCm compiler:
+The core [`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/)
+package includes the ROCm compiler:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
@@ -66,12 +66,12 @@
local-task://
```
-#### :octicons-package-16: Download the runtime from a release
+#### :octicons-download-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 packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-runtime` package includes the HIP HAL driver:
+The core [`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
+package includes the HIP HAL driver:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
diff --git a/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md b/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md
index 83e4b30..48e8a1b 100644
--- a/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md
+++ b/docs/website/docs/guides/deployment-configurations/gpu-vulkan.md
@@ -76,12 +76,12 @@
[SPIR-V](https://www.khronos.org/registry/spir-v/) binary exchange format, which
the model must be compiled into.
-#### :octicons-package-16: Download the compiler from a release
+#### :octicons-download-16: Download the compiler from a release
-Python packages are regularly published to
-[PyPI](https://pypi.org/user/google-iree-pypi-deploy/). See the
+Python packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-compiler` package includes the SPIR-V compiler:
+The core [`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/)
+package includes the SPIR-V compiler:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md"
@@ -120,12 +120,12 @@
vulkan://00000000-1111-2222-3333-444444444444
```
-#### :octicons-package-16: Download the runtime from a release
+#### :octicons-download-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 packages are distributed through multiple channels. See the
[Python Bindings](../../reference/bindings/python.md) page for more details.
-The core `iree-base-runtime` package includes the Vulkan HAL drivers:
+The core [`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
+package includes the Vulkan HAL driver:
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md"
diff --git a/docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md b/docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md
index 18c055e..8830815 100644
--- a/docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md
+++ b/docs/website/docs/guides/deployment-configurations/snippets/_iree-compiler-from-release.md
@@ -1,13 +1,12 @@
-=== "Stable releases"
+=== ":octicons-package-16: Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install iree-base-compiler
```
-=== ":material-alert: Nightly releases"
+=== ":octicons-beaker-16: Nightly releases"
Nightly pre-releases are published on
[GitHub releases](https://github.com/iree-org/iree/releases).
@@ -18,6 +17,8 @@
--upgrade --pre iree-base-compiler
```
+--8<-- "docs/website/docs/snippets/_iree-dev-packages.md"
+
!!! 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
diff --git a/docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md b/docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md
index c72aff7..eaf5e8a 100644
--- a/docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md
+++ b/docs/website/docs/guides/deployment-configurations/snippets/_iree-runtime-from-release.md
@@ -1,13 +1,12 @@
-=== "Stable releases"
+=== ":octicons-package-16: Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install iree-base-runtime
```
-=== ":material-alert: Nightly releases"
+=== ":octicons-beaker-16: Nightly releases"
Nightly pre-releases are published on
[GitHub releases](https://github.com/iree-org/iree/releases).
@@ -17,3 +16,5 @@
--find-links https://iree.dev/pip-release-links.html \
--upgrade --pre iree-base-runtime
```
+
+--8<-- "docs/website/docs/snippets/_iree-dev-packages.md"
diff --git a/docs/website/docs/guides/index.md b/docs/website/docs/guides/index.md
index 645bffb..6aede4b 100644
--- a/docs/website/docs/guides/index.md
+++ b/docs/website/docs/guides/index.md
@@ -8,10 +8,11 @@
Guides for specific frameworks:
+* [:simple-python: JAX](./ml-frameworks/jax.md)
+* [:simple-onnx: ONNX](./ml-frameworks/onnx.md)
+* [:simple-pytorch: PyTorch](./ml-frameworks/pytorch.md)
* [:simple-tensorflow: TensorFlow](./ml-frameworks/tensorflow.md) and
[:simple-tensorflow: TensorFlow Lite](./ml-frameworks/tflite.md)
-* [:simple-python: JAX](./ml-frameworks/jax.md)
-* [:simple-pytorch: PyTorch](./ml-frameworks/pytorch.md)
## Deployment configurations
diff --git a/docs/website/docs/guides/ml-frameworks/onnx.md b/docs/website/docs/guides/ml-frameworks/onnx.md
index 5be3190..64dadad 100644
--- a/docs/website/docs/guides/ml-frameworks/onnx.md
+++ b/docs/website/docs/guides/ml-frameworks/onnx.md
@@ -57,10 +57,9 @@
[building from source](../../building-from-source/getting-started.md#python-bindings)
or from pip:
- === "Stable releases"
+ === ":octicons-package-16: Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install \
@@ -68,7 +67,7 @@
iree-base-runtime
```
- === ":material-alert: Nightly releases"
+ === ":octicons-beaker-16: Nightly releases"
Nightly pre-releases are published on
[GitHub releases](https://github.com/iree-org/iree/releases).
diff --git a/docs/website/docs/guides/ml-frameworks/pytorch.md b/docs/website/docs/guides/ml-frameworks/pytorch.md
index 722d0ba..c94194b 100644
--- a/docs/website/docs/guides/ml-frameworks/pytorch.md
+++ b/docs/website/docs/guides/ml-frameworks/pytorch.md
@@ -72,6 +72,9 @@
--index-url https://download.pytorch.org/whl/test/cpu torch==2.4.1
```
+<!-- TODO(scotttodd): mention nightly releases after
+ https://github.com/iree-org/iree/issues/19193 is fixed -->
+
Install iree-turbine:
``` shell
diff --git a/docs/website/docs/guides/ml-frameworks/tensorflow.md b/docs/website/docs/guides/ml-frameworks/tensorflow.md
index 253dd57..bf328ef 100644
--- a/docs/website/docs/guides/ml-frameworks/tensorflow.md
+++ b/docs/website/docs/guides/ml-frameworks/tensorflow.md
@@ -61,8 +61,7 @@
=== "Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install \
diff --git a/docs/website/docs/guides/ml-frameworks/tflite.md b/docs/website/docs/guides/ml-frameworks/tflite.md
index 9e96da4..7b5ebe8 100644
--- a/docs/website/docs/guides/ml-frameworks/tflite.md
+++ b/docs/website/docs/guides/ml-frameworks/tflite.md
@@ -56,8 +56,7 @@
=== "Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install \
diff --git a/docs/website/docs/reference/bindings/c-api.md b/docs/website/docs/reference/bindings/c-api.md
index 497efb2..01436f8 100644
--- a/docs/website/docs/reference/bindings/c-api.md
+++ b/docs/website/docs/reference/bindings/c-api.md
@@ -4,7 +4,7 @@
# C API bindings
-## Overview
+## :octicons-book-16: Overview
The IREE compiler and IREE runtime both have their own C/C++ APIs. This page
introduces the available APIs and describes how to use them from your
diff --git a/docs/website/docs/reference/bindings/python.md b/docs/website/docs/reference/bindings/python.md
index f23907d..0910c9c 100644
--- a/docs/website/docs/reference/bindings/python.md
+++ b/docs/website/docs/reference/bindings/python.md
@@ -8,25 +8,29 @@
# Python bindings
-## Overview
+## :octicons-book-16: Overview
-IREE offers Python bindings split into several packages, covering different
-components:
+IREE offers several Python packages, including API bindings, utilities, and
+integrations with frameworks:
-| PIP package name | Description |
-|------------------------------|-----------------------------------------------------------------------------|
-| `iree-base-compiler` | IREE's generic compiler tools and helpers |
-| `iree-base-runtime` | IREE's runtime, including CPU and GPU backends |
-| `iree-tools-tf` | Tools for importing from [TensorFlow](https://www.tensorflow.org/) |
-| `iree-tools-tflite` | Tools for importing from [TensorFlow Lite](https://www.tensorflow.org/lite) |
-| `iree-jax` | Tools for importing from [JAX](https://github.com/google/jax) |
+PIP package name | Description
+-- | --
+[`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/) | IREE's generic compiler tools and helpers
+[`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/) | IREE's runtime, including CPU and GPU backends
+[`iree-tools-tf`](https://pypi.org/project/iree-tools-tf/) | Tools for importing from [TensorFlow](https://www.tensorflow.org/)
+[`iree-tools-tflite`](https://pypi.org/project/iree-tools-tflite/) | Tools for importing from [TensorFlow Lite](https://www.tensorflow.org/lite)
+[`iree-turbine`](https://pypi.org/project/iree-turbine/) | IREE's frontend for [PyTorch](https://pytorch.org/)
Collectively, these packages allow for importing from frontends, compiling
towards various targets, and executing compiled code on IREE's backends.
-???+ Note "Note - `iree-compiler` and `iree-runtime` are deprecated"
- The Python packages `iree-compiler` and `iree-runtime` have been
- renamed to `iree-base-compiler` and `iree-base-runtime`
+???+ Info "Note - `iree-compiler` and `iree-runtime` are deprecated"
+ The Python packages
+ [`iree-compiler`](https://pypi.org/project/iree-compiler/) and
+ [`iree-runtime`](https://pypi.org/project/iree-runtime/) have been
+ renamed to
+ [`iree-base-compiler`](https://pypi.org/project/iree-base-compiler/) and
+ [`iree-base-runtime`](https://pypi.org/project/iree-base-runtime/)
respectively, thus effectively deprecating the old packages.
This name change only affects the names of the packages but not
the modules. To make sure the new packages are used, run
@@ -70,12 +74,11 @@
## Installing IREE packages
-### :octicons-package-16: Prebuilt packages
+### :octicons-download-16: Prebuilt packages
-=== "Stable releases"
+=== ":octicons-package-16: Stable releases"
- Stable release packages are
- [published to PyPI](https://pypi.org/user/google-iree-pypi-deploy/).
+ Stable release packages are [published to PyPI](https://pypi.org/).
``` shell
python -m pip install \
@@ -83,20 +86,22 @@
iree-base-runtime
```
-=== ":material-alert: Nightly pre-releases"
+=== ":octicons-beaker-16: Nightly pre-releases"
Nightly pre-releases are published on
[GitHub releases](https://github.com/iree-org/iree/releases).
- ``` shell
+ ``` shell hl_lines="2-4"
python -m pip install \
--find-links https://iree.dev/pip-release-links.html \
- --upgrade \
--pre \
+ --upgrade \
iree-base-compiler \
iree-base-runtime
```
+--8<-- "docs/website/docs/snippets/_iree-dev-packages.md"
+
### :material-hammer-wrench: Building from source
See [Building Python bindings](../../building-from-source/getting-started.md#python-bindings)
diff --git a/docs/website/docs/snippets/_iree-dev-packages.md b/docs/website/docs/snippets/_iree-dev-packages.md
new file mode 100644
index 0000000..29ddaeb
--- /dev/null
+++ b/docs/website/docs/snippets/_iree-dev-packages.md
@@ -0,0 +1,17 @@
+=== ":octicons-git-branch-16: Development packages"
+
+ Development packages are built at every commit and on pull requests, for
+ limited configurations.
+
+ On **Linux** with **Python 3.11**, development packages can be installed
+ into a [Python `venv`](https://docs.python.org/3/library/venv.html) using
+ the
+ [`build_tools/pkgci/setup_venv.py`](https://github.com/iree-org/iree/blob/main/build_tools/pkgci/setup_venv.py)
+ script:
+
+ ``` shell
+ # Install packages from a specific commit ref.
+ # See also the `--fetch-latest-main` and `--fetch-gh-workflow` options.
+ python ./build_tools/pkgci/setup_venv.py /tmp/.venv --fetch-git-ref=8230f41d
+ source /tmp/.venv/bin/activate
+ ```
