Configure your project to compile against Banjo API.

This document describes how to integrate Banjo into your project. If you want to know how to build Banjo itself, see Building the API.

Integration with CMake

Banjo provides comprehensive CMake support with three integration methods. For most projects, FetchContent is the recommended approach due to its simplicity and reproducibility.

Method 1: Fetch at Configure Time (FetchContent)

This is the quickest and easiest way to get started with Banjo. CMake automatically downloads Banjo during configuration, making it ideal for new projects, open-source development, and continuous integration environments where dependencies should be reproducible.

Use in Your Project

In your CMakeLists.txt:

cmake_minimum_required(VERSION 3.21)
project(MyGame C)
 
include(FetchContent)
 
# Declare the Banjo dependency
FetchContent_Declare(
    banjo
    GIT_REPOSITORY https://github.com/yourname/banjo.git
    GIT_TAG        v0.1.0  # Use a specific tag or commit hash
)
FetchContent_MakeAvailable(banjo)
 
add_executable(mygame main.c)
 
target_link_libraries(mygame PRIVATE banjo)

Advantages:

No manual installation or submodule management required
Reproducible builds with version pinning (GIT_TAG)
CMake handles downloading and caching automatically
Ready to use in seconds

Note: FetchContent requires an internet connection during the first configuration.

Method 2: Source Subdirectory (add_subdirectory)

This method embeds Banjo directly into your project's source tree. It is useful for tightly coupled projects or when you need fine-grained control over Banjo's build configuration.

Step 1: Add Banjo to Your Project

# Option A: Git submodule
git submodule add https://github.com/yourname/banjo.git external/banjo
 
# Option B: Copy the source directly
cp -r /path/to/banjo external/banjo

Step 2: Use in Your Project

In your CMakeLists.txt:

cmake_minimum_required(VERSION 3.21)
project(MyGame C)
 
# Add Banjo as a subdirectory
add_subdirectory(external/banjo)
 
add_executable(mygame main.c)
 
# Link against the Banjo target
target_link_libraries(mygame PRIVATE banjo)

Step 3: Configure Build Options (Optional)

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

# Disable examples and tests
set(BANJO_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
 
# Configure specific backends
set(BANJO_CONFIG_X11_BACKEND ON CACHE BOOL "" FORCE)
set(BANJO_CONFIG_PEDANTIC OFF CACHE BOOL "" FORCE)
 
add_subdirectory(external/banjo)

Note: When using add_subdirectory(), link against the banjo target (not banjo::banjo).

Method 3: Installed Library (find_package)

This method is appropriate when Banjo has been installed system-wide or to a specific prefix. It is the recommended approach for production deployments and packaged distributions.

Step 1: Install Banjo

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

Step 2: Use in Your Project

In your CMakeLists.txt:

cmake_minimum_required(VERSION 3.21)
project(MyGame C)
 
# Find the installed Banjo package
find_package(banjo REQUIRED)
 
add_executable(mygame main.c)
 
# Link against the installed library
target_link_libraries(mygame PRIVATE banjo::banjo)

Step 3: Configure Your Project

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

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

cmake --build build

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

Backend Selection

Regardless of which integration method you use, Banjo automatically enables platform-appropriate backends. However, you may want to explicitly control backend selection:

# Force specific backends (when using add_subdirectory or FetchContent)
set(BANJO_CONFIG_COCOA_BACKEND ON CACHE BOOL "" FORCE)
set(BANJO_CONFIG_X11_BACKEND OFF CACHE BOOL "" FORCE)
 
# Or when using find_package, configure backends during Banjo's installation
cmake -B build \
    -DBANJO_CONFIG_COCOA_BACKEND=ON \
    -DBANJO_CONFIG_X11_BACKEND=OFF
cmake --install build

See Build with CMake for a complete list of available CMake options.

Integration with pkg-config

For non-CMake build systems, Banjo provides a pkg-config file.

Prerequisites: Banjo must be installed (see Method 3: Installed Library (find_package)).

Usage:

# Compile and link in one step
gcc main.c $(pkg-config --cflags --libs banjo) -o mygame
 
# Or separately
gcc -c main.c $(pkg-config --cflags banjo)
gcc main.o $(pkg-config --libs banjo) -o mygame

Makefile Example:

CC = gcc
CFLAGS = $(shell pkg-config --cflags banjo)
LDFLAGS = $(shell pkg-config --libs banjo)
 
mygame: main.o
    $(CC) main.o $(LDFLAGS) -o mygame
 
main.o: main.c
    $(CC) -c main.c $(CFLAGS)

If Banjo is 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, you can link against Banjo manually.

Prerequisites:

Banjo must be built (see Manual Build (No Build System))
You must have the compiled library (libbanjo.a or libbanjo.so)

Compile Your Application:

# Link against static library
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -o mygame
 
# Add additional libraries based on enabled backends
# For X11:
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -lX11 -o mygame
 
# For Cocoa (macOS):
gcc main.c -I/path/to/banjo/inc -L/path/to/banjo -lbanjo -lm -framework Cocoa -o mygame

Include Paths:

Add -I/path/to/banjo/inc to access public headers

Library Paths:

Add -L/path/to/banjo to locate libbanjo.a
Always link with -lm (math library) on Unix-like systems

Backend Dependencies: Depending on which backends were enabled during Banjo's build, you must link additional platform libraries. See Build Options for the complete list of backend linker flags.

Verifying Integration

After integrating Banjo, verify your setup with a minimal test program:

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

If compilation succeeds, your integration is configured correctly.

For a functional example with window creation and rendering, see the examples/ directory in the Banjo source tree.