Vulkan C++ Template

A minimal, modern C++ template for Vulkan projects using C++20 modules.

Features

• ✅ C++20 Modules - Uses import vulkan_hpp; instead of legacy headers
• ✅ Modern CMake 4.1 - Clean, explicit configuration
• ✅ Slang Shaders - First-class shader language support with SPIR-V compilation
• ✅ Vendored Dependencies - GLFW and GLM as git submodules
• ✅ Ninja Build - Fast, parallel builds
• ✅ Minimal & Opinionated - Linux only, no cross-platform bloat

Prerequisites

Required

• Linux (this template is Arch Linux-specific)
• Vulkan SDK - Install via pacman -S vulkan-devel vulkan-headers vulkan-tools
• CMake 4.1+ - pacman -S cmake
• Ninja - pacman -S ninja
• Clang 20+ or GCC 15+ - pacman -S clang or pacman -S gcc
• Git - For submodules

Optional

• Slang Compiler - For shader compilation (included in some Vulkan SDKs)
• mise - For managing VULKAN_SDK environment variable (see mise.toml)

Quick Start

1. Use This Template

On GitHub:

# Clone from template
gh repo create my-vulkan-app --template toni6/vulkan-template --public --clone
cd my-vulkan-app

Or manually:

git clone https://github.com/toni6/vulkan-template.git my-vulkan-app
cd my-vulkan-app
rm -rf .git
git init

2. Initialize Submodules

git submodule add https://github.com/glfw/glfw.git vendor/glfw
git submodule add https://github.com/g-truc/glm.git vendor/glm
git submodule update --init --recursive

# Pin to stable versions
cd vendor/glfw && git checkout 3.4 && cd ../..
cd vendor/glm && git checkout 1.0.1 && cd ../..
git add vendor/
git commit -m "Add vendored dependencies"

3. Configure & Build

# Configure
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

# Build
ninja -C build

# Run
./build/app

Project Structure

vulkan-template/
├── CMakeLists.txt          # Main build configuration
├── mise.toml               # Optional: environment setup
├── src/
│   └── main.cpp           # Your Vulkan application
├── shaders/
│   └── shader.slang       # Slang shader source
├── vendor/                # Git submodules
│   ├── glfw/
│   └── glm/
└── build/                 # Build artifacts (generated)
    ├── app                # Compiled executable
    ├── shaders/
    │   └── slang.spv      # Compiled SPIR-V
    └── compile_commands.json

Development Workflow

Building

# Full rebuild
ninja -C build

# Shader-only rebuild
ninja -C build slang_shaders

# Clean build
ninja -C build -t clean && ninja -C build

# Verbose output
ninja -C build -v

Editor Integration

The project generates compile_commands.json for LSP/clangd:

# Symlink to project root for editors
ln -sf build/compile_commands.json .

For Zed editor, update .zed/settings.json:

{
  "lsp": {
    "clangd": {
      "binary": {
        "path": "/usr/bin/clangd",
        "arguments": ["-background-index", "--compile-commands-dir=build"]
      }
    }
  }
}

Shader Development

Shaders are automatically compiled during the build:

# Edit shader
vim shaders/shader.slang

# Rebuild (shaders recompile automatically)
ninja -C build

# Force recompile
touch shaders/shader.slang && ninja -C build

Shader entry points:

• vertMain - Vertex shader
• fragMain - Fragment shader

Environment Setup (Optional)

Using mise for environment management:

# Install mise
curl https://mise.run | sh

# Activate in shell
mise install
mise trust

# VULKAN_SDK is now set automatically
echo $VULKAN_SDK

Or manually:

export VULKAN_SDK=/path/to/vulkansdk
export PATH=$VULKAN_SDK/bin:$PATH
export LD_LIBRARY_PATH=$VULKAN_SDK/lib:$LD_LIBRARY_PATH

CMake Configuration Details

C++20 Module Setup

# Vulkan C++ module is built automatically
target_link_libraries(app PRIVATE Vulkan::cppm glfw glm::glm)

In your code:

import vulkan_hpp;  // Modern C++ Vulkan API

#define GLFW_INCLUDE_VULKAN
#include <GLFW/glfw3.h>

Compiler Flags

• Standard: C++20 with modules
• Warnings: -Wall -Wextra -Wpedantic

Customization

Add Source Files

Edit CMakeLists.txt:

add_executable(app
  src/main.cpp
  src/renderer.cpp
  src/window.cpp
)

Add Shader Stages

Add to shaders/shader.slang and update CMakeLists.txt entry points:

-entry computeMain -stage compute

Change Compiler

# Use GCC instead of Clang
cmake -B build -G Ninja -DCMAKE_CXX_COMPILER=g++

Installation

# Install to /usr/local/bin
cmake --install build

# Or specify prefix
cmake --install build --prefix ~/.local

Contributing

This is a template repository. Fork it and make it your own!

License

Public domain / Unlicense - use freely for any purpose.

Resources

• Vulkan Tutorial
• Vulkan-Hpp Documentation
• Slang Documentation
• GLFW Documentation
• GLM Documentation

Template Usage

After creating a new repo from this template:

1. Replace this README with your project-specific documentation
2. Update CMakeLists.txt project name: project(your_project_name LANGUAGES CXX)
3. Replace src/main.cpp with your application code
4. Add your own shaders in shaders/
5. Commit and push!

---

Happy Vulkan coding! 🌋