diff --git a/docs/nightly_releases.md b/docs/nightly_releases.md index 545cdd4f5..f41374445 100644 --- a/docs/nightly_releases.md +++ b/docs/nightly_releases.md @@ -1,12 +1,5 @@ # Nightly releases -> [!WARNING] -> This is still under development! See -> https://github.com/nod-ai/shark-ai/issues/400. -> -> These instructions will be converted into a user guide once stable packages -> are published to PyPI: . - Nightly releases are uploaded to https://github.com/nod-ai/shark-ai/releases/tag/dev-wheels. @@ -51,11 +44,9 @@ which python3.11 # /usr/bin/python3.11 ``` -> [!NOTE] -> Tip: manage multiple Python versions using `pyenv` -> (), or `update-alternatives` on Linux -> ([guide here](https://linuxconfig.org/how-to-change-from-default-to-alternative-python-version-on-debian-linux)) -> , or the +> [!TIP] +> Manage multiple Python versions using `pyenv` +> (), or the > [Python Launcher for Windows](https://docs.python.org/3/using/windows.html#python-launcher-for-windows) > on Windows. @@ -117,3 +108,106 @@ pip install -f https://iree.dev/pip-release-links.html --upgrade --pre \ iree-base-compiler iree-base-runtime --src deps \ -e "git+https://github.com/iree-org/iree-turbine.git#egg=iree-turbine" ``` + +## Switching between stable and nightly channels + +The [`shark-ai` package on PyPI](https://pypi.org/project/shark-ai/) is a +meta-package that pins specific stable versions of each package that share +at least their major and minor versions: + +```bash +pip install shark-ai==2.9.1 + +pip freeze +# ... +# iree-base-compiler==2.9.0 +# iree-base-runtime==2.9.0 +# iree-turbine==2.9.0 +# ... +# shark-ai==2.9.1 +# shortfin==2.9.1 +# ... +``` + +If you attempt to update any individual package outside of those supported +versions, pip will log an error but continue anyway: + +```bash +pip install --upgrade --pre \ + -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels \ + shortfin==3.0.0rc20241118 + +# Looking in links: https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels +# Collecting shortfin==3.0.0rc20241118 +# Downloading https://github.com/nod-ai/shark-ai/releases/download/dev-wheels/shortfin-3.0.0rc20241118-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB) +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.5/2.5 MB 24.3 MB/s eta 0:00:00 +# Installing collected packages: shortfin +# Attempting uninstall: shortfin +# Found existing installation: shortfin 2.9.1 +# Uninstalling shortfin-2.9.1: +# Successfully uninstalled shortfin-2.9.1 +# ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. +# shark-ai 2.9.1 requires shortfin==2.9.1, but you have shortfin 3.0.0rc20241118 which is incompatible. +# Successfully installed shortfin-3.0.0rc20241118 + +pip freeze +# ... +# shark-ai==2.9.1 +# shortfin==3.0.0rc20241118 +# ... +``` + +Installing the `shark-ai` package again should get back to aligned versions: + +```bash +pip install shark-ai==2.9.1 +# ... +# Installing collected packages: shortfin +# Attempting uninstall: shortfin +# Found existing installation: shortfin 3.0.0rc20241118 +# Uninstalling shortfin-3.0.0rc20241118: +# Successfully uninstalled shortfin-3.0.0rc20241118 +# Successfully installed shortfin-2.9.1 + +pip freeze +# ... +# shark-ai==2.9.1 +# shortfin==2.9.1 +# ... +``` + +You can also uninstall the `shark-ai` package to bypass the error and take full +control of package versions yourself: + +```bash +pip uninstall shark-ai + +pip freeze +# ... +# (note: no shark-ai package) +# shortfin==2.9.1 +# ... + +pip install --upgrade --pre \ + -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels \ + shortfin==3.0.0rc20241118 + +# Looking in links: https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels +# Collecting shortfin==3.0.0rc20241118 +# Using cached https://github.com/nod-ai/shark-ai/releases/download/dev-wheels/shortfin-3.0.0rc20241118-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB) +# Installing collected packages: shortfin +# Attempting uninstall: shortfin +# Found existing installation: shortfin 2.9.1 +# Uninstalling shortfin-2.9.1: +# Successfully uninstalled shortfin-2.9.1 +# Successfully installed shortfin-3.0.0rc20241118 + +pip freeze +# ... +# (note: no shark-ai package) +# shortfin==3.0.0rc20241118 +# ... +``` + +If you ever get stuck, consider creating a fresh +[virtual environment](https://docs.python.org/3/library/venv.html). diff --git a/docs/user_guide.md b/docs/user_guide.md index 13caa2acc..a0415eb63 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,9 +1,5 @@ # SHARK User Guide -> [!WARNING] -> This is still pre-release so the artifacts listed here may be broken -> - These instructions cover the usage of the latest stable release of SHARK. For a more bleeding edge release please install the [nightly releases](nightly_releases.md). ## Prerequisites @@ -12,7 +8,6 @@ Our current user guide requires that you have: - Access to a computer with an installed AMD Instinct™ MI300x Series Accelerator - Installed a compatible version of Linux and ROCm on the computer (see the [ROCm compatability matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html)) - ## Set up Environment This section will help you install Python and set up a Python environment with venv. @@ -51,11 +46,9 @@ pip install torch torchvision torchaudio --index-url https://download.pytorch.or pip install shark-ai[apps] ``` -Temporarily, you may need an update to your `shortfin` install. -Install the latest pre-release with: -``` -pip install shortfin --upgrade --pre -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels -``` +> [!TIP] +> To switch from the stable release channel to the nightly release channel, +> see [`nightly_releases.md`](./nightly_releases.md). ### Test the installation.