Tutorial 02: Setting Up Your Dev Environment

CNA Tutorial Series  ·  Beginner

System Requirements

SDL3, SDL3_image, and SDL3_mixer are compiled from vendored submodules. You do not need to install them from your OS package manager.

Installing Dependencies

Ubuntu / Debian

sudo apt update
sudo apt install -y \
    build-essential \
    gcc-12 g++-12 \
    cmake \
    git \
    ninja-build \
    libgl1-mesa-dev \
    libgles2-mesa-dev \
    libasound2-dev \
    libpulse-dev \
    pkg-config

If GCC 12 is not the default on your system, set it explicitly:

sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100

Verify the C++23 support:

g++ --version          # should print gcc 12 or newer
g++ -std=c++23 -x c++ - <<< "int main(){}" && echo "C++23 OK"

Fedora / RHEL

sudo dnf install -y \
    gcc gcc-c++ \
    cmake \
    git \
    ninja-build \
    mesa-libGL-devel \
    mesa-libGLES-devel \
    alsa-lib-devel \
    pulseaudio-libs-devel \
    pkg-config

Arch Linux

sudo pacman -Syu base-devel cmake git ninja mesa

Windows (MSVC)

1. Install Visual Studio 2022 with the "Desktop development with C++" workload.
2. Install CMake 3.20+ and add it to PATH.
3. Install Git for Windows.

Open a "Developer Command Prompt for VS 2022" for all subsequent commands.

Cloning CNA and sharp-runtime

CNA requires the sharp-runtime repository to be cloned as a sibling directory. Both repositories must sit next to each other in the same parent folder:

mkdir my-cna-workspace
cd my-cna-workspace

# Clone sharp-runtime first (required dependency)
git clone https://github.com/openeggbert/sharp-runtime.git

# Clone CNA
git clone https://github.com/openeggbert/cna.git

# Initialize CNA's vendored submodules (SDL3, SDL3_image, SDL3_mixer)
cd cna
git submodule update --init --recursive

After this, your workspace should look like:

my-cna-workspace/
├── sharp-runtime/   ← C# primitive types for C++
└── cna/             ← the main CNA repository
    ├── include/
    ├── src/
    ├── tests/
    └── third_party/
        ├── SDL/
        ├── SDL_image/
        └── SDL_mixer/

If you also want the EasyGL backend (recommended for full 2D+3D support), clone it as well:

cd my-cna-workspace
git clone https://github.com/openeggbert/easy-gl.git

Building CNA

EasyGL backend (recommended)

From inside the cna/ directory:

cmake -S . -B build \
    -DCNA_GRAPHICS_BACKEND=EASYGL \
    -DCMAKE_BUILD_TYPE=Debug

cmake --build build --target CNA CnaTests -j$(nproc)

SDL_RENDERER backend (2D only, simplest)

cmake -S . -B build-sdl \
    -DCNA_GRAPHICS_BACKEND=SDL_RENDERER \
    -DCMAKE_BUILD_TYPE=Debug

cmake --build build-sdl --target CNA CnaTests -j$(nproc)

Release build

cmake -S . -B build-release \
    -DCNA_GRAPHICS_BACKEND=EASYGL \
    -DCMAKE_BUILD_TYPE=Release

cmake --build build-release --target CNA -j$(nproc)

Windows (MSVC Developer Prompt)

cmake -S . -B build -DCNA_GRAPHICS_BACKEND=EASYGL
cmake --build build --config Debug --target CNA CnaTests

CMake options reference

Running the Test Suite

CNA includes 4,373 GoogleTest unit tests covering math types, geometry, curves, packed vectors, game loop semantics, and more. After building the CnaTests target, run them with CTest:

# Run all tests
ctest --test-dir build --output-on-failure

# Run with verbose output
ctest --test-dir build -V

# Run a specific test by name pattern
ctest --test-dir build -R Vector2

# Run and show only failures
ctest --test-dir build --output-on-failure -Q

Expected output:

Test project /home/you/my-cna-workspace/cna/build
    Start 1: MathTests
1/8 Test #1: MathTests ....................   Passed    0.12 sec
    Start 2: ColorTests
2/8 Test #2: ColorTests ...................   Passed    0.04 sec
...
100% tests passed, 0 tests failed out of 4357

All 4,373 unit tests should pass. If any fail on a clean EasyGL build, please open an issue — the current unit test suite has no known pre-existing failures.

You can also run the test binary directly:

./build/CnaTests --gtest_filter="Vector*"

IDE Setup

VS Code

1. Install the C/C++ extension and the CMake Tools extension.
2. Open the cna/ folder in VS Code.
3. CMake Tools will detect CMakeLists.txt automatically. Select your kit (GCC 12 or Clang 15).
4. In the status bar, set the backend: click "No Configure Preset" and add a configure preset, or use the CMake Tools settings to pass -DCNA_GRAPHICS_BACKEND=EASYGL.
5. Press F7 to build, or click the build button in the status bar.

For IntelliSense to find CNA headers, CMake Tools generates a compile_commands.json automatically. If IntelliSense is confused, run "CMake: Configure" from the command palette.

CLion

1. Open the cna/ directory as a CLion project.
2. CLion auto-detects CMakeLists.txt. Go to Settings → Build, Execution, Deployment → CMake.
3. Add a CMake profile and set CMake options: -DCNA_GRAPHICS_BACKEND=EASYGL.
4. Choose the toolchain (GCC or Clang). Make sure it points to a C++23-capable version.
5. Build with Ctrl+F9.

CLion's indexer will pick up all CNA headers from the include/ directory automatically once the CMake project is configured.

Neovim / Emacs (compile_commands.json)

CNA's CMake build generates build/compile_commands.json. Point your LSP (clangd) at it:

# Generate compile_commands.json
cmake -S . -B build -DCNA_GRAPHICS_BACKEND=EASYGL -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# Symlink to project root for clangd
ln -s build/compile_commands.json compile_commands.json

clangd will then provide completion and diagnostics across all CNA headers.

With your environment set up and the tests passing, you are ready to write your first CNA game. Continue to Tutorial 03: Your First CNA Window.