Building Wolang

The compiler, the runtime and the libraries need clang and CMake 3.24+. Nothing else. LLVM is optional and only for wolang build.

Last updated Invalid DateVersion 1.0.0

The compiler, the runtime and the libraries need clang and CMake 3.24+. Nothing else. LLVM is optional and only for wolang build.

Why clang. The compiler uses clang's overflow builtins for the checked arithmetic every Wolang operator compiles to, __int128 for the wide multiply a constant divisor becomes, and statement expressions in the trap machinery. GCC has most of those and is untested; Microsoft's compiler has none of them, which is why the Windows build uses clang-cl (D184).

In one minute

Shell
git clone https://github.com/MowoGames/Wolang && cd Wolang
cmake --preset debug
cmake --build --preset debug -j
ctest --preset debug
build/debug/tools/wolang/wolang run examples/hello.wo

What each system needs

macOS

Apple's clang is fine, and it is what xcode-select installs.

Shell
xcode-select --install
brew install cmake ninja
# Optional, for `wolang build` and for cross-compiling:
brew install llvm

If CMake does not find LLVM, point it at the one Homebrew installed:

Shell
cmake --preset release -DLLVM_DIR="$(brew --prefix llvm)/lib/cmake/llvm"

Linux

Shell
sudo apt install clang lld cmake ninja-build        # Debian, Ubuntu
sudo dnf install clang lld cmake ninja-build        # Fedora
sudo pacman -S clang lld cmake ninja                # Arch

# Optional: the ahead-of-time backend, and a window
sudo apt install llvm-dev libx11-dev

If cc/c++ are GCC, say which compiler to use:

Shell
CC=clang CXX=clang++ cmake --preset debug

Windows

Install LLVM (it provides clang-cl), CMake and Ninja, then from a Developer Command Prompt — the Visual Studio C++ build tools provide the system headers and libraries that clang-cl uses:

PowerShell
cmake --preset windows
cmake --build --preset windows -j
ctest --preset windows

The windows preset selects clang-cl explicitly. Building with Microsoft's own compiler does not work and the configure step says so.

The ahead-of-time tier (wolang build) needs LLVM's C API, which the LLVM installer does not include. Fetch it once, then configure again:

PowerShell
python tools/package/fetch_llvm.py
cmake --preset windows

That puts LLVM 22.1.8's headers, LLVM-C.lib and LLVM-C.dll in build/llvm-sdk; the build copies the DLL next to wolang.exe. LLVM 23 miscompiles a remainder in a comparison (D208), so it is 22 on purpose.

The presets

PresetWhat it is for
debugEverything on, warnings are errors. What to develop against.
release-O2, no assertions. What to measure and ship.
asanAddress and undefined-behaviour sanitizers. Where memory bugs die.
ubsanUndefined-behaviour sanitizer alone, recovery off; cheaper than asan, run in CI.
windowsclang-cl, on Windows. A debug build.
windows-releaseclang-cl on Windows, optimized. What to time there.
windows-arm64clang-cl on a Windows ARM64 machine, told to compile for arm64. Checked in CI, informationally.
x64Cross-build to x86-64 on an arm64 machine, for the other back end.
Shell
cmake --preset asan && cmake --build --preset asan -j && ctest --preset asan

Options

OptionDefaultWhat it does
WOLANG_WITH_LLVMONThe ahead-of-time backend. Off builds without wolang build.
WOLANG_ALL_TARGETSONEmit code for every target LLVM has, so --target works. Off is this machine only, and a much smaller driver.
WOLANG_BUILD_TESTSONThe unit tests.
WOLANG_BUILD_TOOLSONThe wolang driver.
WOLANG_BUILD_PLATFORMONThe window, GPU and sound library.
WOLANG_WARNINGS_AS_ERRORSOFFOn in the debug preset.
WOLANG_ENABLE_SANITIZERSOFFOn in the asan preset.
WOLANG_REQUIRE_CLANGONThe check above. Off to try another compiler.
Shell
cmake --preset release -DWOLANG_ALL_TARGETS=OFF -DWOLANG_BUILD_TESTS=OFF

