Build System

Creating a Project

New projects can be created using the new command. This generates a new directory that contains the basic structure of a Banjo project:

banjo new name

Building a Project

Projects can be built using the build command. This invokes the compiler and linker to generate the executable/library. The resulting binary can be found at out/<target>-<config>/<name>:

banjo build

To run an executable immediately after building, use the run command:

banjo run

Projects can be built with the debug (default) or release config:

banjo build --config debug
banjo build --config release

The release config enables compiler optimizations. These are still unstable and might lead to incorrect code generation or even compiler crashes.

The optimization level can be controlled using the --opt-level option:

banjo build --opt-level 1

The available optimization levels are:

  • --opt-level 0: No optimization except dead function elimination. The default for the debug config.

  • --opt-level 1: Enables basic optimizations such as peephole optimizations or inlining. The default for the release config.

  • --opt-level 2: Enables unstable optimizations that might produce incorrect code. Here be dragons.

Cross-Compilation

Note

Cross-compilation requires an installation of the LLD linker.

The build system is capable of cross-compiling for targets (platforms) other than the host target:

banjo build --target x86_64-linux-gnu
banjo build --target aarch64-macos

These targets currently support cross-compilation from other machines:

  • x86_64-windows-gnu

  • x86_64-linux-gnu

  • x86_64-macos

  • aarch64-linux-gnu

  • aarch64-macos

Notes

Cross-compilation has some limitations depending on the target operating system.

Windows
Cross-compilation is currently not possible for MSVC targets as this platform requires linking proprietary static libraries distributed by Microsoft. You can use the GNU targets instead (e.g. x86_64-windows-gnu). This automatically downloads the llvm-mingw toolchain.

Linux
When cross-compiling for Linux, precompiled versions of glibc and libgcc are downloaded to the toolchains directory. Some shared objects are missing from these libraries, which might cause linker errors.

macOS
When cross-compiling for macOS, a JSON file describing the macOS system APIs is downloaded. The build system then generates a sysroot containing TAPI files from this JSON file that the linker uses to link macOS system libraries and frameworks. The sysroot generated is incomplete and some frameworks cannot be linked for this reason.

Toolchains

The build system requires a toolchain to build projects. This includes an assembler, a linker and system libraries.

When building for a target, the build system tries to auto-detect toolchains based on standard paths, environment variables and the Windows registry. If a toolchain can’t be found (for example if you are cross-compiling), the build system tries to download it. If this also fails, the toolchain has to be added manually by running the toolchain add command and specifying the config parameters:

banjo toolchain add x86_64-windows-msvc
banjo toolchain add aarch64-macos

The stored toolchains can be listed using the toolchain list command:

banjo toolchain list