Skip to content

Building HAL

Jump to bottom
SJulianS edited this page May 21, 2024 · 30 revisions

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).

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 .. [OPTIONS] to run cmake
  5. make 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 here.

Specifying options for cmake is optional and only required to build tests, documentation, or specific plugins that are disabled by default (see below). We do currently not support building on any other Linux distribution.

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 required dependencies

The latter command will not only install all dependencies listed in the Brewfile file, but also build the igraph-0.9 library from source and hence may take some time. Ensure building HAL using a compiler that supports OpenMP (currently llvm@14). You may hide the llvm version number by creating a symbolic link.

  1. mkdir build && cd build to create and move to the build folder
  2. cmake -G Ninja .. -DQt5_DIR=/usr/local/opt/qt@5/lib/cmake -DPL_GUI=ON -DCMAKE_C_COMPILER=/usr/local/opt/llvm@14/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm@14/bin/clang++ run cmake explicitly pointing to compiler location
  3. ninja to compile HAL

Windows

You can try using HAL directly on Windows using an Ubuntu subsystem on WSL 2. After setting up WSL 2, follow the installation instructions for Ubuntu 22.04 and 24.04 provided above.

In the new WSL 2, you can make use of the new graphical features and HAL should work out of the box.

For WSL 1 follow the tips below:

WSL1 Troubleshooting

To work with the HAL GUI, you will need to set up an XServer. Install VcXsrv and run Xlaunch on your Windows machine. Now go to Ubuntu and start HAL with GUI support using the command below. Note that the command assumes the DISPLAY to be at located at localhost:0. This will need adjustment on your machine.

Start the XServer/Xlaunch and select One Large Window and set the box Disable Access Control.

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

You might also run in some firewall issues, have a look at this stackoverflow discussion. You can always install an Ubuntu VM.

CMake Options

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

  • 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
  • PL_<plugin name>: enable (or disable) building a specific plugin
  • BUILD_ALL_PLUGINS: all-in-one option to build all available plugins, overrides the options for individual plugins
  • SANITIZE_ADDRESS, SANITIZE_MEMORY, SANITIZE_THREAD, SANITIZE_UNDEFINED : builds with the respective sanitizers (recommended only for debug builds)
  • ABC_PATH: optionally provide your 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.

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.
Clone this wiki locally