Building¶

This guide covers building VulkanW3DViewer from source.

Quick Build¶

The fastest way to build is using the provided build scripts:

Windows (PowerShell)Linux/macOS

.\scripts\rebuild.ps1 release

./scripts/rebuild.sh release

# If permission denied:
chmod +x scripts/rebuild.sh
./scripts/rebuild.sh release

Build Presets¶

The project uses CMake presets for different build configurations:

Preset	Description	Output Directory
`debug`	Debug build with symbols, no optimization	`build/debug/`
`release`	Optimized release build	`build/release/`
`test`	Debug build with testing enabled	`build/test/`

Manual Build¶

If you prefer manual control over the build process:

Configure¶

# Debug build
cmake --preset debug

# Release build
cmake --preset release

# Test build
cmake --preset test

Build¶

# Build debug
cmake --build --preset debug

# Build release
cmake --build --preset release

# Build tests
cmake --build --preset test

Run¶

# Windows
./build/release/VulkanW3DViewer.exe

# Linux/macOS
./build/release/VulkanW3DViewer

Running Tests¶

Build and run the test suite:

# Configure and build tests
cmake --preset test
cmake --build --preset test

# Run tests
ctest --preset test

Parallel Test Execution

Speed up testing with parallel execution:

ctest --preset test -j $(nproc)

Build Options¶

Compiler Flags¶

The project uses strict compiler settings:

-Werror - Treat warnings as errors
-Wall -Wextra - Enable comprehensive warnings
-std=c++20 - C++20 standard

Shader Compilation¶

Shaders are automatically compiled to SPIR-V during the build process using glslc from the Vulkan SDK. The compiled shaders are embedded into the executable.

Troubleshooting¶

Common Issues¶

Vulkan SDK not found

Ensure the VULKAN_SDK environment variable is set:

# Check if set
echo $VULKAN_SDK

# Set manually (example path)
export VULKAN_SDK=/path/to/VulkanSDK/1.3.xxx/x86_64

Submodules not initialized

Initialize submodules if dependencies are missing:

git submodule update --init --recursive

Permission denied on build scripts

Make scripts executable:

chmod +x scripts/rebuild.sh

CMake version too old

The project requires CMake 3.20+. Check your version:

cmake --version

Clean Build¶

If you encounter issues, try a clean build:

# Remove build directory
rm -rf build/

# Rebuild from scratch
cmake --preset release
cmake --build --preset release

IDE Integration¶

Visual Studio Code¶

Install the CMake Tools extension
Open the project folder
Select the build preset from the CMake Tools panel
Build using Ctrl+Shift+B

CLion¶

Open the project folder
CLion will auto-detect CMake configuration
Select the desired preset from the build configuration dropdown

Next Steps¶

After building successfully, learn how to use the viewer!