Repository files navigation

Halide is a programming language designed to make it easier to writehigh-performance image and array processing code on modern machines. Halidecurrently targets:

• CPU architectures: X86, ARM, Hexagon, PowerPC, RISC-V
• Operating systems: Linux, Windows, macOS, Android, iOS, Qualcomm QuRT
• GPU Compute APIs: CUDA, OpenCL, Apple Metal, Microsoft Direct X 12, Vulkan

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 aHalide pipeline using Halide's C++ API. You can then compile this representationto an object file, or JIT-compile it and run it in the same process. Halide alsoprovides a Python binding that provides full support for writing Halide embeddedin Python without C++.

Halide requires C++17 (or later) to use.

For more detail about what Halide is, seehttps://halide-lang.org.

For API documentation seehttps://halide-lang.org/docs.

For some example code, read through the tutorials onlineathttps://halide-lang.org/tutorials. The corresponding code is in thetutorials/ directory. Larger examples are in theapps/ directory.

If you've acquired a full source distribution and want to build Halide, see thenotes below.

As of Halide 19.0.0, we provide binary wheels on PyPI. Halide provides bindingsfor C++ and Python. Even if you only intend to use Halide from C++, pip may bethe easiest way to get a binary build of Halide.

Full releases may be installed withpip like so:

$ pip install halide

Every commit tomain is published to Test PyPI as a development version andthese may be installed with a few extra flags:

$ pip install halide --pre --extra-index-url https://test.pypi.org/simple

Currently, we provide wheels for: Windows x86-64, macOS x86-64, macOS arm64, andLinux x86-64. The Linux wheels are built for manylinux_2_28, which makes thembroadly compatible (Debian 10, Ubuntu 18.10, Fedora 29).

For C++ usage of the pip package: On Linux and macOS, CMake'sfind_packagecommand should find Halide as long as you're in the same virtual environment youinstalled it in. On Windows, you will need to add the virtual environment rootdirectory toCMAKE_PREFIX_PATH. This can be done by runningset CMAKE_PREFIX_PATH=%VIRTUAL_ENV% incmd.

Other build systems can find the Halide root path by runningpython -c "import halide; print(halide.install_dir())".

Alternatively, if you use macOS, you can install Halide viaHomebrew like so:

$ brew install halide

The latest version of Halide can always be found on GitHubathttps://github.com/halide/Halide/releases

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/ARMUbuntu Linux.

The macOS releases are built using XCode's command-line tools with Apple Clang500.2.76. This means that we link against libc++ instead of libstdc++. You mayneed to adjust compiler options accordingly if you're using an older XCode whichdoes not default to libc++.

We use a recent Ubuntu LTS to build the Linux releases; if your distribution istoo old, it might not have the requisite glibc.

Nightly builds of Halide and the LLVM versions we use in CI are also availableathttps://buildbot.halide-lang.org/

If you usevcpkg to manage dependencies,you can install Halide via:

$ vcpkg install halide:x64-windows # or x64-linux/x64-osx

One caveat: vcpkg installs only the minimum Halide backends required to compilecode for the active platform. If you want to include all the backends, youshould installhalide[target-all]:x64-windows instead. Note that since thiswill build LLVM, it will take alot of disk space (up to 100GB).

We are interested in bringing Halide to other popular package managers and Linuxdistribution repositories! We track the status of various distributions ofHalidein this GitHub issue. Ifyou have experience publishing packages we would be happy to work with you!

There are two sets of platform requirements relevant to Halide: those requiredto run the compiler library in either JIT or AOT mode, and those required to runthebinary outputs of the AOT compiler.

These are thetested host toolchain and platform combinations for buildingand running the Halide compiler library.

Some users have successfully built Halide for Linux using Clang 9.0.0+, forWindows using ClangCL 11.0.0+, and for Windows ARM64 by cross-compiling withMSVC. We do not actively test these scenarios, however, so your mileage mayvary.

Beyond these, we are willing to support (by accepting PRs for) platform andtoolchain combinations that still receiveactive, first-party, public supportfrom their original vendors. For instance, at time of writing, this excludesWindows 7 and includes Ubuntu 18.04 LTS.

Compiled AOT pipelines are expected to have much broader platform support. Thebinaries use the C ABI, and we expect any compliant C compiler to be able to usethe generated headers correctly. The C++ bindings currently require C++17. Ifyou discover a compatibility problem with a generated pipeline, please open anissue.

At any point in time, building Halide requires either the latest stable versionof LLVM, the previous stable version of LLVM, or trunk. At the time of writing,this means versions 20, 19, and 18 are supported, but 17 is not.

