Building from Source

Building Atlas Engine from source gives you access to the latest features and allows you to contribute to the project. This guide covers the complete build process for all supported platforms.

Why Build from Source?

Access cutting-edge features before official releases
Customize the engine for your specific needs
Contribute improvements and bug fixes
Debug engine internals
Create custom builds with specific backend configurations

Prerequisites

Before building, ensure you have all required tools and dependencies installed as described in the Installation Guide.

Quick Checklist

Linux
macOS
Windows

# Verify prerequisites
cmake --version        # Should be 3.15+
g++ --version          # Should support C++20
python3 --version      # Required for shader packing

# Check libraries
pkg-config --modversion glfw3 glm freetype2 assimp openal vulkan

# Verify prerequisites
cmake --version
clang++ --version
python3 --version

# Check Homebrew packages
brew list | grep -E '(glfw|glm|freetype|assimp|openal)'

# Verify prerequisites
cmake --version
cl          # MSVC compiler
python --version

# Vcpkg should be installed and configured

Cloning the Repository

Clone Atlas Engine

Clone the repository from GitHub:

git clone https://github.com/maxvdec/atlas.git
cd atlas

Check the Current Branch

The main branch contains stable releases. For development:

# View available branches
git branch -a

# Switch to development branch (if desired)
git checkout develop

Atlas Engine uses Git submodules for some dependencies. CMake’s FetchContent will handle most dependencies automatically.

Build Configuration

Basic Build

The simplest build process:

mkdir build
cd build
cmake ..
make

On Windows with Visual Studio:

mkdir build
cd build
cmake -G "Visual Studio 17 2022" ..
cmake --build . --config Release

Selecting a Rendering Backend

Atlas Engine supports multiple rendering backends. Choose one during configuration:

cmake -DBACKEND=AUTO ..
# Windows/Linux: Uses Vulkan
# macOS: Uses Metal

The Metal backend is only available on macOS. Attempting to build with Metal on other platforms will fail with a CMake error.

Build Types

Control optimization and debug information:

# Debug build (default if not specified)
cmake -DCMAKE_BUILD_TYPE=Debug ..

# Release build (optimized)
cmake -DCMAKE_BUILD_TYPE=Release ..

# Release with debug info
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

Advanced Options

Atlas Engine provides several build options:

# Use native Bezel physics (experimental)
cmake -DBEZEL_NATIVE=ON ..

# Specify a custom backend
cmake -DBACKEND=VULKAN ..

# Combine multiple options
cmake -DCMAKE_BUILD_TYPE=Release -DBACKEND=VULKAN ..

Complete Build Process

Here’s the full step-by-step process:

Create Build Directory

mkdir build
cd build

Keep build files separate from source for easier cleanup.

Configure with CMake

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBACKEND=AUTO

CMake will:

Detect your compiler and platform
Download Jolt Physics (v5.5.0) via FetchContent
Find system dependencies
Pack shaders into header files
Generate build files

Build the Engine

Linux/macOS

make -j$(nproc)

Windows

cmake --build . --config Release --parallel

This compiles:

bezel - Physics library
finewave - Audio library
opal - Rendering abstraction
aurora - Terrain system
hydra - Environment system
atlas - Main engine library
atlas_test - Test executable

Run the Test Suite

./bin/atlas_test

On Windows:

.\bin\Release\atlas_test.exe

This launches the test application to verify the build.

Build Output

After building, you’ll find:

build/
├── bin/
│   └── atlas_test           # Test executable
├── lib/
│   ├── libatlas.a          # Main engine library
│   ├── libbezel.a          # Physics library
│   ├── libfinewave.a       # Audio library
│   ├── libopal.a           # Rendering library
│   ├── libaurora.a         # Terrain library
│   └── libhydra.a          # Environment library
└── docs/                    # Generated documentation (if Typst available)

Platform-Specific Notes

Linux

Compiler Selection

# Use GCC
export CC=gcc
export CXX=g++
cmake ..

# Use Clang
export CC=clang
export CXX=clang++
cmake ..

Parallel Builds

# Use all available cores
make -j$(nproc)

# Limit to 4 cores
make -j4

Vulkan Issues

If Vulkan SDK is not found:

export VULKAN_SDK=/path/to/vulkan/sdk
cmake ..

macOS

Xcode Command Line Tools

Ensure Xcode Command Line Tools are installed:

xcode-select --install

Homebrew Dependencies

Atlas Engine expects dependencies in Homebrew’s default locations:

# For Intel Macs
/usr/local/opt/

# For Apple Silicon Macs
/opt/homebrew/opt/

CMake automatically checks both locations.

Metal Backend

The Metal backend is default on macOS and links Metal frameworks automatically:

cmake -DBACKEND=METAL ..
make

MoltenVK for Vulkan

To use Vulkan on macOS, install the Vulkan SDK which includes MoltenVK:

brew install --cask vulkan-sdk
brew install spirv-cross
cmake -DBACKEND=VULKAN ..

Windows

Visual Studio

Use Visual Studio 2019 or later:

cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release

Vcpkg Integration

