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)
FetchContent_Declare(
    banjo
    GIT_REPOSITORY https://forge.codework-orange.com/OragonEfreet/banjo.git
    GIT_TAG        v0.1.5         # pin a release tag (see Releases for the latest)
)
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. Both stable tags (e.g. v1.0.0) and pre-release tags (e.g. v1.0.0-alpha.1) are valid; pick the newest that suits you from the Releases page.

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 (not banjo::banjo).

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)

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: lib/libbanjo.a (or .so for shared builds)
• Public headers: include/banjo/*.h
• CMake configuration: lib/cmake/banjo/
• pkg-config file: lib/pkgconfig/banjo.pc

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

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 (X11 and/or ALSA enabled): nothing extra to link; backends are dlopen'd
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -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 GDI/user32/kernel32 libs
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -luser32 -lgdi32 -lkernel32 -o mygame

Banjo's optional Linux/Windows backends (X11, ALSA, MME) are loaded with dlopen / LoadLibrary at runtime: they have no link-time dependency, so you don't pass -lX11, -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.

Verifying your setup

A minimal test program:

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

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