Update README for Halide 12 release. (#6034)

Author: alexreinking

README.md

@@ -4,10 +4,10 @@ Halide is a programming language designed to make it easier to write
 high-performance image and array processing code on modern machines. Halide
 currently targets:
 
-- CPU architectures: X86, ARM, MIPS, Hexagon, PowerPC
-- Operating systems: Linux, Windows, Mac OS X, Android, iOS, Qualcomm QuRT
-- GPU Compute APIs: CUDA, OpenCL, OpenGL Compute Shaders, Apple Metal,
-  Microsoft Direct X 12
+- CPU architectures: X86, ARM, MIPS, Hexagon, PowerPC, RISC-V
+- Operating systems: Linux, Windows, macOS, Android, iOS, Qualcomm QuRT
+- GPU Compute APIs: CUDA, OpenCL, OpenGL Compute Shaders, Apple Metal, Microsoft
+  Direct X 12
 
 Rather than being a standalone programming language, Halide is embedded in C++.
 This means you write C++ code that builds an in-memory representation of a
@@ -29,10 +29,10 @@ If you've acquired a full source distribution and want to build Halide, see the
 
 ## Binary tarballs
 
-The latest version of Halide is **Halide 11.0.1**. We provide binary releases
+The latest version of Halide is **Halide 12.0.0**. We provide binary releases
 for many popular platforms and architectures, including 32/64-bit x86 Windows,
 64-bit macOS, and 32/64-bit x86/ARM Ubuntu Linux. See the releases tab on the
-right (or click [here](https://github.com/halide/Halide/releases/tag/v10.0.0)).
+right (or click [here](https://github.com/halide/Halide/releases/tag/v12.0.0)).
 
 ## Vcpkg
 
@@ -43,13 +43,10 @@ you can install Halide via:
 $ vcpkg install halide:x64-windows # or x64-linux/x64-osx
 ```
 
-Note two caveats: first, at time of writing,
-[MSVC mis-compiles LLVM](https://github.com/halide/Halide/issues/5039) on
-x86-windows, so Halide cannot be used in vcpkg on that platform at this time;
-second, 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).
+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).
 
 ## Homebrew
 
@@ -62,60 +59,93 @@ $ brew install halide
 
 ## Other package managers
 
-We are interested in bringing Halide 10 to other popular package managers
-and Linux distribution repositories including, but not limited to, Conan,
+We are interested in bringing Halide 12 to other popular package managers and
+Linux distribution repositories including, but not limited to, Conan,
 Debian, [Ubuntu (or PPA)](https://github.com/halide/Halide/issues/5285),
-CentOS/Fedora, and Arch. If you have experience publishing packages we
-would be happy to work with you!
+CentOS/Fedora, and Arch. If you have experience publishing packages we would be
+happy to work with you!
 
-If you are a maintainer of any other package distribution platform, we would
-be excited to work with you, too.
+If you are a maintainer of any other package distribution platform, we would be
+excited to work with you, too.
+
+# Platform Support
+
+There are two sets of platform requirements relevant to Halide: those required
+to run the compiler library in either JIT or AOT mode, and those required to run
+the _binary outputs_ of the AOT compiler.
+
+These are the **tested** host toolchain and platform combinations for building
+and running the Halide compiler library.
+
+| Compiler   | Version      | OS                     | Architectures   |
+| ---------- | ------------ | ---------------------- | --------------- |
+| GCC        | 7.5          | Ubuntu Linux 20.04 LTS | x86, x64, ARM32 |
+| GCC        | 7.5          | Ubuntu Linux 18.04 LTS | ARM32, ARM64    |
+| MSVC       | 2019 (19.28) | Windows 10 (20H2)      | x86, x64        |
+| AppleClang | 12.0.0       | macOS 10.15            | x86_64          |
+| AppleClang | 12.0.0       | macOS 11.1             | ARM64           |
+
+Some users have successfully built Halide for Linux using Clang 9.0.0+, for
+Windows using ClangCL 11.0.0+, and for Windows ARM64 by cross-compiling with
+MSVC. We do not actively test these scenarios, however, so your mileage may
+vary.
+
+Beyond these, we are willing to support (by accepting PRs for) platform and
+toolchain combinations that still receive _active, first-party, public support_
+from their original vendors. For instance, at time of writing, this excludes
+Windows 7 and includes Ubuntu 18.04 LTS.
+
+Compiled AOT pipelines are expected to have much broader platform support. The
+binaries use the C ABI, and we expect any compliant C compiler to be able to use
+the generated headers correctly. The C++ bindings currently require C++11. If
+you discover a compatibility problem with a generated pipeline, please open an
+issue.
 
 # Building Halide with Make
 
 ### TL;DR
 
-Have llvm-9.0 (or greater) installed and run `make` in the root directory of the
-repository (where this README is).
+Have llvm-11.0 (or greater) installed and run `make` in the root directory of
+the repository (where this README is).
 
 ### Acquiring LLVM
 
 At any point in time, building Halide requires either the latest stable version
 of LLVM, the previous stable version of LLVM, and trunk. At the time of writing,
-this means versions 11.0 and 10.0 are supported, but 9.0 is not. The commands
+this means versions 12.0 and 11.0 are supported, but 10.0 is not. The commands
 `llvm-config` and `clang` must be somewhere in the path.
 
-If your OS does not have packages for llvm, you can find binaries for it at
+If your OS does not have packages for LLVM, you can find binaries for it at
 http://llvm.org/releases/download.html. Download an appropriate package and then
 either install it, or at least put the `bin` subdirectory in your path. (This
 works well on OS X and Ubuntu.)
 
 If you want to build it yourself, first check it out from GitHub:
 
 ```
-% git clone --depth 1 --branch llvmorg-11.0.0 https://github.com/llvm/llvm-project.git
+% git clone --depth 1 --branch llvmorg-12.0.0 https://github.com/llvm/llvm-project.git
 ```
 
-(If you want to build LLVM 10.x, use branch `llvmorg-10.0.1`; for current trunk,
+(If you want to build LLVM 11.x, use branch `llvmorg-11.1.0`; for current trunk,
 use `main`)
 
 Then build it like so:
 
 ```
 % cmake -DCMAKE_BUILD_TYPE=Release \
         -DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra" \
-        -DLLVM_TARGETS_TO_BUILD="X86;ARM;NVPTX;AArch64;Mips;Hexagon" \
+        -DLLVM_TARGETS_TO_BUILD="X86;ARM;NVPTX;AArch64;Mips;Hexagon;WebAssembly" \
         -DLLVM_ENABLE_TERMINFO=OFF -DLLVM_ENABLE_ASSERTIONS=ON \
         -DLLVM_ENABLE_EH=ON -DLLVM_ENABLE_RTTI=ON -DLLVM_BUILD_32_BITS=OFF \
         -S llvm-project/llvm -B llvm-build
 % cmake --build llvm-build
 % cmake --install llvm-build --prefix llvm-install
 ```
+
 Running a serial build will be slow. To improve speed, try running a parallel  
 build. That's done by default in Ninja; for make, use the option -j NNN,   
-where NNN is the number of parallel jobs, e.g. the number of CPUs you have. 
-
-then to point Halide to it:
+where NNN is the number of parallel jobs, e.g. the number of CPUs you have.
+Then, point Halide to it:
 
 ```
 % export LLVM_ROOT=$PWD/llvm-install
@@ -125,8 +155,8 @@ then to point Halide to it:
 Note that you _must_ add `clang` to `LLVM_ENABLE_PROJECTS`; adding `lld` to
 `LLVM_ENABLE_PROJECTS` is only required when using WebAssembly, and adding
 `clang-tools-extra` is only necessary if you plan to contribute code to Halide
-(so that you can run clang-tidy on your pull requests). We recommend enabling
-both in all cases, to simplify builds. You can disable exception handling (EH)
+(so that you can run `clang-tidy` on your pull requests). We recommend enabling
+both in all cases to simplify builds. You can disable exception handling (EH)
 and RTTI if you don't want the Python bindings.
 
 ### Building Halide with make
@@ -136,8 +166,7 @@ just run `make` in the root directory of the Halide source tree.
 `make run_tests` will run the JIT test suite, and `make test_apps` will make
 sure all the apps compile and run (but won't check their output).
 
-There is no `make install` yet. If you want to make an install package, run
-`make distrib`.
+There is no `make install`. If you want to make an install package, use CMake.
 
 ### Building Halide out-of-tree with make
 
@@ -156,16 +185,16 @@ Follow the above instructions to build LLVM or acquire a suitable binary
 release. Then change directory to the Halide repository and run:
 
 ```
-% cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR=$LLVM_ROOT/lib/cmake/llvm -S . -B build
+% cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR=$LLVM_ROOT/lib/cmake/llvm -S . -B build
 % cmake --build build
 ```
 
 `LLVM_DIR` is the folder in the LLVM installation tree **(do not use the build
 tree by mistake)** that contains `LLVMConfig.cmake`. It is not required to set
 this variable if you have a suitable system-wide version installed. If you have
 multiple system-wide versions installed, you can specify the version with
-`Halide_REQUIRE_LLVM_VERSION`. Add `-G Ninja` if you prefer to build with the
-Ninja generator.
+`Halide_REQUIRE_LLVM_VERSION`. Remove `-G Ninja` if you prefer to build with a
+different generator.
 
 ### Windows
 
@@ -236,7 +265,7 @@ this by specifying, for example:
 Then run the build with:
 
 ```
-D:\Halide> cmake --build build --config Release -j %NUMBER_OF_PROCESSORS%
+D:\Halide> cmake --build build --config Release
 ```
 
 To run all the tests:
@@ -252,10 +281,10 @@ Subsets of the tests can be selected with `-L` and include `correctness`,
 #### Building LLVM (optional)
 
 Follow these steps if you want to build LLVM yourself. First, download LLVM's
-sources (these instructions use the latest 11.0 release)
+sources (these instructions use the latest 12.0 release)
 
 ```
-D:\> git clone --depth 1 --branch llvmorg-11.0.0 https://github.com/llvm/llvm-project.git
+D:\> git clone --depth 1 --branch llvmorg-12.0.0 https://github.com/llvm/llvm-project.git
 ```
 
 For a 64-bit build, run:
@@ -291,7 +320,7 @@ D:\> cmake -G Ninja ^
 Finally, run:
 
 ```
-D:\> cmake --build llvm-build --config Release -j %NUMBER_OF_PROCESSORS%
+D:\> cmake --build llvm-build --config Release
 D:\> cmake --install llvm-build --prefix llvm-install
 ```
 
@@ -337,47 +366,44 @@ 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++.
 
-# Halide OpenGL/GLSL backend
-
-TODO(https://github.com/halide/Halide/issues/5633): update this for OpenGLCompute, which is staying
-
 # Halide for Hexagon HVX
 
 Halide supports offloading work to Qualcomm Hexagon DSP on Qualcomm Snapdragon
-835 devices or newer. The Hexagon DSP provides a set of 128 byte vector instruction
-extensions - the Hexagon Vector eXtensions (HVX). HVX is well suited for image
-processing, and Halide for Hexagon HVX will generate the appropriate HVX vector
-instructions from a program authored in Halide.
+835 devices or newer. The Hexagon DSP provides a set of 128 byte vector
+instruction extensions - the Hexagon Vector eXtensions (HVX). HVX is well suited
+for image processing, and Halide for Hexagon HVX will generate the appropriate
+HVX vector instructions from a program authored in Halide.
 
 Halide can be used to compile Hexagon object files directly, by using a target
 such as `hexagon-32-qurt-hvx`.
 
 Halide can also be used to offload parts of a pipeline to Hexagon using the
 `hexagon` scheduling directive. To enable the `hexagon` scheduling directive,
-include the `hvx` target feature in your target. The currently
-supported combination of targets is to use the HVX target features with an x86
-linux host (to use the simulator) or with an ARM android target (to use Hexagon
-DSP hardware). For examples of using the `hexagon` scheduling directive on both
-the simulator and a Hexagon DSP, see the blur example app.
+include the `hvx` target feature in your target. The currently supported
+combination of targets is to use the HVX target features with an x86 linux
+host (to use the simulator) or with an ARM android target (to use Hexagon DSP
+hardware). For examples of using the `hexagon` scheduling directive on both the
+simulator and a Hexagon DSP, see the blur example app.
 
 To build and run an example app using the Hexagon target,
 
 1. Obtain and build trunk LLVM and Clang. (Earlier versions of LLVM may work but
    are not actively tested and thus not recommended.)
-2. Download and install the Hexagon SDK and Hexagon Tools. Hexagon SDK 3.4.1 or later
-   is needed. Hexagon Tools 8.2 or later is needed.
+2. Download and install the Hexagon SDK and Hexagon Tools. Hexagon SDK 3.4.1 or
+   later is needed. Hexagon Tools 8.2 or later is needed.
 3. Build and run an example for Hexagon HVX
 
 ### 1. Obtain and build trunk LLVM and Clang
 
-(Instructions given previous, just be sure to check out the `master` branch.)
+(Follow the instructions given previously, just be sure to check out the `main`
+branch.)
 
 ### 2. Download and install the Hexagon SDK and Hexagon Tools
 
 Go to https://developer.qualcomm.com/software/hexagon-dsp-sdk/tools
 
-1. Select the Hexagon Series 600 Software and download the 3.4.1 version or later
-   for Linux.
+1. Select the Hexagon Series 600 Software and download the 3.4.1 version or
+   later for Linux.
 2. untar the installer
 3. Run the extracted installer to install the Hexagon SDK and Hexagon Tools,
    selecting Installation of Hexagon SDK into `/location/of/SDK/Hexagon_SDK/3.x`
@@ -405,7 +431,8 @@ LD_LIBRARY_PATH=../../src/runtime/hexagon_remote/bin/host/:$HL_HEXAGON_TOOLS/lib
 
 To build the example for Android, first ensure that you have Android NDK r19b or
 later installed, and the ANDROID_NDK_ROOT environment variable points to it.
-(Note that Qualcomm Hexagon SDK v3.5.2 includes Android NDK r19c, which is fine.)
+(Note that Qualcomm Hexagon SDK v3.5.2 includes Android NDK r19c, which is
+fine.)
 
 Now build and run the blur example using the script to run it on device: