Skip to content

Building and Toolchain

Jump to bottom
Renan Bomtempo edited this page Sep 24, 2026 · 5 revisions

⚠️ This wiki is under construction. Pages are being populated incrementally.

Building and Toolchain

This page is the technical reference for building Nodens. For the shortest onboarding path, see Getting Started or start from the Nodens Application Template.

Supported Build Boundary

The current development and validation environment is Linux-based. The repository's devcontainer uses Arch Linux and is the recommended way to obtain the project toolchain. Native Linux builds are possible when equivalent packages are installed.

Native Windows and macOS builds are not currently supported or validated.

Toolchain Requirements

The project currently requires:

Component Requirement or guidance
Operating system Linux for the supported and validated workflow
CMake 3.30 or newer, as required by the top-level CMakeLists.txt
Language C++23 with standard library module support
Compiler Clang is used by the development container; other compilers are not currently validated
Build generator Ninja is recommended for C++ module dependency scanning
Doxygen Optional; required only for the nodens-docs target

The shared Linux graphics development image is maintained in the EldritchCodex/Devcontainers repository. Its Arch package list is in linux-graphics/scripts/install-packages.sh, and the pinned Slang compiler installation is in linux-graphics/scripts/install-slang.sh. On another Linux distribution, install equivalent packages using that distribution's package manager.

Rebuilding the Shared Development Image Locally

Application projects use one published image:

ghcr.io/eldritchcodex/arch-dev:main

The image owns the full toolchain. GPU runtime arguments and NVIDIA capabilities are configured in each project's devcontainer.json. Nodens and Template-NodensApp use NVIDIA runtime arguments by default and document Intel/AMD alternatives. Each project uses a unique Docker container name to avoid local name collisions.

NVIDIA Container Toolkit

NVIDIA GPU support requires three host-side components:

  1. A working NVIDIA driver.
  2. Docker or another supported container engine.
  3. NVIDIA Container Toolkit configured for that container engine.

The development image does not contain NVIDIA kernel drivers. Install the NVIDIA driver on the host machine first, then verify it:

nvidia-smi

The NVIDIA Container Toolkit connects Docker to the host NVIDIA driver. When a container requests --gpus=all, the toolkit injects NVIDIA GPU devices and compatible userspace driver libraries into the container. Nodens also sets NVIDIA_DRIVER_CAPABILITIES=graphics,display,utility to request graphics, display, and utility capabilities. This setting does not install a driver.

On Arch Linux, install the toolkit from the official Extra repository:

sudo pacman -Syu
sudo pacman -S nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Install the host NVIDIA driver separately with the package appropriate for the GPU and kernel. On Ubuntu, Debian, Fedora, and other supported distributions, follow the NVIDIA Container Toolkit installation guide for distribution-specific repository and package instructions.

Test Docker GPU access before opening the Dev Container:

docker run --rm --gpus=all nvidia/cuda:12.9.0-base-ubuntu22.04 nvidia-smi

Intel/AMD hosts do not need NVIDIA Container Toolkit. Use the /dev/dri, video, and render runArgs block instead of the NVIDIA block. Keep exactly one GPU configuration active.

To test changes locally, clone the Devcontainers repository and build generic image first:

docker build --pull \
    -f linux-graphics/Dockerfile \
    -t ghcr.io/eldritchcodex/arch-dev:main \
    linux-graphics

Rebuild or reopen the project Dev Container after changing the image.

Configuring and Building Nodens

From the Nodens repository root, preferably in the active devcontainer:

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

When Nodens is the top-level project, the example applications are enabled by default. To build only the framework target, use:

cmake --build build --target Nodens

The first configuration may download dependencies and therefore requires network access. If the build directory contains stale CMake or module metadata, remove it and configure again:

rm -rf build
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Build Types and Options

The project defines the following build types and options:

Setting Default Description
CMAKE_BUILD_TYPE=Debug Depends on the generator Enables the ND_DEBUG compile definition for Debug builds.
CMAKE_BUILD_TYPE=Release Depends on the generator Enables the ND_RELEASE compile definition for Release builds.
CMAKE_BUILD_TYPE=Profiling Depends on the generator Enables ND_RELEASE and Tracy instrumentation. See Profiling with Tracy.
ND_ENABLE_OPENGL ON Builds the OpenGL backend.
ND_ENABLE_VULKAN ON Builds the Vulkan backend when Vulkan is available.
ND_BUILD_EXAMPLES ON when Nodens is top-level; OFF when consumed Controls whether the example applications are added.
ND_BUILD_TRACY_PROFILER OFF Builds the Tracy Profiler GUI from the vendored Tracy source as the tracy-profiler target.

For a Release build:

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

Profiling Build

The Profiling configuration mirrors Release code generation and adds only what the profiler needs: debug symbols (-g) and frame pointers (-fno-omit-frame-pointer). Tracy instrumentation is compiled in for this configuration only, so Debug and Release builds are unchanged.

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Profiling \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

To also build the profiler GUI from the vendored Tracy source, add -DND_BUILD_TRACY_PROFILER=ON and build the tracy-profiler target:

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Profiling \
    -DND_BUILD_TRACY_PROFILER=ON
cmake --build build --target tracy-profiler

The profiler GUI is a separate CMake project that vendors its own dependencies, so it is built through ExternalProject and excluded from the default build. See Profiling with Tracy for instrumentation and capture details.

When Nodens is consumed through FetchContent or add_subdirectory, PROJECT_IS_TOP_LEVEL is false and the examples default to off. This prevents a consuming application from unexpectedly building Nodens' examples.

C++ Modules and CMake

Nodens uses C++ module interfaces (.cppm) and implementation units (.cpp). The top-level build enables CMake's module-related features:

  • CMAKE_CXX_STANDARD is set to 23.
  • CMAKE_CXX_MODULE_STD is enabled.
  • CMAKE_CXX_COMPILER_IMPORT_STD is enabled.
  • Public module interfaces are registered through a FILE_SET with TYPE CXX_MODULES.
  • CMAKE_EXPERIMENTAL_CXX_IMPORT_STD is set to the identifier expected by the project's CMake configuration.

The experimental import std; support depends on compatible CMake, compiler, and standard-library versions. Do not change the experimental identifier casually; update it only when deliberately updating the supported CMake toolchain.

When Nodens is consumed through FetchContent or add_subdirectory, the consuming project's CMakeLists.txt must set CMAKE_EXPERIMENTAL_CXX_IMPORT_STD before its project(... LANGUAGES CXX) call. Nodens cannot enable this toolchain feature after the parent project has already enabled C++.

Ninja is the recommended generator because C++ modules require the build system to understand compilation dependencies between module interfaces, implementation units, and importers.

Dependency Resolution

Dependency declarations are centralized in cmake/NodensDependencies.cmake. The current source revisions are:

Dependency Revision
spdlog v1.17.0
GLFW 3.4
Tracy v0.14.1
ImGui v1.92.9b-docking
ImPlot v1.0
ImPlot3D v0.4

CMake may download and build these dependencies during configuration. ImGui, ImPlot, and ImPlot3D are built from source by the project's CMake files because they do not provide the packaging model used by Nodens.

Nodens does not currently provide an installable or exported CMake package. Consumers should use FetchContent or a local add_subdirectory checkout, as described in Getting Started.

Building on a Native Linux Host

The devcontainer is recommended because it defines the tested environment. A native Linux build can use the same CMake commands after installing equivalent packages.

The shared image's Arch Linux package list is maintained in the Devcontainers repository. The script uses pacman and is intended to run inside the Arch-based image; it is a reference for package names rather than a universal installer.

After installing the equivalent packages, configure and build from the Nodens repository root:

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

Generating API Documentation

Doxygen is optional during configuration. The nodens-docs target is created only when CMake finds Doxygen:

cmake --build build --target nodens-docs

Generated documentation is written under build/docs/ according to Doxyfile.in.

Troubleshooting

CMake cannot find a compatible compiler or standard library

Use the devcontainer first. If building natively, verify that the compiler supports the C++23 module features enabled by the project and that CMake is at least version 3.30.

Module dependency or BMI errors

Use Ninja and remove the build directory before reconfiguring:

rm -rf build
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Configuration cannot download dependencies

The first configuration requires network access because dependencies may be fetched from their upstream repositories. Check network access from inside the devcontainer and inspect the CMake error for the dependency that failed to populate.

The application unexpectedly builds Nodens examples

When Nodens is consumed as a subproject, examples default to off. If they are enabled explicitly, configure with:

cmake -S . -B build -G Ninja -DND_BUILD_EXAMPLES=OFF

The documentation target does not exist

Install Doxygen and reconfigure the build. The target is only defined when find_package(Doxygen QUIET) succeeds.

See Also

Home

Getting Started

Architecture

Guides

Reference

API Reference (Doxygen) · GitHub Repository

Clone this wiki locally