- Generated by
1.12.0
|
Halide 19.0.0
Halide compiler and libraries
|
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 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| macOS | :x: | 10.10+ | 11.0+ (incl. universal2) |
| Linux (musl 1.1+) | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| 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:
Alternatively, you can use a normal virtual environment:
If 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:
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:
There are a few good ways to install CMake on Ubuntu:
sudo apt install cmake will install CMake 3.28.snap install cmake. Note this will conflict with an APT-provided CMake.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:
pipx install ninjawinget install Ninja-build.Ninjabrew install ninjaapt install ninja-buildYou 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:
To 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
from the root of the repository.
On macOS, it is possible to install all dependencies via Homebrew:
The llvm package includes clang, clang-format, and lld, too. To ensure CMake can find the keg-only dependencies, set the following:
On Ubuntu you should install the following packages (this includes the Python module dependencies):
When running the Python package, you will need to install additional dependencies. These are tabulated in requirements.txt and may be installed with:
These 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:
Then, assuming that vcpkg is installed to D:\vcpkg, simply run:
Valid 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:
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:
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:
If 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.
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 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 pluginTo use these, you must build LLVM with additional options:
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:
For a multi-configuration generator (like Visual Studio) run:
Of 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_FETCHCONTENT is disabled, so the environment must be prepared for CMake to find its dependencies. This is easiest to do by setting either CMAKE_PREFIX_PATH to pre-built dependencies or by setting CMAKE_TOOLCHAIN_FILE to vcpkg.wabt is required on non-Windows systems, flatbuffers is always required, and the Python bindings must be built.auditwheel or delocate.Even so, this is a very good method of installing Halide. It supports both Python and C++ find_package workflows.
1.12.0