Building HAL

HAL officially supports (and is tested for) Ubuntu 22.04 and 24.04 only, but you are free to add support for other platforms. We also offer experimental support for macOS as well as Windows (via WSL 2).

There are no pre-built binaries — HAL must be built from source.

Before you start: only a subset of HAL's plugins is built by default, and several of the ones used throughout this wiki and by the example projects are opt-in. Unless you have a reason not to, build with -DBUILD_ALL_PLUGINS=ON so that everything is available. See Provided Plugins for what exists and CMake Options below for how to select it.

Build instructions

Ubuntu 22.04 and 24.04

If you want to build HAL on Ubuntu 22.04 or 24.04, run the following commands:

1. git clone https://github.com/emsec/hal.git && cd hal to clone the Git repository
2. ./install_dependencies.sh to install all required dependencies
3. mkdir build && cd build to create and move to the build folder
4. cmake .. -DBUILD_ALL_PLUGINS=ON to run cmake
5. make -j$(nproc) to compile HAL
6. from within the build folder, run ./bin/hal -g to launch HAL in GUI mode. For details on starting HAL, see Starting HAL.

The first build takes a while, since HAL builds several bundled dependencies (such as ABC and igraph) from source. Subsequent builds are much faster.

Important: We do currently not support building on any other Linux distribution. We will not provide support for building HAL on any other platforms.

macOS

Warning: Building on macOS is experimental and may not always work.

All essential tools and dependencies for the HAL build must be installed via Homebrew, so please make sure it is available on your system. Also make sure that you have git installed (brew install git).

1. git clone https://github.com/emsec/hal.git && cd hal to clone the Git repository
2. ./install_dependencies.sh to install all dependencies listed in the Brewfile as well as the Python packages from requirements.txt
3. mkdir build && cd build to create and move to the build folder
4. configure and build:

export PATH="$(brew --prefix qt@5)/bin:$PATH"
export LDFLAGS="-L$(brew --prefix qt@5)/lib -Wl,-rpath,$(brew --prefix llvm)/lib"
export SDKROOT=$(xcrun --show-sdk-path)
cmake -G Ninja .. -DQt5_DIR="$(brew --prefix qt@5)/lib/cmake" -DPL_GUI=ON -DBUILD_ALL_PLUGINS=ON
ninja

The commands above mirror what our macOS CI runs, so they are the most reliable starting point. A few things to be aware of:

• HAL must currently be built against Qt5, not Qt6. Since the location where brew installs its packages varies between Intel and Apple Silicon machines, using the $(brew --prefix ...) syntax is strongly recommended over hardcoded paths.
• HAL needs a compiler with OpenMP support. If the default toolchain gives you OpenMP-related errors, point CMake at the Homebrew LLVM explicitly by additionally passing -DCMAKE_C_COMPILER=$(brew --prefix llvm)/bin/clang -DCMAKE_CXX_COMPILER=$(brew --prefix llvm)/bin/clang++.
• On Apple Silicon, see Notes on ABC below.

Windows

There is no native Windows build of HAL. Instead, run it inside an Ubuntu installation on the Windows Subsystem for Linux (WSL). In both cases below, HAL itself is built exactly as described under Ubuntu 22.04 and 24.04 — only the setup around it differs.

WSL 2 (recommended)

WSL 2 ships with built-in support for Linux GUI applications, so the HAL GUI works without any additional configuration.

1. Set up WSL 2 with Ubuntu 22.04 or 24.04. You can check which version an existing installation uses by running wsl -l -v in PowerShell; the VERSION column must read 2.
2. Inside the Ubuntu shell, follow the Ubuntu build instructions above.
3. Start HAL with ./bin/hal -g. The window should appear on your Windows desktop like any other application.

If the GUI does not come up, your Windows installation may predate the built-in graphics support. In that case, set up an X server as described for WSL 1 below.

WSL 1 (legacy)

WSL 1 has no graphics support of its own, so the HAL GUI needs an X server running on the Windows side.

1. Install an X server. Download and install VcXsrv on your Windows machine.

2. Start it. Run XLaunch, select One Large Window, and tick Disable Access Control. Leave the X server running.

3. Point HAL at it. In the Ubuntu shell, export the two variables below and launch HAL. The DISPLAY value is derived from the nameserver entry in /etc/resolv.conf, which is where WSL records the address of the Windows host:

   export LIBGL_ALWAYS_INDIRECT=1
   export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0
   ./bin/hal -g

   On some setups the host is instead reachable as localhost. If the command above fails to connect, try export DISPLAY=localhost:0 before launching.

