Revise documentation to reflect recent changes (#9006)

Author: alexreinking

README.md

@@ -32,18 +32,25 @@ If you've acquired a full source distribution and want to build Halide, see the
 
 ## Pip
 
-As of Halide 19.0.0, we provide binary wheels on PyPI. Halide provides bindings
-for C++ and Python. Even if you only intend to use Halide from C++, pip may be
-the easiest way to get a binary build of Halide.
+We provide binary wheels on PyPI. Halide provides bindings for C++ and Python.
+Even if you only intend to use Halide from C++, pip may be the easiest way to
+get a binary build of Halide.
 
 Full releases may be installed with `pip` like so:
 
 ```shell
 $ pip install halide
 ```
 
-Every commit to `main` is published to a private PyPI index as a development
-version and these may be installed with a few extra flags:
+Every commit to `main` is published to our [package index][halide-pypi] as a
+development version. If you use [uv](https://docs.astral.sh/uv/), you can pin
+the nightly Halide in a project like so:
+
+```shell
+$ uv add halide --prerelease=allow --index https://pypi.halide-lang.org/simple
+```
+
+Or install directly with `pip`:
 
 ```shell
 $ pip install halide --pre --extra-index-url https://pypi.halide-lang.org/simple
@@ -59,9 +66,11 @@ installed it in. On Windows, you will need to add the virtual environment root
 directory to `CMAKE_PREFIX_PATH`. This can be done by running
 `set CMAKE_PREFIX_PATH=%VIRTUAL_ENV%` in `cmd`.
 
-Other build systems can find the Halide root path by running `python -c 
+Other build systems can find the Halide root path by running `python -c
 "import halide; print(halide.install_dir())"`.
 
+[halide-pypi]: https://pypi.halide-lang.org/simple
+
 ## Homebrew
 
 Alternatively, if you use macOS, you can install Halide via
@@ -80,16 +89,9 @@ We provide binary releases for many popular platforms and architectures,
 including 32/64-bit x86 Windows, 64-bit x86/ARM macOS, and 32/64-bit x86/ARM
 Ubuntu Linux.
 
-The macOS releases are built using XCode's command-line tools with Apple Clang
-500.2.76. This means that we link against libc++ instead of libstdc++. You may
-need to adjust compiler options accordingly if you're using an older XCode which
-does not default to libc++.
-
-We use a recent Ubuntu LTS to build the Linux releases; if your distribution is
-too old, it might not have the requisite glibc.
-
-Nightly builds of Halide and the LLVM versions we use in CI are also available
-at https://buildbot.halide-lang.org/
+The Linux tarballs are built on a recent Ubuntu LTS; if your distribution is too
+old, it might not have the requisite glibc. The [pip wheels](#pip) are built for
+manylinux_2_28 and are more broadly compatible.
 
 ## Vcpkg
 
@@ -102,8 +104,7 @@ $ vcpkg install halide:x64-windows # or x64-linux/x64-osx
 
 One caveat: vcpkg installs only the minimum Halide backends required to compile
 code for the active platform. If you want to include all the backends, you
-should install `halide[target-all]:x64-windows` instead. Note that since this
-will build LLVM, it will take a _lot_ of disk space (up to 100GB).
+should install `halide[target-all]:x64-windows` instead.
 
 ## Other package managers
 
@@ -153,22 +154,39 @@ At any point in time, building Halide requires either the latest stable version
 of LLVM, the previous stable version of LLVM, or trunk. At the time of writing,
 this means versions 23, 22, and 21 are supported, but 20 is not.
 
-It is simplest to get a binary release of LLVM on macOS by using
-[Homebrew](https://brew.sh). Just run `brew install llvm`. On Debian flavors of
-Linux, the [LLVM APT repo](https://apt.llvm.org) is best; use the provided
-installation script. We know of no suitable official binary releases for
-Windows, however the ones we use in CI can usually be found at
-https://buildbot.halide-lang.org, along with tarballs for our other tested
-platforms. See [the section on Windows](#windows) below for further advice.
+We publish the LLVM builds we use in CI as Python packages on our
+[package index][halide-pypi]. This is the easiest way to get a suitable LLVM on
+any platform. From the Halide source tree, install with
+[uv](https://docs.astral.sh/uv/):
+
+```shell
+$ uv sync --group ci-llvm-22 --no-install-project
+$ export Halide_LLVM_ROOT=$(halide-llvm --prefix)
+```
+
+Replace `22` with the desired LLVM major version (`21`, `22`, `23`, or `main`).
+Binary wheels are available for Linux (x86-64, x86-32, AArch64, ARMv7), macOS
+(x86-64, ARM64), and Windows (x86-64, x86-32).
+
+On macOS, [Homebrew](https://brew.sh) is also a good option: `brew install
+llvm`. On Debian flavors of Linux, the
+[LLVM APT repo](https://apt.llvm.org) works well; use the provided installation
+script.
+
+<details>
+<summary>Building LLVM from source (advanced)</summary>
+
+> [!WARNING]
+> Building LLVM from source requires significant time, disk space, and RAM.
+> Prefer the pre-built binaries above unless you need a custom configuration.
 
-If your OS does not have packages for LLVM, or you want more control over the
-configuration, you can build it yourself. First check it out from GitHub:
+First check it out from GitHub:
 
 ```shell
-$ git clone --depth 1 --branch llvmorg-21.1.1 https://github.com/llvm/llvm-project.git
+$ git clone --depth 1 --branch llvmorg-21.1.8 https://github.com/llvm/llvm-project.git
 ```
 
-(LLVM 21.1.1 is the most recent released LLVM at the time of writing. For
+(LLVM 21.1.8 is the most recent released LLVM at the time of writing. For
 current trunk, use `main` instead)
 
 Then build it like so:
@@ -210,6 +228,8 @@ Note that you _must_ add `clang` and `lld` to `LLVM_ENABLE_PROJECTS` and
 exception handling (EH) and RTTI if you don't want the Python bindings. We
 recommend enabling the full set to simplify builds during development.
 
+</details>
+
 ## Building Halide with CMake
 
 This is discussed in greater detail in [BuildingHalideWithCMake.md]. CMake
@@ -219,11 +239,11 @@ version 3.28+ is required to build Halide.
 
 ### MacOS and Linux
 
-Follow the above instructions to build LLVM or acquire a suitable binary
-release. Then change directory to the Halide repository and run:
+After [acquiring LLVM](#acquiring-llvm), change directory to the Halide
+repository and run:
 
 ```shell
-$ cmake -G Ninja  -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT=$LLVM_ROOT
+$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT=$LLVM_ROOT
 $ cmake --build build
 ```
 
@@ -232,6 +252,16 @@ version installed. However, if you have multiple LLVMs installed, it can pick
 between them. Do not use a relative path for `Halide_LLVM_ROOT`. It can cause
 problems on some systems.
 
+If you use [Homebrew](https://brew.sh/) on macOS, you can use the provided CMake
+preset:
+
+```shell
+$ cmake --preset=macOS -S . -B build
+$ cmake --build build
+```
+
+This automatically finds LLVM from Homebrew's install path.
+
 ### Windows
 
 We suggest building with Visual Studio 2022. Your mileage may vary with earlier
@@ -267,14 +297,12 @@ D:\vcpkg> .\bootstrap-vcpkg.bat -disableMetrics
 CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
 ```
 
-When using the toolchain file, vcpkg will automatically build all the necessary
-dependencies. However, as stated above, be aware that acquiring LLVM this way
-may use over 100 GB of disk space for its build trees and take a very long time
-to build. You can manually delete the build trees afterward, but vcpkg will not
-do this automatically.
-
-See [BuildingHalideWithCMake.md](./doc/BuildingHalideWithCMake.md#vcpkg-presets)
-for directions to use Vcpkg for everything _except_ LLVM.
+Halide includes a `vcpkg-configuration.json` that automatically configures
+[overlay ports](https://learn.microsoft.com/en-us/vcpkg/concepts/overlay-ports)
+and overlay triplets. These overlays redirect LLVM and Python to system
+installations, so vcpkg only builds the smaller dependencies (flatbuffers, wabt,
+pybind11, etc.). You must have LLVM and Python installed separately
+(see [Acquiring LLVM](#acquiring-llvm) above).
 
 #### Building Halide
 
@@ -288,9 +316,17 @@ D:\Halide> cmake -G Ninja -S . -B build ^
                  -DCMAKE_BUILD_TYPE=Release
 ```
 
-Then run the build with:
+Or use a CMake preset (e.g. for a Visual Studio build):
 
 ```
+D:\Halide> cmake --preset=win64  &:: or win32 for 32-bit
+D:\Halide> cmake --build build\win64
+```
+
+For a Ninja-based build with vcpkg:
+
+```
+D:\Halide> cmake --preset=release-vcpkg -S . -B build
 D:\Halide> cmake --build build
 ```
 
@@ -303,13 +339,18 @@ D:\Halide> ctest --test-dir build --output-on-failure
 Subsets of the tests can be selected with `-L` and include `correctness`,
 `generator`, `error`, and the other directory names under `tests/`.
 
-#### Building LLVM (optional)
+<details>
+<summary>Building LLVM from source on Windows (advanced)</summary>
 
-Follow these steps if you want to build LLVM yourself. First, download LLVM's
-sources (these instructions use the 21.1.1 release).
+> [!WARNING]
+> Building LLVM from source requires significant time, disk space, and RAM.
+> Prefer the pre-built `halide-llvm` binaries (see
+> [Acquiring LLVM](#acquiring-llvm)) unless you need a custom configuration.
+
+First, download LLVM's sources (these instructions use the 21.1.8 release).
 
 ```
-D:\> git clone --depth 1 --branch llvm-org-21.1.1 https://github.com/llvm/llvm-project.git
+D:\> git clone --depth 1 --branch llvmorg-21.1.8 https://github.com/llvm/llvm-project.git
 ```
 
 As above, run `vcvarsall.bat` to pick between x86 and x64. Then configure LLVM
@@ -347,10 +388,12 @@ D:\> cmake --install build --prefix llvm-install
 You can substitute `Debug` for `Release` in the above `cmake` commands if you
 want a debug build.
 
-To use this with Halide, but still allow vcpkg to manage other dependencies, you
-must add two flags to Halide's CMake configure command line. First, disable LLVM
-with `-DVCPKG_OVERLAY_PORTS=cmake/vcpkg`. Second, point CMake to our newly built
-Halide with `-DHalide_LLVM_ROOT=D:/llvm-install`.
+To use this with Halide, but still allow vcpkg to manage other dependencies,
+point CMake to your LLVM with `-DHalide_LLVM_ROOT=D:/llvm-install`. The overlay
+ports in `vcpkg-configuration.json` automatically prevent vcpkg from trying to
+build its own LLVM.
+
+</details>
 
 #### If all else fails...
 

doc/BuildingHalideWithCMake.md

@@ -187,26 +187,18 @@ for these packages is linked in the table above.
 
 Halide has first-class support for using [vcpkg] to manage dependencies. The
 list of dependencies and features is contained inside `vcpkg.json` at the root
-of the repository.
+of the repository. LLVM and Python must be provided by the system; vcpkg handles
+the remaining dependencies (flatbuffers, wabt, pybind11, libjpeg, libpng, etc.).
 
-By default, a minimum set of LLVM backends will be enabled to compile JIT code
-for the host and the serialization feature will be enabled. When using the vcpkg
-toolchain file, you can set `-DVCPKG_MANIFEST_FEATURES=developer`
-to enable building all dependencies (except Doxygen, which is not available on
-vcpkg).
+Halide includes a `vcpkg-configuration.json` file that automatically configures
+[overlay ports][vcpkg-overlay] and overlay triplets. The overlay ports redirect
+LLVM and Python to system installations, preventing vcpkg from trying to build
+them. This configuration is applied automatically when vcpkg is used from the
+Halide source tree.
 
-By default, running `vcpkg install` will try to build all of LLVM. This is often
-undesirable as it takes very long to do and consumes a lot of disk space,
-especially as `vcpkg` requires special configuration to disable the debug build.
-It will _also_ attempt to build Python 3 as a dependency of pybind11.
-
-To mitigate this issue, we provide a [vcpkg-overlay] that disables building LLVM
-and Python. When using the vcpkg toolchain, you can enable it by setting
-`-DVCPKG_OVERLAY_PORTS=cmake/vcpkg`.
-
-If you do choose to use vcpkg to build LLVM (the easiest way on Windows), note
-that it is safe to delete the intermediate build files and caches in
-`D:\vcpkg\buildtrees` and `%APPDATA%\local\vcpkg`.
+When using the vcpkg toolchain file, you can set
+`-DVCPKG_MANIFEST_FEATURES=developer` to enable building all test dependencies
+(except Doxygen, which is not available on vcpkg).
 
 For convenience, we provide [CMake presets](#cmake-presets) that set these flags
 appropriately per-platform. They are documented further below.
@@ -360,39 +352,32 @@ standard types: `Debug`, `RelWithDebInfo`, `MinSizeRel`, or `Release`.
 
 ## CMake Presets
 
+Halide provides several [presets][cmake_presets] to make the above commands more
+convenient.
+
 ### Common presets
 
-Halide provides several [presets][cmake_presets] to make the above commands more
-convenient. The following CMake preset commands correspond to the longer ones
-above.
+These presets do not use vcpkg. They assume that all dependencies are available
+via the system (e.g. Homebrew on macOS, APT on Linux).
 
 ```shell
-$ cmake --preset=win64    # VS 2022 generator, 64-bit build, vcpkg deps
-$ cmake --preset=win32    # VS 2022 generator, 32-bit build, vcpkg deps
 $ cmake --preset=macOS    # Ninja generator, macOS host build, Homebrew deps
 $ cmake --preset=debug    # Debug mode, any single-config generator / compiler
 $ cmake --preset=release  # Release mode, any single-config generator / compiler
 ```
 
 ### Vcpkg presets
 
-Halide provides two sets of corresponding vcpkg-enabled presets: _base_ and
-_full_.
-
-| Base preset     | Full preset          |
-|-----------------|----------------------|
-| `win32`         | `win32-vcpkg-full`   |
-| `win64`         | `win64-vcpkg-full`   |
-| `macOS-vcpkg`   | `macOS-vcpkg-full`   |
-| `debug-vcpkg`   | `debug-vcpkg-full`   |
-| `release-vcpkg` | `release-vcpkg-full` |
-
-In simple terms, the base presets rely on the system to provide LLVM and Python,
-while the full presets delegate this to vcpkg (which consumes a large amount of
-hard disk space and time).
+The following presets use vcpkg to manage non-LLVM dependencies. LLVM and Python
+must be provided by the system.
 
-The `macOS-vcpkg` preset adds `/opt/homebrew/opt/llvm` to
-`CMAKE_PREFIX_PATH`.
+| Preset          | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `win32`         | Visual Studio 2022 generator, 32-bit build               |
+| `win64`         | Visual Studio 2022 generator, 64-bit build               |
+| `macOS-vcpkg`   | macOS build with vcpkg + Homebrew LLVM                   |
+| `debug-vcpkg`   | Debug build for any single-config generator              |
+| `release-vcpkg` | Release build for any single-config generator            |
 
 ### Sanitizer presets
 

doc/Python.md

@@ -86,10 +86,12 @@ If you don't have LLVM installed already, you can try using the same ones the
 buildbots use by adding `--group ci-llvm-<VERSION>` to the `uv sync` command,
 where `<VERSION>` is the LLVM major version number (e.g. `23`) or `main`.
 
-If you install `ci-llvm-*`, you can set `Halide_LLVM_ROOT=$(halide-llvm 
+If you install `ci-llvm-*`, you can set `Halide_LLVM_ROOT=$(halide-llvm
 --prefix)` in your environment.
 
-Ensure you have `flatbuffers` and `wabt` installed, too.
+Ensure you have `flatbuffers` and `wabt` installed, too. (The wheel build does
+not use vcpkg for manylinux compatibility reasons, so these must be available as
+system packages or installed from source.)
 
 ### Using wheel infrastructure