Skip to main content

​
Overview

Cub3D can be built natively on Linux and macOS systems. The build process compiles SDL2 from source and sets up all necessary dependencies automatically.

​
Prerequisites

​
Required Tools

C Compiler

GCC or Clang compiler with C99 support

Build Tools

GNU Make and standard build utilities

ImageMagick

For font generation (optional: can use Docker fallback)

SDL2 Build Dependencies

System libraries for SDL2 compilation

​
Platform-Specific Dependencies

Install development packages for SDL2 compilation:
Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential libsdl2-dev libpthread-stubs0-dev
Fedora/RHEL
sudo dnf install gcc make SDL2-devel
Arch Linux
sudo pacman -S base-devel sdl2

​
Building the Project

​
Standard Build

The default build process handles all dependencies:
1

Clone the repository

git clone <repository-url>
cd cub3d
2

Run make

make
This command will:
  1. Extract and compile SDL2 from bundled source (lib/SDL2-2.32.8.tar.gz)
  2. Extract miniaudio header from lib/miniaudio.tar.gz
  3. Generate font assets from TTF files
  4. Decrypt and extract Wolf3D assets
  5. Compile all source files
  6. Link the final executable
3

Run the game

./cub3d maps/hub.cub

​
Build Output

Successful compilation produces:
  • cub3d - Main executable
  • obj/ - Compiled object files
  • lib/libSDL2.a - Static SDL2 library
  • headers/SDL2/ - SDL2 headers
  • headers/miniaudio.h - Audio library header
  • assets/fonts/ - Generated font bitmap files
  • assets/wolf3d/ - Decrypted game assets

​
Makefile Targets

​
Primary Targets

make
# or explicitly:
make all

​
Debugging Targets

make val
# Runs with memory leak detection and file descriptor tracking

​
Cleaning Targets

make clean
# Removes obj/ directory

​
Asset Targets

make fonts
# Regenerates font bitmaps from TTF files using ImageMagick

​
Compiler Flags

The build uses these compiler flags: 
CFLAGS = -Wall -Wextra -Werror -O3 -g
  • -Wall -Wextra -Werror: Strict warnings as errors
  • -O3: Maximum optimization
  • -g: Debug symbols
For address sanitizer debugging, uncomment the alternative CFLAGS line in the Makefile:
CFLAGS = -Wall -Wextra -Werror -O3 -g -std=c99 -fsanitize=address -fno-omit-frame-pointer

​
Platform Detection

The Makefile automatically detects your platform: 
UNAME_S = $(shell uname -s)
  • Darwin (macOS): Links Apple frameworks
  • Linux: Adjusts compiler warnings based on GCC vs Clang

​
Library Dependencies

​
SDL2

SDL2 is compiled from source (version 2.32.8) with: 
./configure --disable-shared --enable-static
make
This produces a static library that’s linked into the executable.

​
miniaudio

The miniaudio single-header library provides audio functionality:
  • Extracted from: lib/miniaudio.tar.gz
  • Placed in: headers/miniaudio.h

​
System Libraries

LDLIBS = -lSDL2 -ldl -lpthread
  • libSDL2: Graphics and input
  • libdl: Dynamic linking
  • libpthread: Threading support

​
Troubleshooting

Ensure you have development headers installed:
Linux
sudo apt-get install libx11-dev libxext-dev libxrandr-dev libxcursor-dev \
                     libxinerama-dev libxi-dev libxss-dev libxxf86vm-dev \
                     libasound2-dev libpulse-dev libudev-dev
On macOS, ensure Xcode Command Line Tools are installed:
xcode-select --install
The fonts.sh script requires ImageMagick. Install it:
Linux
sudo apt-get install imagemagick
macOS
brew install imagemagick
Or let the script use Docker as a fallback.
Make sure scripts have execute permissions:
chmod +x scripts/fonts.sh
If you see framework linking errors, update Xcode:
softwareupdate --install -a
xcode-select --install

​
Build Performance

First build takes longer (3-5 minutes) due to SDL2 compilation. Subsequent builds are much faster since SDL2 is cached.

​
Speeding Up Builds

The Makefile supports parallel compilation: 
make -j$(nproc)
Use make cdev instead of make clean dev to preserve compiled audio objects.

​
Next Steps

Creating Maps

Learn how to create custom .cub maps

Controls

Understand keyboard, mouse, and gamepad controls

Build docs developers (and LLMs) love

Get started for freeTalk to us