How to build the documentation from source code.

This document is about producing the Banjo API binaries. If you want to know how to build an application with banjo, see Using Banjo.

You will need at least a C99-compliant compiler.

Manual Build (No Build System)

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

1. Core Sources

Compile all .c files in src/ and src/unix/ (if on Unix) or src/win32/ (if on Windows). Do not compile files in backend-specific subdirectories (src/x11/, src/cocoa/, etc.) unless you are enabling that specific backend.

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

2. Output Type

Static Library: Define BANJO_STATIC.
Shared Library: Define BANJO_EXPORTS (do NOT define BANJO_STATIC).

Example: Building a Static Library (GCC/Clang)

# Compile core sources (excluding backends for this example)
gcc -c src/*.c src/unix/*.c -I inc/ -I src/ -D BANJO_STATIC
# (Note: This example assumes a Unix-like system. On Windows, use src/win32/*.c instead.
#  We are not including src/x11/*.c or src/alsa/*.c here.)
 
# Create archive
ar rcs libbanjo.a *.o

Build Options

You can customize the build by enabling backends or configuration options. To enable an option manually, you simply need to 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
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
Colored Logs	Enable support for colored log outputs
Log Checks	Failing checks are logged
Abort on Check	Failing checks call abort()
Pedantic Mode	Prioritize safety over performance
Fast Math	Enable fast-math optimizations

Win32 Backend

This backend enables support for creating windows on the Windows platform.

Additional source files: src/win32/video.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

This backend enables support for creating windows on Linux and Unix systems using the X11 display server.

Additional source files: src/x11/video.c

Compiler	Compiler Flags	Linker Flags
GCC/Clang	`-D` `BJ_CONFIG_X11_BACKEND`	`-lX11`

Cocoa Backend

This backend enables support for creating windows on macOS.

Additional source files: src/cocoa/video.m

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

CoreAudio Backend

This backend enables support for manipulating audio on macOS.

Compiler	Compiler Flags	Linker Flags
GCC/Clang	`-D` `BANJO_CONFIG_COREAUDIO_BACKEND`	`-framework` `AudioToolbox`

MME Backend

This backend enables audio support on Windows using the Multimedia Extensions API.

Additional source files: src/mme/audio.c

Compiler	Compiler Flags	Linker Flags
MSVC	`/D` `BJ_CONFIG_MME_BACKEND`	`winmm.lib`
GCC/Clang	`-D` `BJ_CONFIG_MME_BACKEND`	`-lwinmm`

ALSA Backend

This backend enables audio support on Linux using the Advanced Linux Sound Architecture (ALSA).

Additional source files: src/alsa/audio.c

Compiler	Compiler Flags	Linker Flags
GCC/Clang	`-D` `BJ_CONFIG_ALSA_BACKEND`	`-lasound`

Emscripten Backend

This backend enables support for WebAssembly builds using Emscripten.

Additional source files: src/emscripten/video.c and src/emscripten/audio.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`

Colored Logs

This option enables ANSI color codes in the log output, making it easier to distinguish between different log levels in your terminal.

Compiler	Compiler Flags
MSVC	`/D` `BJ_CONFIG_LOG_COLOR`
GCC/Clang	`-D` `BJ_CONFIG_LOG_COLOR`

Log Checks

This option ensures that when a check fails (as described in bj_check), an error message is logged to the standard output.

Compiler	Compiler Flags
MSVC	`/D` `BJ_CONFIG_CHECKS_LOG`
GCC/Clang	`-D` `BJ_CONFIG_CHECKS_LOG`

Abort on Check

This option causes the program execution to immediately abort when a check fails. This is useful for debugging critical errors.

Compiler	Compiler Flags
MSVC	`/D` `BJ_CONFIG_CHECKS_ABORT`
GCC/Clang	`-D` `BJ_CONFIG_CHECKS_ABORT`

Pedantic Mode

This option enables extra runtime checks throughout the API. These checks might be costly in terms of performance but ensure strict correctness and safety.

Compiler	Compiler Flags
MSVC	`/D` `BJ_CONFIG_PEDANTIC`
GCC/Clang	`-D` `BJ_CONFIG_PEDANTIC`

Fast Math

This option enables floating-point optimizations that may violate the IEEE 754 standard but can significantly improve performance for math-heavy applications.

Compiler	Compiler Flags
MSVC	`/D` `BJ_CONFIG_FASTMATH` `/fp`:fast
GCC/Clang	`-D` `BJ_CONFIG_FASTMATH` `-ffast-math` `-ffp-contract=fast` `-fno-math-errno` `-fno-trapping-math`

Build with CMake

Banjo provides a CMake configuration for convenience. It aims to work "out of the box" by automatically detecting available dependencies and enabling the corresponding backends.

Auto-Detection

CMake checks your system for libraries (X11, ALSA, etc.) and your platform (Windows, macOS). If a dependency is found, the corresponding backend is enabled by default.

CMake Options

Every manual option listed above has a corresponding CMake option. The naming convention is simple: replace the BJ_ prefix with BANJO_.

Example:

Manual Macro: BJ_CONFIG_X11_BACKEND
CMake Option: BANJO_CONFIG_X11_BACKEND

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

# Disable X11 even if libraries are present
cmake -B build -DBANJO_CONFIG_X11_BACKEND=OFF
 
# Enable Pedantic mode and Colored logs
cmake -B build -DBANJO_CONFIG_PEDANTIC=ON -DBANJO_CONFIG_LOG_COLOR=ON