This is a detailed guide to building Halide with CMake. If you want to learn how to use Halide in your own CMake projects, see HalideCMakePackage.md. If you are looking for Halide's CMake coding guidelines, see CodeStyleCMake.md.
This section covers installing a recent version of CMake and the correct dependencies for building and using Halide. If you have not used CMake before, we strongly suggest reading through the CMake documentation first.
Halide requires at least version 3.28. Fortunately, getting a recent version of CMake couldn't be easier, and there are multiple good options on any system to do so. Generally, one should always have the most recent version of CMake installed system-wide. CMake is committed to backwards compatibility and even the most recent release can build projects over a decade old.
Kitware provides packages for CMake on PyPI which can be installed
via pip into a virtual environment. There are binary wheels available
for nearly all relevant platforms, including:
| OS | x86-32 | x86-64 | ARM64 |
|---|---|---|---|
| Windows | ✅ | ✅ | ✅ |
| macOS | ❌ | 10.10+ | 11.0+ (incl. universal2) |
| Linux (musl 1.1+) | ✅ | ✅ | ✅ |
| Linux (glibc) | glibc 2.12+ | glibc 2.12+ | glibc 2.17+ |
We recommend installing CMake using pipx to avoid package conflicts and redundant installations. After installing pipx, run:
$ pipx install cmakeAlternatively, you can use a normal virtual environment:
$ python -m pip install cmakeIf you don't want Python to manage your CMake installation, you can either follow the platform-specific instructions below or install CMake from Kitware's binary releases. If all else fails, you might need to build CMake from source (e.g. on 32-bit ARM). In that case, follow the directions posted on Kitware's website.
On Windows, there are two primary methods for installing an up-to-date CMake:
- You can get CMake through the Visual Studio 2022 installer.
- You can use Windows's built-in package manager, winget:
winget install Kitware.CMake
We prefer the first option for its simplicity. See Microsoft's documentation for more details.
Homebrew keeps its CMake package up to date. Simply run:
$ brew install cmakeThere are a few good ways to install CMake on Ubuntu:
- If you're running 24.04 LTS, then simply running
sudo apt install cmakewill install CMake 3.28. - If you're running an older LTS or would like to use the newest CMake, try
installing via the snap store:
snap install cmake. Note this will conflict with an APT-provided CMake. - Kitware also provides an APT repository with up-to-date releases. Compatible with 20.04 LTS+ and is the best option for 32-bit ARM.
For other Linux distributions, check with your distribution's package manager.
Note: On WSL 1, snap is not available; in this case, prefer to use APT. On WSL 2, all methods are available.
We strongly recommend using Ninja as your go-to CMake generator for working with Halide. It has a much richer dependency structure than the alternatives, and it is the only generator capable of producing accurate incremental builds.
It is available in most package repositories:
- Python:
pipx install ninja - Visual Studio Installer: alongside CMake
- winget:
winget install Ninja-build.Ninja - Homebrew:
brew install ninja - APT:
apt install ninja-build
You can also place a pre-built binary from their website in the PATH.
The following is a complete list of required and optional dependencies for building the core pieces of Halide.
| Dependency | Version | Required when... | Notes |
|---|---|---|---|
| LLVM | see policy below | always | WebAssembly and X86 targets are required. |
| Clang | ==LLVM |
always | |
| LLD | ==LLVM |
always | |
| flatbuffers | ~=23.5.26 |
WITH_SERIALIZATION=ON |
|
| wabt | ==1.0.36 |
Halide_WASM_BACKEND=wabt |
Does not have a stable API; exact version required. |
| V8 | trunk | Halide_WASM_BACKEND=V8 |
Difficult to build. See WebAssembly.md |
| Python | >=3.8 |
WITH_PYTHON_BINDINGS=ON |
|
| pybind11 | ~=2.10.4 |
WITH_PYTHON_BINDINGS=ON |
Halide maintains the following compatibility policy with LLVM: Halide version
N supports LLVM versions N, N-1, and N-2. Our binary distributions
always include the latest N patch at time of release. For most users, we
recommend using a pre-packaged binary release of LLVM rather than trying to
build it yourself.
To build the apps, documentation, and tests, an extended set is needed.
| Dependency | Required when... | Notes |
|---|---|---|
| CUDA Toolkit | building apps/cuda_mat_mul |
When compiling Halide pipelines that use CUDA, only the drivers are needed. |
| Doxygen | WITH_DOCS=ON |
|
| Eigen3 | building apps/linear_algebra |
|
| libjpeg | WITH_TESTS=ON |
Optionally used by halide_image_io.h and Halide::ImageIO in CMake. |
| libpng | WITH_TESTS=ON |
(same as libjpeg) |
| BLAS | building apps/linear_algebra |
ATLAS and OpenBLAS are supported implementations |
| OpenCL | compiling pipelines with opencl |
It is best practice to configure your environment so that CMake can find
dependencies without package-specific hints. For instance, if you want CMake to
use a particular version of Python, create a virtual environment and activate it
before configuring Halide. Similarly, the CMAKE_PREFIX_PATH variable can be
set to a local directory where from-source dependencies have been installed.
Carefully consult the find_package documentation to learn how the search
procedure works.
If the build still fails to find a dependency, each package provides a bespoke interface for providing hints and overriding incorrect results. Documentation 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.
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).
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.
For convenience, we provide CMake presets that set these flags appropriately per-platform. They are documented further below.
On Windows, we recommend using vcpkg to install library dependencies.
To build the documentation, you will need to install Doxygen. This can be done either from the Doxygen website or through winget:
$ winget install DimitriVanHeesch.DoxygenTo build the Python bindings, you will need to install Python 3. This should be
done by running the official installer from the Python website. Be
sure to download the debugging symbols through the installer. This will require
using the "Advanced Installation" workflow. Although it is not strictly
necessary, it is convenient to install Python system-wide on Windows (i.e.
C:\Program Files) because CMake looks at standard paths and registry keys.
This removes the need to manually set the PATH.
Once Python is installed, you can install the Python module dependencies either globally or in a virtual environment by running
$ python -m pip install -r requirements.txtfrom the root of the repository.
On macOS, it is possible to install all dependencies via Homebrew:
$ brew install llvm flatbuffers wabt python pybind11 doxygen eigen libpng libjpeg openblasThe llvm package includes clang, clang-format, and lld, too. To ensure
CMake can find the keg-only dependencies, set the following:
$ export CMAKE_PREFIX_PATH="/opt/homebrew:/opt/homebrew/opt/llvm:/opt/homebrew/opt/jpeg"On Ubuntu you should install the following packages (this includes the Python module dependencies):
$ sudo apt install clang-tools lld llvm-dev libclang-dev liblld-dev \
libpng-dev libjpeg-dev libgl-dev python3-dev python3-numpy python3-scipy \
python3-imageio python3-pybind11 libopenblas-dev libeigen3-dev \
libatlas-base-dev doxygen
When running the Python package, you will need to install additional
dependencies. These are tabulated in requirements.txt and may be installed
with:
$ python -m pip install -U pip "setuptools[core]" wheel
$ python -m pip install -r requirements.txtThese instructions assume that your working directory is the Halide repository root.
If you plan to use the Ninja generator, be sure to launch the developer command prompt corresponding to your intended environment. Note that whatever your intended target system (x86, x64, or ARM), you must use the 64-bit host tools because the 32-bit tools run out of memory during the linking step with LLVM. More information is available from Microsoft's documentation.
You should either open the correct Developer Command Prompt directly or run the
vcvarsall.bat script with the correct argument, i.e. one of the
following:
$ "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
$ "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_x86
$ "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_armThen, assuming that vcpkg is installed to D:\vcpkg, simply run:
$ cmake -G Ninja -S . -B build --toolchain D:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Release
$ cmake --build .\buildValid values of CMAKE_BUILD_TYPE are Debug,
RelWithDebInfo, MinSizeRel, and Release. When using a single-configuration
generator (like Ninja) you must specify a build type in the configuration step.
Otherwise, if you wish to create a Visual Studio based build system, you can configure with:
$ cmake -G "Visual Studio 17 2022" -Thost=x64 -A x64 -S . -B build ^
--toolchain D:\vcpkg\scripts\buildsystems\vcpkg.cmake
$ cmake --build .\build --config Release -j %NUMBER_OF_PROCESSORS%Because the Visual Studio generator is a multi-config generator, you don't set
CMAKE_BUILD_TYPE at configure-time, but instead pass the configuration to the
build (and test/install) commands with the --config flag. More documentation
is available in the CMake User Interaction Guide.
The process is similar for 32-bit:
> cmake -G "Visual Studio 17 2022" -Thost=x64 -A Win32 -S . -B build ^
--toolchain D:\vcpkg\scripts\buildsystems\vcpkg.cmake
> cmake --build .\build --config Release -j %NUMBER_OF_PROCESSORS%
In both cases, the -Thost=x64 flag ensures that the correct host tools are
used.
Note: due to limitations in MSBuild, incremental builds using the VS
generators will miss dependencies (including changes to headers in the
src/runtime folder). We recommend using Ninja for day-to-day development and
use Visual Studio only if you need it for packaging.
The instructions here are straightforward. Assuming your environment is set up correctly, just run:
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release
$ cmake --build buildIf you omit -G Ninja, a Makefile-based generator will likely be used instead.
In either case, CMAKE_BUILD_TYPE must be set to one of the
standard types: Debug, RelWithDebInfo, MinSizeRel, or Release.
Halide provides several presets to make the above commands more convenient. The following CMake preset commands correspond to the longer ones above.
$ 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 / compilerHalide 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 macOS-vcpkg preset adds /opt/homebrew/opt/llvm to
CMAKE_PREFIX_PATH.
There are also presets to use some Clang sanitizers with the CMake build; at present, only Fuzzer and ASAN (Address Sanitizer) are supported, and only on linux-x86-64.
linux-x64-asan: Use the Address Sanitizerlinux-x64-fuzzer: Use the Clang fuzzer plugin
To use these, you must build LLVM with additional options:
-DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra"
-DLLVM_ENABLE_RUNTIMES="compiler-rt;libcxx;libcxxabi;libunwind"
Halide reads and understands several options that can configure the build. The following are the most consequential and control how Halide is actually compiled.
| Option | Default | Description |
|---|---|---|
BUILD_SHARED_LIBS |
ON |
Standard CMake variable that chooses whether to build as a static or shared library. |
Halide_BUNDLE_STATIC |
OFF |
When building Halide as a static library, merge static library dependencies into libHalide.a. |
Halide_LLVM_SHARED_LIBS |
OFF |
Link to the shared version of LLVM. Not available on Windows. |
Halide_ENABLE_RTTI |
inherited from LLVM | Enable RTTI when building Halide. Recommended to be set to ON |
Halide_ENABLE_EXCEPTIONS |
ON |
Enable exceptions when building Halide |
Halide_TARGET |
empty | The default target triple to use for add_halide_library (and the generator tests, by extension) |
WITH_AUTOSCHEDULERS |
ON |
Enable building the autoschedulers. Requires BUILD_SHARED_LIBS. |
WITH_SERIALIZATION |
ON |
Include experimental Serialization/Deserialization features |
The following options are disabled by default when building Halide through the
add_subdirectory
or FetchContent mechanisms. They control whether non-essential
targets (like tests and documentation) are built.
| Option | Default | Description |
|---|---|---|
WITH_DOCS |
OFF |
Enable building the documentation via Doxygen |
WITH_PACKAGING |
ON |
Include the install() rules for Halide. |
WITH_PYTHON_BINDINGS |
ON |
Enable building Python 3 bindings |
WITH_TESTS |
ON |
Enable building unit and integration tests |
WITH_TUTORIALS |
ON |
Enable building the tutorials |
WITH_UTILS |
ON |
Enable building various utilities including the trace visualizer |
The following options are advanced and should not be required in typical workflows. Generally, these are used by Halide's own CI infrastructure, or as escape hatches for third-party packagers.
| Option | Default | Description |
|---|---|---|
Halide_CLANG_TIDY_BUILD |
OFF |
Used internally to generate fake compile jobs for runtime files when running clang-tidy. |
Halide_CCACHE_BUILD |
OFF |
Use ccache with Halide-recommended settings to accelerate rebuilds. |
Halide_CCACHE_PARAMS |
CCACHE_CPP2=yes CCACHE_HASHDIR=yes CCACHE_SLOPPINESS=pch_defines |
Options to pass to ccache when using Halide_CCACHE_BUILD. |
Halide_VERSION_OVERRIDE |
${Halide_VERSION} |
Override the VERSION for libHalide. |
Halide_SOVERSION_OVERRIDE |
${Halide_VERSION_MAJOR} |
Override the SOVERSION for libHalide. Expects a positive integer (i.e. not a version). |
The following options control whether to build certain test subsets. They only
apply when WITH_TESTS=ON:
| Option | Default | Description |
|---|---|---|
WITH_TEST_AUTO_SCHEDULE |
ON |
enable the auto-scheduling tests |
WITH_TEST_CORRECTNESS |
ON |
enable the correctness tests |
WITH_TEST_ERROR |
ON |
enable the expected-error tests |
WITH_TEST_FUZZ |
detected | enable the libfuzzer-based fuzz tests |
WITH_TEST_GENERATOR |
ON |
enable the AOT generator tests |
WITH_TEST_PERFORMANCE |
ON |
enable performance testing |
WITH_TEST_RUNTIME |
ON |
enable testing the runtime modules |
WITH_TEST_WARNING |
ON |
enable the expected-warning tests |
The following option selects the execution engine for in-process WASM testing:
| Option | Default | Description |
|---|---|---|
Halide_WASM_BACKEND |
wabt |
Select the backend for WASM testing. Can be wabt, V8 or a false value such as OFF. |
Once built, Halide will need to be installed somewhere before using it in a
separate project. On any platform, this means running the
cmake --install command in one of two ways. For a
single-configuration generator (like Ninja), run either:
$ cmake --install ./build --prefix /path/to/Halide-install
$ cmake --install .\build --prefix X:\path\to\Halide-installFor a multi-configuration generator (like Visual Studio) run:
$ cmake --install ./build --prefix /path/to/Halide-install --config Release
$ cmake --install .\build --prefix X:\path\to\Halide-install --config ReleaseOf course, make sure that you build the corresponding config before attempting to install it.
Halide also supports installation via the standard Python packaging workflow.
Running pip install . at the root of the repository will build a wheel and
install it into the currently active Python environment.
However, this comes with a few caveats:
Halide_USE_FETCHCONTENTis disabled, so the environment must be prepared for CMake to find its dependencies. This is easiest to do by setting eitherCMAKE_PREFIX_PATHto pre-built dependencies or by settingCMAKE_TOOLCHAIN_FILEto vcpkg.- The build settings are fixed, meaning that
wabtis required on non-Windows systems,flatbuffersis always required, and the Python bindings must be built. - The generated wheel will likely only work on your system. In particular, it
will not be repaired with
auditwheelordelocate.
Even so, this is a very good method of installing Halide. It supports both
Python and C++ find_package workflows.