a language for fast, portable data-parallel computation
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:
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 Halide pipeline using Halide's C++ API. You can then compile this representation to an object file, or JIT-compile it and run it in the same process. Halide also provides a Python binding that provides full support for writing Halide embedded in Python without C++.
For more detail about what Halide is, see http://halide-lang.org.
For API documentation see http://halide-lang.org/docs
To see some example code, look in the tutorials directory.
If you've acquired a full source distribution and want to build Halide, see the notes below.
The latest version of Halide is Halide 11.0.1. 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).
If you use vcpkg to manage dependencies, 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 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-windowsinstead. Note that since this will build LLVM, it will take a lot of disk space (up to 100GB).
Alternatively, if you use macOS, you can install Halide via Homebrew like so:
$ brew install halide
We are interested in bringing Halide 10 to other popular package managers and Linux distribution repositories including, but not limited to, Conan, Debian, Ubuntu (or PPA), 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.
Have llvm-9.0 (or greater) installed and run
makein the root directory of the repository (where this README is).
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
clangmust be somewhere in the path.
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
binsubdirectory 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
(If you want to build LLVM 10.x, use branch
llvmorg-10.0.1; for current trunk, use
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_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:
% export LLVM_ROOT=$PWD/llvm-install % export LLVM_CONFIG=$LLVM_ROOT/bin/llvm-config
Note that you must add
LLVM_ENABLE_PROJECTSis only required when using WebAssembly, and adding
clang-tools-extrais 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) and RTTI if you don't want the Python bindings.
llvm-configin your path), you should be able to just run
makein the root directory of the Halide source tree.
make run_testswill run the JIT test suite, and
make test_appswill make sure all the apps compile and run (but won't check their output).
There is no
make installyet. If you want to make an install package, run
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
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 --build build
LLVM_DIRis 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
-G Ninjaif you prefer to build with the Ninja generator.
We suggest building with Visual Studio 2019. Your mileage may vary with earlier versions. Be sure to install the "C++ CMake tools for Windows" in the Visual Studio installer. For older versions of Visual Studio, do not install the CMake tools, but instead acquire CMake and Ninja from their respective project websites.
These instructions start from the
D:drive. We assume this git repo is cloned to
D:\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\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
For a 32-bit build, run:
D:\> "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_x86
The best way to get compatible dependencies on Windows is to use vcpkg. Install it like so:
D:\> git clone https://github.com/Microsoft/vcpkg.git D:\> cd vcpkg D:\> .\bootstrap-vcpkg.bat D:\vcpkg> .\vcpkg integrate install ... CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
Then install the libraries. For a 64-bit build, run:
D:\vcpkg> .\vcpkg install libpng:x64-windows libjpeg-turbo:x64-windows llvm[target-all,clang-tools-extra]:x64-windows
To support 32-bit builds, also run:
D:\vcpkg> .\vcpkg install libpng:x86-windows libjpeg-turbo:x86-windows llvm[target-all,clang-tools-extra]:x86-windows
Create a separate build tree and call CMake with vcpkg's toolchain. This will build in either 32-bit or 64-bit depending on the environment script (
vcvars) that was run earlier.
D:\Halide> cmake -G Ninja ^ -DCMAKE_BUILD_TYPE=Release ^ -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^ -S . -B build
Note: If building with Python bindings on 32-bit (enabled by default), be sure to point CMake to the installation path of a 32-bit Python 3. You can do this by specifying, for example:
"-DPython3_ROOT_DIR=C:\Program Files (x86)\Python38-32".
Then run the build with:
D:\Halide> cmake --build build --config Release -j %NUMBER_OF_PROCESSORS%
To run all the tests:
D:\Halide> cd build D:\Halide\build> ctest -C Release
Subsets of the tests can be selected with
error, and the other directory names under
Follow these steps if you want to build LLVM yourself. First, download LLVM's sources (these instructions use the latest 11.0 release)
D:\> git clone --depth 1 --branch llvmorg-11.0.0 https://github.com/llvm/llvm-project.git
For a 64-bit build, run:
D:\> cmake -G Ninja ^ -DCMAKE_BUILD_TYPE=Release ^ -DLLVM_ENABLE_PROJECTS=clang;lld;clang-tools-extra ^ -DLLVM_ENABLE_TERMINFO=OFF ^ -DLLVM_TARGETS_TO_BUILD=X86;ARM;NVPTX;AArch64;Mips;Hexagon ^ -DLLVM_ENABLE_ASSERTIONS=ON ^ -DLLVM_ENABLE_EH=ON ^ -DLLVM_ENABLE_RTTI=ON ^ -DLLVM_BUILD_32_BITS=OFF ^ -S llvm-project\llvm -B llvm-build
For a 32-bit build, run:
D:\> cmake -G Ninja ^ -DCMAKE_BUILD_TYPE=Release ^ -DLLVM_ENABLE_PROJECTS=clang;lld;clang-tools-extra ^ -DLLVM_ENABLE_TERMINFO=OFF ^ -DLLVM_TARGETS_TO_BUILD=X86;ARM;NVPTX;AArch64;Mips;Hexagon ^ -DLLVM_ENABLE_ASSERTIONS=ON ^ -DLLVM_ENABLE_EH=ON ^ -DLLVM_ENABLE_RTTI=ON ^ -DLLVM_BUILD_32_BITS=ON ^ -S llvm-project\llvm -B llvm32-build
D:\> cmake --build llvm-build --config Release -j %NUMBER_OF_PROCESSORS% D:\> cmake --install llvm-build --prefix llvm-install
You can substitute
Releasein the above
cmakecommands if you want a debug build. Make sure to add
-DLLVM_DIR=D:/llvm-install/lib/cmake/llvmto the Halide CMake command to override
MSBuild: If you want to build LLVM with MSBuild instead of Ninja, use
-G "Visual Studio 16 2019" -Thost=x64 -A x64or
-G "Visual Studio 16 2019" -Thost=x64 -A Win32in place of
Do what the build-bots do: https://buildbot.halide-lang.org/master/#/builders
If the column that best matches your system is red, then maybe things aren't just broken for you. If it's green, then you can click the "stdio" links in the latest build to see what commands the build bots run, and what the output was.
HL_TARGET=...will set Halide's AOT compilation target.
HL_JIT_TARGET=...will set Halide's JIT compilation target.
HL_DEBUG_CODEGEN=1will 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 thread pool. When the async scheduling directive is used, more threads than this number may be required and thus allocated. A maximum of 256 threads is allowed. (By default, 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 one
trace_feature is enabled in
HL_JIT_TARGET). The output can be parsed programmatically by starting from the code in
Precompiled Halide distributions 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++.
TODO(https://github.com/halide/Halide/issues/5633): update this for OpenGLCompute, which is staying
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.
Halide can be used to compile Hexagon object files directly, by using a target such as
Halide can also be used to offload parts of a pipeline to Hexagon using the
hexagonscheduling directive. To enable the
hexagonscheduling directive, include the
hvxtarget 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
hexagonscheduling 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,
(Instructions given previous, just be sure to check out the
Go to https://developer.qualcomm.com/software/hexagon-dsp-sdk/tools
/location/of/SDK/Hexagon_SDK/3.xand the Hexagon tools into
In addition to running Hexagon code on device, Halide also supports running Hexagon code on the simulator from the Hexagon tools.
To build and run the blur example in Halide/apps/blur on the simulator:
cd apps/blur export HL_HEXAGON_SIM_REMOTE=../../src/runtime/hexagon_remote/bin/v62/hexagon_sim_remote export HL_HEXAGON_TOOLS=$SDK_LOC/Hexagon_Tools/8.x/Tools/ LD_LIBRARY_PATH=../../src/runtime/hexagon_remote/bin/host/:$HL_HEXAGON_TOOLS/lib/iss/:. HL_TARGET=host-hvx make test
To build the example for Android, first ensure that you have Android NDK r19b or later installed, and the ANDROIDNDKROOT environment variable points to it. (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:
export HL_HEXAGON_TOOLS=$SDK_LOC/HEXAGON_Tools/8.0/Tools/ HL_TARGET=arm-64-android-hvx ./adb_run_on_device.sh