Add the two export lines to your ~/.bashrc if you do not want to repeat them in every session.

Troubleshooting

• The GUI does not appear and HAL reports that it cannot open the display. The Windows firewall commonly blocks the X server. See this Stack Overflow discussion for how to allow it through.
• Nothing works and you are out of patience. Upgrading the installation to WSL 2 removes the need for an X server entirely. Running Ubuntu in a virtual machine is another way out.

Verifying your build

From within the build folder:

• ./bin/hal -v prints the HAL version and confirms that the executable works.
• ./bin/hal -h lists all available command line options. Plugins contribute their own options here, so this is also a quick way to check which plugins were built.
• If you configured with -DBUILD_TESTS=ON, run ctest in the build directory to execute the test suite.

HAL's built-in gate libraries are copied into build/share/hal/gate_libraries and are picked up automatically from there.

CMake options

Using the CMake build system, your HAL build can be configured quite easily (by adding -D<OPTION>=ON to the cmake command). Here is a selection of the most important options:

• BUILD_ALL_PLUGINS: all-in-one option to build all available plugins, overrides the options for individual plugins. Recommended, in particular if you want to follow the example projects.
• PL_<PLUGIN NAME>: enable (or disable) building a specific plugin. Provided Plugins lists the flag for each one.
• BUILD_TESTS: builds all available tests which can be executed by running ctest in the build directory. This also builds all tests of plugins that are built.
• BUILD_DOCUMENTATION: build the C++ and Python documentation
• SANITIZE_ADDRESS, SANITIZE_MEMORY, SANITIZE_THREAD, SANITIZE_UNDEFINED: builds with the respective sanitizers (recommended only for debug builds)
• ABC_PATH: optionally provide the path to the shared library of Berkeley ABC to avoid re-building it all the time, see Notes on ABC.

If you do not specify CMAKE_BUILD_TYPE, it defaults to Release. Supported build types are Debug, Release, RelWithDebInfo, MinSizeRel, and Perf.

Which plugins are built by default?

Roughly half of them. Provided Plugins lists every plugin with its individual CMake flag and whether it is built by default.

If a plugin you expect is missing from the Plugin Manager inside the GUI, it most likely was not built.

Troubleshooting

Notes on ABC (mandatory on M1 Macs)

To speed up the build process, you may install ABC at a location of your choice and provide the path to CMake or put in a standard path like (/usr/local/lib/). Important: To ensure correct execution of ABC from within HAL, we had to modify some buffer sizes because Boolean functions generated in HAL can be quite large. Hence, make sure to adjust the buffer in abc/src/base/ver/verStream.c as shown below:

-#define VER_BUFFER_SIZE          1048576
-#define VER_OFFSET_SIZE            65536 
-#define VER_WORD_SIZE              65536
+#define VER_BUFFER_SIZE        104857600 
+#define VER_OFFSET_SIZE          6553600
+#define VER_WORD_SIZE            6553600

We also adjusted the file abc/src/base/abc/abcFunc.c as follows:

-#define ABC_MAX_CUBES   100000
+#define ABC_MAX_CUBES   2000000

Installation instructions:

cd deps/abc
make ABC_USE_PIC=1 libabc.so
sudo cp libabc.so /usr/local/lib/

(See abc troubleshooting on failure)

pybind11

CMake Error in src/python_bindings/CMakeLists.txt:
  Imported target "pybind11::module" includes non-existent path
    "/include"
  in its INTERFACE_INCLUDE_DIRECTORIES.  Possible reasons include:
  * The path was deleted, renamed, or moved to another location.
  * An install or uninstall procedure did not complete successfully.
  * The installation package was faulty and references files it does not
  provide.

Try the following:

• Make sure you have the most recent pybind11-dev version installed.
• -DCMAKE_PREFIX_PATH=<root_of_pybind> can be provided as additional flag to cmake. For some reason this variable sometimes remains empty in the pybind11 CMakeLists and results in faulty paths.

A plugin is missing in the GUI

Check whether it is one of the opt-in plugins listed above and reconfigure with -DBUILD_ALL_PLUGINS=ON. Some plugins additionally need to be activated in the Plugin Manager (main menu > Utilities > Plugin Manager), which requires a restart of HAL.

Still stuck?

Please open an issue and include your operating system, the exact cmake command you used, and the error output. See Reporting Bugs.

See also

• Starting HAL — running what you just built
• Provided Plugins — the plugins behind the build flags, and which are on by default
• Plugin Management — activating plugins once HAL is running
• Reporting Bugs — when the build fails in a way this page does not cover