Checking the other back end without another machine

There are two machine-code back ends -- arm64 and x86-64 -- and a laptop runs one of them. On an Apple Silicon machine the x64 preset builds a real x86-64 binary, and Rosetta runs it:

Shell
cmake --preset x64 && cmake --build --preset x64 -j
./build/x64/tests/wolang_tests          # the whole suite, as x86-64
./build/x64/tools/wolang/wolang fuzz --seed 1 --count 150

This is worth doing after any change to a back end. The first time it was run, 94 tests into the suite the x86-64 build crashed, and seven real bugs were behind it (D195 to D198).

When something does crash there, the crash is in generated code and has no source line on it. What to do:

Shell
wolang asm --raw file.wo                # the bytes of each function, hex

Then hand those bytes to a disassembler -- llvm-mc --disassemble --arch=x86-64 takes 0x.. separated by spaces -- and compare what the two back ends emitted for the same program. The one that answers correctly is the specification.

Shell
# The same function from both, side by side.
wolang asm --raw probe.wo | sed -n '/@Probe:/,$p'

What gets built

Text
build/<preset>/
  tools/wolang/wolang          the driver: run, build, test, fmt, lsp...
  src/libwolang_core.a         the compiler
  src/libwolang_runtime.a      what a built binary links against
  src/libwolang_embed.a/.so    the embedding API
  platform/libwolang_platform.*  window, GPU and sound
  tests/wolang_tests           the unit tests

Running the tests

Shell
W=build/debug/tools/wolang/wolang

ctest --preset debug          # the compiler's own tests
$W test lib/std               # the standard library, in two tiers
$W test lib/http lib/db lib/gfx
$W fuzz --count 200           # the tiers against each other
$W fmt --check lib examples   # the formatter
python3 tools/package/check_docs.py   # every example in the docs

The fuzzer is the one that matters after a change to lowering, a back end or the runtime: it generates programs, runs them through all three tiers and compares.

Installing

Shell
cmake --install build/release --prefix /usr/local

That puts wolang in bin, the libraries in lib, the headers in include/wolang, and the standard library's sources where the driver looks for them. See install.md for the scripts that do this for you.

Building the editor extension

No npm needed:

Shell
python3 tools/package/make_vsix.py
code --install-extension build/wolang-1.3.0.vsix

Building programs with no C compiler

wolang build links its output with the system's own linker, c++, where there is one. On Linux a machine with no compiler, a minimal container for instance, can still build programs: unpack the sysroot for its architecture (wolang-sysroot-linux-x86_64.tar.gz or -arm64, from the release) into lib/wolang/sysroot of the installed compiler, or anywhere with WOLANG_SYSROOT pointing at it. With no c++ or cc on PATH, the build then links with the sysroot's own ld.lld, against musl, and writes a static executable that runs on any Linux of the same architecture. The same source and flags give the same bytes (D272).

WOLANG_LINKER=bundled uses the sysroot even where a compiler exists, which is how to check a reproducible build; WOLANG_LINKER=system never does. To build the sysroot yourself, run tools/package/make_sysroot.sh in an Alpine container; the script's header says how. macOS and Windows keep their own linker, which is always there.

The asan preset links the programs it builds with the sanitizers it was built with, so an AotTest there needs the sanitizer runtime on PATH on Windows (C:\Program Files\LLVM\lib\clang\<version>\lib\windows).

When something goes wrong

Wolang is built with clang, and this is GNU — set CC and CXX, as above.

no LLVM found — the build continues without wolang build. Install LLVM, or pass -DLLVM_DIR=....

ld: library 'LLVM-22' not found on macOS — CMake found LLVM's headers from one installation and its libraries from another. Pass -DLLVM_DIR="$(brew --prefix llvm)/lib/cmake/llvm".

Tests pass but wolang run traps in a package of yours — run it with --interpret. A difference between the two is a compiler bug and a good bug report (see CONTRIBUTING.md).

A window does not open on Linux — the platform library needs X11 headers at build time (libx11-dev); without them gfx.Available() answers false and everything else still works.

Page feedback

Was this page helpful?