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

Add Banjo to your project via CMake, pkg-config, or hand-rolled compiler flags.

Prerequisites

If you integrate Banjo through FetchContent or add_subdirectory, your build is going to compile Banjo as part of your project, so it needs the same system development headers Banjo itself needs (see Prerequisites).

If you integrate via find_package against a pre-installed Banjo, your build does not recompile Banjo; only Banjo's runtime requirements apply.

CMake, Method 1: FetchContent

Quickest and easiest. CMake automatically downloads Banjo during configuration. Ideal for new projects, OSS development, and CI where dependencies should be reproducible.

cmake_minimum_required(VERSION 3.21)
project(MyGame C)
include(FetchContent)
# Pin a release tag (see Releases for the latest)
FetchContent_Declare(
banjo
GIT_REPOSITORY https://forge.codework-orange.com/OragonEfreet/banjo.git
GIT_TAG v1.1.0-alpha
)
FetchContent_MakeAvailable(banjo)
add_executable(mygame main.c)
target_link_libraries(mygame PRIVATE banjo)

Requires an internet connection during the first configuration.

Pin GIT_TAG to a release tag rather than a branch so your build is reproducible: main tracks unreleased development and can shift under you. Stable releases are tagged vX.Y.Z, such as v1.0.0; pick the newest from the Releases page. The pre-releases published there, such as v1.0.0-rc.3, are tagged too, to try a version before it is stable.

CMake, Method 2: add_subdirectory

Embeds Banjo directly into your project's source tree. Useful for tightly coupled projects or when you need fine-grained control over Banjo's build configuration.

add_subdirectory(external/banjo)
add_executable(mygame main.c)
target_link_libraries(mygame PRIVATE banjo)

You can control Banjo's configuration from your parent project:

set(BANJO_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
set(BANJO_CONFIG_X11_BACKEND ON CACHE BOOL "" FORCE)
add_subdirectory(external/banjo)

When using add_subdirectory, link against the banjo target, or banjo::banjo, which names the same library. banjo::static or banjo::shared also exists, matching the flavour BUILD_SHARED_LIBS selected.

CMake, Method 3: find_package

Appropriate when Banjo has been installed system-wide or to a specific prefix. Recommended for production deployments and packaged distributions.

Install Banjo first:

cd /path/to/banjo
cmake -B build && cmake --build build
cmake --install build --prefix /usr/local

Then in your project:

find_package(banjo REQUIRED)
add_executable(mygame main.c)
target_link_libraries(mygame PRIVATE banjo::banjo)

An installation can hold both library flavours (see Building Banjo). banjo::banjo follows your project's BUILD_SHARED_LIBS: the static library when it is OFF, the shared one when it is ON or unset, falling back to the other flavour when that one is not installed. Link banjo::static or banjo::shared to pick one explicitly:

target_link_libraries(mygame PRIVATE banjo::static)

If Banjo was installed to a non-standard prefix, specify CMAKE_PREFIX_PATH:

cmake -B build -DCMAKE_PREFIX_PATH=/custom/install/prefix

What gets installed:

  • Library files:
    • static builds: lib/libbanjo.a (lib/banjo-static.lib with MSVC)
    • shared builds: lib/libbanjo.so linking to libbanjo.so.<major> (the soname) and the fully versioned libbanjo.so.<major>.<minor>.<patch>; libbanjo.<major>.dylib on macOS; bin/banjo.dll with its import library lib/banjo.lib (MSVC) or lib/libbanjo.dll.a (MinGW) on Windows
  • Public headers: include/banjo/*.h
  • CMake configuration: lib/cmake/banjo/
  • pkg-config files: lib/pkgconfig/banjo.pc, plus banjo-static.pc from a static build

pkg-config

For non-CMake build systems, Banjo provides a pkg-config file (requires installation first).

gcc main.c $(pkg-config --cflags --libs banjo) -o mygame

banjo links -lbanjo, which picks the shared library when one is installed. To link the static library, use banjo-static: it names the archive itself, even when the shared library sits next to it, adds the system libraries it needs (frameworks on macOS; ws2_32, user32, gdi32 on Windows), and defines BANJO_STATIC:

gcc main.c $(pkg-config --cflags --libs banjo-static) -o mygame

If installed to a non-standard prefix:

export PKG_CONFIG_PATH=/custom/install/prefix/lib/pkgconfig
gcc main.c $(pkg-config --cflags --libs banjo) -o mygame

Manual integration

If you prefer not to use a build system, link against Banjo manually (after building it via Building Banjo):

# Linux: -pthread for the fake backend's audio thread; X11, Wayland and ALSA are dlopen'd
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -pthread -o mygame
# macOS (Cocoa + CoreAudio): re-list the frameworks at the final link line
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -framework Cocoa -framework AudioToolbox -o mygame
# Windows (Win32 backend, MinGW): re-list the Winsock, GDI, user32 and kernel32 libs
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lws2_32 -luser32 -lgdi32 -lkernel32 -o mygame

Banjo's optional Linux/Windows backends (X11, Wayland, ALSA, MME) are loaded with dlopen / LoadLibrary at runtime: they have no link-time dependency, so you don't pass -lX11, -lwayland-client, -lasound, or -lwinmm. Backends that do need link-time symbols (Win32, Cocoa, CoreAudio, Emscripten) must be re-listed at your application's link line when using the static libbanjo.a, as must ws2_32 on Windows and, on glibc older than 2.34, -ldl.

Verifying your setup

A minimal test program:

#include <banjo/api.h>
#include <stdio.h>
int main(void) {
printf("Hello Banjo!\n");
return 0;
}
General-purpose definitions for Banjo API.
int main(void)

If this compiles and links, your integration is configured correctly. For a functional example with window creation and rendering, see the Examples topic and the example file start.c.

See also
Prerequisites, Building Banjo, Examples