It is simplest to get a binary release of LLVM on macOS by usingHomebrew. Just runbrew install llvm. On Debian flavors ofLinux, theLLVM APT repo is best; use the providedinstallation script. We know of no suitable official binary releases forWindows, however the ones we use in CI can usually be found athttps://buildbot.halide-lang.org, along with tarballs for our other testedplatforms. Seethe section on Windows below for further advice.

If your OS does not have packages for LLVM, or you want more control over theconfiguration, you can build it yourself. First check it out from GitHub:

$ git clone --depth 1 --branch llvmorg-19.1.5 https://github.com/llvm/llvm-project.git

(LLVM 19.1.5 is the most recent released LLVM at the time of writing. Forcurrent trunk, usemain instead)

Then build it like so:

$ cmake -G Ninja -S llvm-project/llvm -B build \        -DCMAKE_BUILD_TYPE=Release \        -DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra" \        -DLLVM_ENABLE_RUNTIMES=compiler-rt \        -DLLVM_TARGETS_TO_BUILD="WebAssembly;X86;AArch64;ARM;Hexagon;NVPTX;PowerPC;RISCV" \        -DLLVM_ENABLE_ASSERTIONS=ON \        -DLLVM_ENABLE_EH=ON \        -DLLVM_ENABLE_RTTI=ON \        -DLLVM_ENABLE_HTTPLIB=OFF \        -DLLVM_ENABLE_LIBEDIT=OFF \        -DLLVM_ENABLE_LIBXML2=OFF \        -DLLVM_ENABLE_TERMINFO=OFF \        -DLLVM_ENABLE_ZLIB=OFF \        -DLLVM_ENABLE_ZSTD=OFF \        -DLLVM_BUILD_32_BITS=OFF$ cmake --build build$ cmake --install build --prefix llvm-install

This will produce a working LLVM installation in$PWD/llvm-install. We referto this path asLLVM_ROOT later.Do not confuse this installation tree withthe build tree!

LLVM takes a long time to build, so the above command uses Ninja to maximizeparallelism. If you choose to omit-G Ninja, Makefiles will be generatedinstead. In this case, enable parallelism withcmake --build build -j NNNwhereNNN is the number of parallel jobs, i.e. the number of CPUs you have.

Note that youmust addclang andlld toLLVM_ENABLE_PROJECTS andWebAssembly andX86must be included inLLVM_TARGETS_TO_BUILD.LLVM_ENABLE_RUNTIMES=compiler-rt is only required to build the fuzz tests, andclang-tools-extra is only necessary if you plan to contribute code to Halide(so that you can runclang-tidy on your pull requests). You can disableexception handling (EH) and RTTI if you don't want the Python bindings. Werecommend enabling the full set to simplify builds during development.

This is discussed in greater detail inBuildingHalideWithCMake.md. CMakeversion 3.28+ is required to build Halide.

Follow the above instructions to build LLVM or acquire a suitable binaryrelease. Then change directory to the Halide repository and run:

$ cmake -G Ninja  -S. -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT=$LLVM_ROOT$ cmake --build build

Setting-DHalide_LLVM_ROOT is not required if you have a suitable system-wideversion installed. However, if you have multiple LLVMs installed, it can pickbetween them.

We suggest building with Visual Studio 2022. Your mileage may vary with earlierversions. Be sure to install the "C++ CMake tools for Windows" in the VisualStudio installer. For older versions of Visual Studio, do not install the CMaketools, but instead acquire CMake and Ninja from their respective projectwebsites.

These instructions start from theD: drive. We assume this git repo is clonedtoD:\Halide. We also assume that your shell environment is set up correctly.For a 64-bit build, run:

D:\> "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

For a 32-bit build, run:

D:\> "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_x86

The best way to get compatible dependencies on Windows is to usevcpkg. Install it like so:

D:\> git clone https://github.com/Microsoft/vcpkg.gitD:\> cd vcpkgD:\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 necessarydependencies. However, as stated above, be aware that acquiring LLVM this waymay use over 100 GB of disk space for its build trees and take a very long timeto build. You can manually delete the build trees afterward, but vcpkg will notdo this automatically.

SeeBuildingHalideWithCMake.mdfor directions to use Vcpkg for everythingexcept LLVM.

Create a separate build tree and call CMake with vcpkg's toolchain. This willbuild in either 32-bit or 64-bit depending on the environment script (vcvars)that was run earlier.