If using vcpkg for dependencies:

cmake -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..

MSVC Compiler Warnings

Atlas Engine enables /W4 warnings and treats them as errors. To build successfully, ensure:

Visual Studio is up to date
Windows SDK is installed
No deprecated API usage

Shader Compilation

Atlas Engine packs shaders at build time using a Python script:

# Shader source locations
shaders/
├── opengl/     # GLSL shaders
├── vulkan/     # SPIR-V compiled from GLSL
└── metal/      # Metal Shading Language

Shaders are compiled and embedded into include/atlas/core/default_shaders.h.

For Vulkan, the build process uses glslc (from Vulkan SDK) to compile GLSL to SPIR-V. Ensure the Vulkan SDK is in your PATH.

Optional: Documentation Generation

If you have Typst installed, Atlas Engine can generate documentation PDFs:

# Install Typst
curl -fsSL https://typst.app/install.sh | sh

# CMake will automatically detect and build documentation
cmake ..
make typst_docs

# Output in build/docs/

Troubleshooting Build Issues

Jolt Physics Download Fails

Atlas Engine downloads Jolt Physics 5.5.0 via CMake’s FetchContent. If download fails:

# Clear CMake cache and retry
rm -rf CMakeCache.txt CMakeFiles
cmake ..

Or manually clone Jolt:

git clone --depth 1 --branch v5.5.0 https://github.com/jrouwe/JoltPhysics.git external/jolt

Shader Packing Errors

Shader packing requires Python 3:

# Verify Python
python3 --version

# Check shader directories exist
ls -la shaders/opengl/
ls -la shaders/vulkan/
ls -la shaders/metal/

For Vulkan, ensure glslc is available:

glslc --version

Linker Errors

If you see undefined symbols during linking:

# Clean and rebuild
make clean
make -j$(nproc)

Check that all dependencies are properly installed:

# Linux
pkg-config --libs glfw3 glm freetype2 assimp openal

# macOS
brew list | grep -E '(glfw|glm|freetype|assimp|openal)'

C++20 Compiler Errors

Atlas Engine requires C++20. Update your compiler:

# Linux: GCC 10+
sudo apt-get install g++-10
export CXX=g++-10

# macOS: Update Xcode
softwareupdate --install -a
xcode-select --install

Installing the Build

To install Atlas Engine system-wide:

sudo make install

By default, this installs to:

Linux/macOS: /usr/local/
Windows: C:\Program Files\Atlas\

To customize the installation prefix:

cmake -DCMAKE_INSTALL_PREFIX=/opt/atlas ..
make install

Development Workflow

For active development:

Use Debug Builds

cmake -DCMAKE_BUILD_TYPE=Debug ..

Debug builds include symbols and disable optimizations for easier debugging.

Enable Verbose Output

make VERBOSE=1

See exact compiler commands for troubleshooting.

Incremental Builds

After making changes:

make -j$(nproc)

CMake tracks dependencies and only rebuilds changed files.

Run Tests

./bin/atlas_test

Test your changes with the included test application.

Contributing

If you’re building from source to contribute:

Read the Contributing Guide
Follow the Code of Conduct
Check open issues
Join the Discord community

Next Steps

Now that you’ve built Atlas Engine from source:

Follow the Quickstart Guide to create your first application
Explore the test application source in test/main.cpp
Read the API reference documentation
Experiment with different rendering backends

Quickstart

Create your first Atlas application

API Reference

Explore the complete API documentation

Examples

Study example projects and demos

Community

Join the Atlas Engine Discord server

Getting Started

Core Concepts

Rendering

Physics (Bezel)

Audio (Finewave)

Environment

Advanced

CLI Tools

​Building from Source

​Why Build from Source?

​Prerequisites

​Quick Checklist

​Cloning the Repository

​Build Configuration

​Basic Build

​Selecting a Rendering Backend

​Build Types

​Advanced Options

​Complete Build Process

​Build Output

​Platform-Specific Notes

​Compiler Selection

​Parallel Builds

​Vulkan Issues

​Xcode Command Line Tools

​Homebrew Dependencies

​Metal Backend

​MoltenVK for Vulkan

​Visual Studio

​Vcpkg Integration

​MSVC Compiler Warnings

​Shader Compilation

​Optional: Documentation Generation

​Troubleshooting Build Issues

​Installing the Build

​Development Workflow

​Contributing

​Next Steps

Quickstart

API Reference

Examples

Community

Build docs developers (and LLMs) love

Building from Source

Why Build from Source?

Prerequisites

Quick Checklist

Cloning the Repository

Build Configuration

Basic Build

Selecting a Rendering Backend

Build Types

Advanced Options

Complete Build Process

Build Output

Platform-Specific Notes

Compiler Selection

Parallel Builds

Vulkan Issues

Xcode Command Line Tools

Homebrew Dependencies

Metal Backend

MoltenVK for Vulkan

Visual Studio

Vcpkg Integration

MSVC Compiler Warnings

Shader Compilation

Optional: Documentation Generation

Troubleshooting Build Issues

Installing the Build

Development Workflow

Contributing

Next Steps