Hazel Logo

Environment and Building

While Linux is in an experimental state, it is recommended that users build from the dev branch of the Hazel repo rather than a release branch; as patches are continuously applied in between releases which may not propogate to the release branch.

Hazel supports both native in-tree builds and Docker builds. The latter is the recommended format for end users not making active changes.

Contents

Docker Builds

1. Setup & Prerequisites

You will need the following tools to get started:

It's recommended that you get these from your system maintainers (e.g. via. a package manager or from user repositories) as they're more likely to be properly configured for your system out of the box.

Docker requires a Docker daemon to be running in order to perform builds and create containers. Information for starting and controlling this daemon can be found here.

Other dependencies will be fetched inside the container during the build process and copied out.

Finally, you should clone Hazel using git clone --recursive -b dev https://github.com/StudioCherno/Hazel. Simply downloading the branch archive from Github or using non-recursive clones will not work -- Hazel handles many dependencies as submodules.

2. Building

The Docker build has been encapsulated in scripts/Docker-Build.sh which invokes docker with the appropriate flags and copies out the resultant binaries (alongside any binaries required from dependencies).

The script does NOT support out of tree builds at present, and attempting to execute it outside of the Hazel root directory will likely create broken orphaned containers.

The script accepts passthrough flags to docker itself; these expose the following variables which can be set via. --build-arg VAR=value: | Name | Description | Default | | --- | --- | --- | | NPROC | Sets the build parallelism for make | 1 | | CXXFLAGS | Sets additional C++ compile flags | - | | BUILD_CONFIG | Sets build mode to Debug or Release | - |

The recommended invocation is:

scripts/Docker-Build.sh --build-arg NPROC=$(nproc) --build-arg CXXFLAGS=-Wno-everything

In order to make use of maximum parallelism and suppress all warnings.

This process is known to take a long time on initial builds. Having adequate parallelism set in the NPROC variable mitigates this factor but a fresh clone will still likely take several minutes.

After the script is done -- the Hazel binaries and required dependencies will have been copied out to bin. The Docker build also builds the Sandbox project for convenience, although the ScriptCore .dll is copied out to its appropriate location, so C# project builds can be performed outside of Docker as-usual.

3. Running

Before running Hazel tools from the Docker build -- you must set the following variables from the Hazel root directory:

export HAZEL_DIR=$(realpath .)
export VULKAN_SDK=$(realpath bin/x86_64)
export LD_LIBRARY_PATH=$(realpath bin/)

To run Hazelnut, use:

cd Hazelnut
../bin/Hazelnut [project]

If no project is specified in argv, the Sandbox project will be opened.

Native Builds

This section assumes some familiarity with native toolchains and interaction with GNU Make.

1. Setup & Prerequisites

You will need the following tools to get started:

It's recommended that you get these from your system maintainers (e.g. via. a package manager or from user repositories) as they're more likely to be properly configured for your system out of the box. Toolchains and associated libs/tooling are often provided as a "development" metapackage.

Supported/Tested build toolchain elements are listed below. Please note that this list is not exhaustive, as many aspects of build tooling are entailed as prerequisites to other tools. Additionally, whilst only glibc is tested at present, we are willing to maintain musl support if issues are submitted; otherwise, alternate C/C++ compilers/standard libraries other than those listed below will be unlikely to recieve official support. | Tool | Supported | Recommended | | --- | --- | --- | | C/C++ Compiler | GCC
Clang | Clang | | ar Archive Tool | GNU Binutils ar
LLVM llvm-ar | LLVM llvm-ar | | Linker | GNU Binutils ld
LLVM lld
Mold | Mold | | C++ Standard Library | GNU libstdc++
LLVM libc++ | - |

The following dependencies will also need to be installed in order to use Hazel:

You should then clone Hazel using git clone --recursive -b dev https://github.com/StudioCherno/Hazel. Simply downloading the branch archive from Github or using non-recursive clones will not work -- Hazel handles many dependencies as submodules.

When inside the Hazel root directory -- download the VulkanSDK and unpack/rename it such that the SDK root is as follows: Hazel/vendor/VulkanSDK/x86_64.

2. Building

The script build/Linux-Build.sh performs appropriate configure and build steps for native Hazel code, managed Coral/ScriptCore code and the Sandbox project. The build config can be modified by setting the BUILD_CONFIG variable to Debug or Release. The argv is passed through to the make invocation for Hazel native code -- this should be used to set build parallelism and toolchain opts. in accordance with regular Makefile practice (CXX, AR and LDLIBS etc.).

The resultant outputs are placed into bin/ in a subdirectory named based on the build config, platform and architecture.

3. Running

Before running Hazel tools -- you must set the following variables from the Hazel root directory:

export HAZEL_DIR=`realpath .`
export VULKAN_SDK=`realpath Hazel/vendor/VulkanSDK/x86_64`
export LD_LIBRARY_PATH="$VULKAN_SDK/lib:$HAZEL_DIR/Hazel/vendor/assimp/bin/linux:$HAZEL_DIR/Hazel/vendor/NvidiaAftermath/lib/x64/linux"

To run Hazelnut, use:

cd Hazelnut
../$BUILD_CONFIG-linux-$(uname -m)/Hazelnut [project]

If no project is specified in argv, the Sandbox project will be opened.