D:\Halide> cmake -G Ninja -S . -B build ^                 --toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^                 -DCMAKE_BUILD_TYPE=Release

Then run the build with:

D:\Halide> cmake --build build

To run all the tests:

D:\Halide> ctest --test-dir build --output-on-failure

Subsets of the tests can be selected with-L and includecorrectness,generator,error, and the other directory names undertests/.

Follow these steps if you want to build LLVM yourself. First, download LLVM'ssources (these instructions use the 19.1.5 release).

D:\> git clone --depth 1 --branch llvm-org-19.1.5 https://github.com/llvm/llvm-project.git

As above, runvcvarsall.bat to pick between x86 and x64. Then configure LLVMwith the following command (for 32-bit, set-DLLVM_BUILD_32_BITS=ON instead):

D:\> cmake -G Ninja -S llvm-project\llvm -B build ^           -DCMAKE_BUILD_TYPE=Release ^           -DLLVM_ENABLE_PROJECTS=clang;lld;clang-tools-extra ^           -DLLVM_ENABLE_RUNTIMES=compiler-rt ^           -DLLVM_TARGETS_TO_BUILD=WebAssembly;X86;AArch64;ARM;Hexagon;NVPTX;PowerPC;RISCV ^           -DLLVM_ENABLE_ASSERTIONS=ON ^           -DLLVM_ENABLE_EH=ON ^           -DLLVM_ENABLE_RTTI=ON ^           -DLLVM_ENABLE_HTTPLIB=OFF ^           -DLLVM_ENABLE_LIBEDIT=OFF ^           -DLLVM_ENABLE_LIBXML2=OFF ^           -DLLVM_ENABLE_TERMINFO=OFF ^           -DLLVM_ENABLE_ZLIB=OFF ^           -DLLVM_ENABLE_ZSTD=OFF ^           -DLLVM_BUILD_32_BITS=OFF

MSBuild: If you want to build LLVM with MSBuild instead of Ninja, use-G "Visual Studio 17 2022" -Thost=x64 -A x64 or-G "Visual Studio 17 2022" -Thost=x64 -A Win32 in place of-G Ninja.

Finally, run the build and install to a local directory:

D:\> cmake --build build --config ReleaseD:\> cmake --install build --prefix llvm-install

You can substituteDebug forRelease in the abovecmake commands if youwant a debug build.

To use this with Halide, but still allow vcpkg to manage other dependencies, youmust add two flags to Halide's CMake configure command line. First, disable LLVMwith-DVCPKG_OVERLAY_PORTS=cmake/vcpkg. Second, point CMake to our newly builtHalide with-DHalide_LLVM_ROOT=D:/llvm-install.

Do what the buildbots do:https://buildbot.halide-lang.org/master/#/builders

If the row that best matches your system is red, then maybe things aren't justbroken for you. If it's green, then you can click through to the latest buildand see the commands that the build bots run. Open a step ("Configure Halide" isuseful) and look at the "stdio" logs in the viewer. These logs contain the fullcommands that were run, as well as the environment variables they were run with.

TL;DR: Have LLVM 17 (or greater) installed and runmake in the rootdirectory of the repository (where this README is).

By default,make will use thellvm-config tool found in thePATH. If youwant to use a different LLVM, such as a custom-built one following theinstructions above, set the following environment variable:

$export LLVM_CONFIG="$LLVM_ROOT/bin/llvm-config"

Now you should be able to just runmake in the root directory of the Halidesource tree.make run_tests will run the JIT test suite, andmake test_appswill make sure all the apps compile and run (but won't check their output).

When building the tests, you can set the AOT compilation target with theHL_TARGET environment variable.

If you wish to build Halide in a separate directory, you can do that like so:

$cd ..$ mkdir halide_build$cd halide_build$ make -f ../Halide/Makefile

HL_JIT_TARGET=... will set Halide's JIT compilation target.

HL_DEBUG_CODEGEN=1 will print out pseudocode for what Halide is compiling.Higher numbers will print more detail.

HL_NUM_THREADS=... specifies the number of threads to create for the threadpool. When the async scheduling directive is used, more threads than this numbermay be required and thus allocated. A maximum of 256 threads is allowed. (Bydefault, the number of cores on the host is used.)

HL_TRACE_FILE=... specifies a binary target file to dump tracing data into(ignored unless at least onetrace_ feature is enabled in the target). Theoutput can be parsed programmatically by starting from the code inutils/HalideTraceViz.cpp.

We have more documentation indoc/, the following links might be helpful:

The following links are of greater interest to developers wishing to contributecode to Halide: