Skip to content
Hylo

Building the Compiler

The Hylo compiler is written in Swift, links against LLVM 23, and can be built using the Swift Package Manager.

Environment setup can be challenging, so here is some emotional support:

A yellow clay duck with a Hylo hoodie.

If something doesn’t work, feel free to ask on Slack or report an issue!

Environment Setup

Section titled “Environment Setup”

You can either set up the environment manually, or use a devcontainer (recommended).

Option 1: Devcontainer

Section titled “Option 1: Devcontainer”

A development container allows us to use a pre-built Docker image, hylo-dev-toolchain as our development environment. To use it, we need a container Runtime such as Docker. Using VSCode has the best devcontainer integration, but others may also work.

Set up Docker

Section titled “Set up Docker”

Cloning the repository

Section titled “Cloning the repository”
 
git clone https://github.com/hylo-lang/hylo-new
cd hylo-new
git submodule update --init

Open the container in VSCode

Section titled “Open the container in VSCode”

  1. Install the Dev Containers extension.

  2. Open the hylo-new folder, then run Dev Containers: Reopen in Container from the command palette.

  3. Build the compiler from the integrated terminal, which is now running inside the container:

    swift build

Congrats, you are now ready to go! Skip to Build and test.

Bonus: Opening the container from the command line

Section titled “Bonus: Opening the container from the command line”

If you use a terminal based code editor, you can edit the sources locally, and perform building and testing using the devcontainer CLI:

npm install -g @devcontainers/cli


devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . swift build
devcontainer exec --workspace-folder . swift test
devcontainer down --workspace-folder . # warning: removes the container

Bonus: Building against the Debug LLVM

Section titled “Bonus: Building against the Debug LLVM”

By default, the container uses MinSizeRel LLVM. If you need to debug some LLVM internals, you can make the container use the Debug image version by setting the environment variable HYLO_LLVM_BUILD_TYPE to Debug:

export HYLO_LLVM_BUILD_TYPE=Debug

Option 2: Manual Installation

Section titled “Option 2: Manual Installation”

  1. Install Swift 6.3.2 or newer, using swiftly, Swift’s toolchain installer.

  2. Install pkg-config, which Swift Package Manager uses to find LLVM.

    sudo apt install pkg-config

  3. Download Hylo’s latest LLVM build from the llvm-build releases page and extract it somewhere permanent.

    We build LLVM for x64 and arm64, requiring glibc 2.39+ (Ubuntu 24.04+). If your platform is not among these, you will need to acquire an LLVM 23 distribution that works for you, and generate llvm.pc using our scripts.

  4. Tell pkg-config where to locate LLVM. The archive contains a pkgconfig subdirectory holding llvm.pc, which must be exposed on PKG_CONFIG_PATH:

    export PKG_CONFIG_PATH="<LLVM>/pkgconfig:$PKG_CONFIG_PATH"

    Confirm it resolves:

    pkg-config --modversion llvm

Build and test

Section titled “Build and test”
swift build  # build in debug mode, without tests
swift test  # build and run tests in debug mode
swift test -c release  # build and run tests in release mode
swift test --parallel  # build and run tests in parallel

Compiler Tests

Section titled “Compiler Tests”

A large part of our test suite is generated from hylo programs at Tests/CompilerTests/{positive,negative}/*.hylo. See instructions in the Compiler Testing Guide.

Building for cross-compilation

Section titled “Building for cross-compilation”

By default, a custom-built hc can only generate code for the machine it is running on. To build a cross-capable version, supply the SWIFTY_LLVM_CROSS_COMPILATION_ENABLED flag (already set in official releases):

swift build -c release -Xswiftc -DSWIFTY_LLVM_CROSS_COMPILATION_ENABLED

If everything works, welcome on board!

Contributing Guide
Good first issues
Coding Conventions
Compiler Architecture