Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Building Banjo

Produce the Banjo library binaries from source, with or without CMake.

Banjo is not distributed as a package: there's no apt install banjo or equivalent. You either build from source (see below) or grab a pre-built release artifact from the Releases page. Either way the runtime side of every optional backend is dlopen'd, so a binary built on one machine can run on another that has the corresponding system shared object installed.

Prerequisites

You need at least a C99-compliant compiler. Beyond that, Banjo's CMake auto-detects platform backends (window system, audio) and enables each one whose development headers are present at build time. To get a working out-of-the-box build, install the headers up-front.

Debian / Ubuntu / Mint:

sudo apt install libx11-dev libwayland-dev libxkbcommon-dev libasound2-dev

Fedora / RHEL:

sudo dnf install libX11-devel wayland-devel libxkbcommon-devel alsa-lib-devel

Arch:

sudo pacman -S libx11 wayland libxkbcommon alsa-lib

macOS: no extra install. Cocoa and CoreAudio ship with Xcode / the Command Line Tools (xcode-select --install).

Windows: no extra install. Win32 and MME ship with the Windows SDK (MSVC) or the MinGW-w64 toolchain.

Emscripten: install the emsdk toolchain (https://emscripten.org/docs/getting_started/downloads.html).

Per-backend / per-distro breakdown

Banjo's optional backends are loaded at runtime with dlopen so the resulting libbanjo has no link-time dependency on them. However, each backend still needs the matching development headers at build time to compile its source. CMake auto-detects these: if the headers are missing, that backend is simply not built (and BANJO_CONFIG_*_BACKEND defaults to OFF).

Backend Debian / Ubuntu / Mint Fedora / RHEL Arch
X11 libx11-dev libX11-devel libx11
Wayland libwayland-dev + libxkbcommon-dev wayland-devel + libxkbcommon-devel wayland + libxkbcommon
ALSA libasound2-dev alsa-lib-devel alsa-lib

At runtime, the dynamic loader must be able to find the shared object matching whatever backend was enabled (libX11.so.6, libwayland-client.so.0, libxkbcommon.so.0, libasound.so.2, etc.). On a desktop Linux distribution these are present whenever the corresponding subsystem is in use, so this typically requires no extra action.

Manual build (no build system)

Banjo is designed to be built without any complex build system. You only need to feed your compiler with the source files and the correct include paths.

Compile all .c files in src/, plus those of src/posix/ on Unix, or net_win32.c, system_win32.c and time_win32.c of src/win32/ on Windows. Do not compile a backend's own source files, listed per backend under "Build options" below, unless you are enabling that backend. Enable at least the fake backend, as the examples below do, so that video and audio always have a backend to start.

Add inc/ and src/ to your include search path.

Output type:

  • Static library: define BANJO_STATIC.
  • Shared library: define BANJO_EXPORTS (do NOT define BANJO_STATIC). With GCC or Clang, also pass -fvisibility=hidden so that only the public API (the functions declared with BANJO_EXPORT) is exported.

Example (GCC/Clang static library):

gcc -c src/*.c src/posix/*.c src/fake/*.c -I inc/ -I src/ \
-D BANJO_STATIC -D BJ_CONFIG_FAKE_BACKEND
ar rcs libbanjo.a *.o

Example (GCC/Clang shared library):

gcc -shared -fPIC -fvisibility=hidden src/*.c src/posix/*.c src/fake/*.c \
-I inc/ -I src/ -D BANJO_EXPORTS -D BJ_CONFIG_FAKE_BACKEND \
-lm -pthread -o libbanjo.so

On glibc older than 2.34, also link -ldl, which dlopen needs. On Windows, the networking functions need ws2_32 (-lws2_32, or ws2_32.lib with MSVC).

See "Build options" below for the per-backend / per-option list of macros and linker flags.

Build with CMake

Banjo provides a CMake configuration that aims to work out-of-the-box: CMake checks your system for libraries (X11, ALSA, …) and your platform (Windows, macOS), and enables matching backends by default.

Every manual option below has a corresponding CMake option. The naming convention is simple: replace the BJ_ prefix with BANJO_. For example the manual macro BJ_CONFIG_X11_BACKEND becomes the CMake option BANJO_CONFIG_X11_BACKEND.

You can force options ON or OFF to override auto-detection:

cmake -B build -DBANJO_CONFIG_X11_BACKEND=OFF
cmake -B build -DBANJO_CONFIG_PEDANTIC=ON -DBANJO_CONFIG_LOG_COLOR=ON

Code linking against Banjo through CMake also receives these BJ_CONFIG_* macros. This is deprecated: no public header uses them, pkg-config and manual builds never provided them, and 2.0 stops passing them on. To find out at runtime how the loaded library was configured, call bj_build_information(), or bj_video_backends() and bj_audio_backends() for the backends.

CMake presets

A CMakePresets.json is shipped at the project root with the configurations used by Banjo's CI/CD pipeline. Using a preset is optional (the manual cmake commands above work the same) but presets give you a shortcut to the exact build CI runs, handy for reproducing failures locally.

Preset Description
linux-linux-gcc Linux x86_64 release build with GCC, the X11, Wayland and ALSA backends, and the examples
linux-windows-mingw Windows x86_64 release build cross-compiled on Linux with mingw-w64, the Win32 and MME backends, and the examples

Both presets leave the tests out (BUILD_TESTING=OFF). CI turns them on from the command line, and so can you; only linux-linux-gcc has a test preset:

cmake --preset linux-linux-gcc -DBUILD_TESTING=ON # configure
cmake --build --preset linux-linux-gcc # build
ctest --preset linux-linux-gcc # run tests

Build artifacts land under build/<preset>/, such as build/linux-linux-gcc/, to keep each preset's output apart.

Static vs shared library

Banjo can be built and consumed as either a static or a shared library. The build type is set by CMake options and communicated to producing and consuming code through C macro definitions (in inc/banjo/api.h):

  • BANJO_STATIC is set when building and using a static library; it entirely disables the other macros.
  • BANJO_EXPORTS is set when building (but not using) a dynamic library.
  • BANJO_EXPORT and BANJO_NO_EXPORT expand to compiler-specific attributes for exporting/importing symbols through binary compatibility. On Windows, BANJO_EXPORT is __declspec(dllexport) while building the DLL; consumers get __declspec(dllimport) with MSVC, and no attribute with GCC-based toolchains (MinGW), which do not need one to call DLL functions.

When using CMake you don't set these directly; CMake derives them from BUILD_SHARED_LIBS. The default (unset) is a static library.

The library target is banjo, also reachable as banjo::banjo and, depending on the flavour, banjo::static or banjo::shared: the names find_package() provides (see Using Banjo).

Shipping both flavours

One build tree produces one flavour. To ship both, as a package or an SDK usually does, build twice and install both builds into the same prefix:

cmake -B build-static -DBUILD_SHARED_LIBS=OFF && cmake --build build-static
cmake -B build-shared -DBUILD_SHARED_LIBS=ON && cmake --build build-shared
cmake --install build-static --prefix /path/to/package
cmake --install build-shared --prefix /path/to/package

The installed files do not overlap: each flavour has its own library files and its own CMake targets file, and find_package(banjo) then provides both banjo::static and banjo::shared. With MSVC, where a static library and a DLL import library are both .lib files, the static library is named banjo-static.lib for that reason.

Do not mix flavours inside one program: Banjo keeps process-wide state (memory callbacks, log settings, the event queue, initialized systems), and each copy of the library has its own.

Build options

You can customize the build by enabling backends or configuration options. To enable an option manually, define the corresponding C macro and compile any required additional sources.

Option Name Description
Win32 backend Enable Win32 window support
X11 backend Enable X11 window support
Wayland backend Enable Wayland window support (Linux)
Cocoa backend Enable Cocoa/macOS support
MME backend Enable Windows Multimedia Extensions audio
ALSA backend Enable ALSA audio support
CoreAudio backend Enable CoreAudio support
Emscripten backend Enable Emscripten/WebAssembly support
Fake backend Always-available no-op fallback (default ON)
Coloured logs Enable ANSI coloured log output
Log Checks Failing checks are logged
Abort on Check Deprecated, no effect (removed in 2.0)
Pedantic Mode Prioritise safety over performance
Fast Math Enable fast-math optimisations

Per-backend / per-option details:

Win32 backend

Additional source files: src/win32/video_win32.c

Compiler Compiler Flags Linker Flags
MSVC /D BJ_CONFIG_WIN32_BACKEND user32.lib gdi32.lib kernel32.lib
GCC/Clang -D BJ_CONFIG_WIN32_BACKEND -luser32 -lgdi32 -lkernel32

X11 backend

Additional source files: src/x11/video_x11.c

Compiler Compiler Flags Linker Flags
GCC/Clang -D BJ_CONFIG_X11_BACKEND (none, dlopen'd at runtime)

Banjo loads libX11.so.6 with dlopen, so libbanjo has no link-time dependency on libX11. The X11 development headers are needed at build time only (see Prerequisites), and libX11.so.6 must be discoverable by the dynamic loader on the target machine. On glibc < 2.34, add -ldl when linking the final executable.

Wayland backend

Additional source files: src/wayland/video_wayland.c, src/wayland/wayland-protocol.c, src/wayland/xdg-shell-protocol.c

Compiler Compiler Flags Linker Flags
GCC/Clang -D BJ_CONFIG_WAYLAND_BACKEND (none, dlopen'd at runtime)

Banjo loads libwayland-client.so.0 and libxkbcommon.so.0 with dlopen, so libbanjo has no link-time dependency on either. The Wayland and xkbcommon development headers are needed at build time only (see Prerequisites), and both shared objects must be discoverable by the dynamic loader on the target machine. The Wayland protocol glue (core wayland and xdg-shell) is vendored into the project as pre-generated wayland-scanner output, so neither wayland-scanner nor wayland-protocols is needed at build time. On glibc < 2.34, add -ldl when linking the final executable.

Cocoa backend

Additional source files: src/cocoa/video_cocoa.m

Compiler Compiler Flags Linker Flags
GCC/Clang -D BJ_CONFIG_COCOA_BACKEND -framework Cocoa

Cocoa ships with every macOS install.

CoreAudio backend

Additional source files: src/coreaudio/audio_coreaudio.c

Compiler Compiler Flags Linker Flags
GCC/Clang -D BJ_CONFIG_COREAUDIO_BACKEND -framework AudioToolbox

MME backend

Additional source files: src/mme/audio_mme.c

Compiler Compiler Flags Linker Flags
MSVC /D BJ_CONFIG_MME_BACKEND (none, loaded at runtime)
GCC/Clang -D BJ_CONFIG_MME_BACKEND (none, loaded at runtime)

Banjo calls LoadLibrary("winmm.dll") at runtime and resolves waveOut* entry points dynamically, so there is no link-time dependency on winmm. winmm.dll ships with Windows.

ALSA backend

Additional source files: src/alsa/audio_alsa.c

Compiler Compiler Flags Linker Flags
GCC/Clang -D BJ_CONFIG_ALSA_BACKEND (none, dlopen'd at runtime)

Banjo loads libasound.so.2 with dlopen, so libbanjo has no link-time dependency on libasound. The ALSA development headers are needed at build time only, and libasound.so.2 must be discoverable by the dynamic loader on the target machine.

Emscripten backend

Additional source files: src/emscripten/video_emscripten.c and src/emscripten/audio_emscripten.c

Compiler Compiler Flags Linker Flags
Emscripten -D BJ_CONFIG_EMSCRIPTEN_BACKEND ‘-sEXPORTED_RUNTIME_METHODS=['ccall’,'cwrap','_malloc','_free'] -sEXPORTED_FUNCTIONS=['_bj_emscripten_audio_process'] -sALLOW_MEMORY_GROWTH`

Fake backend

The always-available no-op fallback. Implements the full video and audio vtables with in-memory bitmaps and silence, so initialisation cannot fail even on a headless host with no display server or sound card. Its audio device runs a playback thread that calls the device callback at the pace of the sample rate, as the native backends do. Enabled by default; leaving it on is recommended.

Additional source files: src/fake/video_fake.c and src/fake/audio_fake.c

Compiler Compiler Flags Linker Flags
Any -D BJ_CONFIG_FAKE_BACKEND -pthread on POSIX systems

Logging, checks, and math

Macro Effect
BJ_CONFIG_LOG_COLOR Enable ANSI colour codes in log output
BJ_CONFIG_CHECKS_LOG A failing bj_check logs an error message
BJ_CONFIG_CHECKS_ABORT Deprecated, no effect: a failing check returns, as documented
BJ_CONFIG_PEDANTIC Enable extra runtime checks (slower, stricter)
BJ_CONFIG_FASTMATH Enable floating-point optimisations that may violate IEEE 754

For fast math, GCC/Clang also need -ffast-math -ffp-contract=fast -fno-math-errno -fno-trapping-math; MSVC needs /fp:fast.

Precision of bj_real

bj_real, the floating-point type of the math, vector, matrix and physics functions, is float unless one of these macros is defined:

Macro bj_real CMake
(none) float -DBANJO_REAL_PRECISION=float (default)
BJ_API_FLOAT64 double -DBANJO_REAL_PRECISION=double
BJ_API_LONG_DOUBLE long double -DBANJO_REAL_PRECISION=long_double

Unlike the BJ_CONFIG_* macros, these are read by inc/banjo/math.h, so a program must define the same one as the library it links, or the two disagree on the type of every bj_real they exchange. CMake passes it on to the programs linking Banjo through CMake, and the pkg-config files carry it; with a manual build, define it for your program too. bj_build_information() reports the library's sizeof(bj_real) as real_size, which a program can compare with its own.

Troubleshooting (build)

CMake says "X11 backend: OFF" on a box that has X11. The runtime library (libx11-6) is installed but the development headers are not. Install libx11-dev (or your distro's equivalent, see Prerequisites).

cmake --build asks for Ninja. You're using a preset that selects Ninja, or you passed -G Ninja. Banjo's presets pin Unix Makefiles. Use the shipped presets or pass -G "Unix Makefiles" explicitly.

clang-tidy fails with cert-err33-c. A return value is being silently discarded. Fold the return into your control flow rather than suppressing with (void): see the Error Management topic for the recipe.

Test binary reports "Potential leaks detected". The test harness's mock_allocators counts every bj_malloc / bj_free and fails the suite if the totals don't match. Look at the most recent TEST_CASE for a missing bj_destroy_* / bj_clear_error / matching bj_free.

See also
Using Banjo