All source listed below is under MIT license if no LICENSE file stating different is available.

Example project - CMake Emscripten Project Template

A cross-platform C++ project template using CMake and Emscripten for building native desktop applications and WebAssembly applications that run in web browsers.

Features

  • Cross-platform: Builds for both native platforms (Linux, Windows, macOS) and WebAssembly
  • Modern C++: Uses C++26 standard
  • SDL3: Graphics and multimedia library for cross-platform development
  • vcpkg: Package manager for C++ dependencies
  • Emscripten: Compile C++ to WebAssembly for web deployment
  • Testing: Integrated with Catch2 testing framework
  • Asset Pipeline: Automatic data folder preloading for web builds

Prerequisites

Required Tools

  • CMake (version 4.0 or higher)
  • vcpkg package manager
  • Emscripten SDK (for WebAssembly builds)
  • C++ Compiler supporting C++26:
    • GCC 14+ or Clang 18+ (Linux/macOS)
    • MSVC 2022 (Windows)

Setup vcpkg

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # On Windows: .\bootstrap-vcpkg.bat

Setup Emscripten

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh  # On Windows: emsdk_env.bat

Project Structure

manater/
├── CMakeLists.txt          # Main CMake configuration
├── vcpkg.json             # Package dependencies
├── serve.py               # Development web server
├── src/                   # Source code
│   ├── main.cpp          # Application entry point
│   └── util/             # Utility modules
├── data/                  # Game assets (preloaded in web builds)
│   └── test.txt          # Example data file
├── tests/                 # Unit tests
└── cmake-build-debug/     # Build output directory

Building

Native Build (Desktop)

# Configure with vcpkg
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path-to-vcpkg]/scripts/buildsystems/vcpkg.cmake

# Build
cmake --build build

# Run
./build/manater

WebAssembly Build

# Configure with Emscripten toolchain
emcmake cmake -B build-web -S . -DCMAKE_TOOLCHAIN_FILE=[path-to-vcpkg]/scripts/buildsystems/vcpkg.cmake

# Build
cmake --build build-web

# Serve locally
cd build-web
python3 ../serve.py

Then open your browser to http://localhost:8000

Development

Adding Dependencies

Add new dependencies to vcpkg.json:

{
  "dependencies": [
    "sdl3",
    "catch2",
    "your-new-dependency"
  ]
}

Asset Management

  • Place game assets in the data/ folder
  • Files in data/ are automatically preloaded in WebAssembly builds
  • Access files using relative paths from the root (e.g., "test.txt")

Testing

# Build and run tests
cmake --build build --target tests_manater
./build/tests_manater

Configuration

Compiler Flags

The project is configured with strict warning levels:

  • MSVC: /W4 /WX (treat warnings as errors)
  • GCC/Clang: -Wall -Wextra -Wpedantic -Werror

Emscripten Settings

  • Output format: HTML with embedded JavaScript and WebAssembly
  • Data preloading: Automatically includes data/ folder
  • SDL3 integration: Configured for web compatibility

Customization

Project Name

  1. Update the project() name in CMakeLists.txt
  2. Update the name field in vcpkg.json
  3. Rename the project folder if desired

Adding Source Files

Add new source files to the ${PROJECT_NAME}_src variable in CMakeLists.txt:

set(${PROJECT_NAME}_src 
    src/main.cpp
    src/your_new_file.cpp
    src/util/helper.cpp
)

Troubleshooting

Common Issues

vcpkg not found: Set the VCPKG_ROOT environment variable or specify the toolchain file manually.

Emscripten build fails: Ensure the Emscripten SDK is properly activated in your shell.

SDL3 linking errors: Make sure vcpkg has installed SDL3 for your target platform.

Web Deployment

For production deployment:

  1. Build with release configuration: -DCMAKE_BUILD_TYPE=Release
  2. Copy the generated .html, .js, .wasm, and .data files to your web server
  3. Ensure proper MIME types are configured for .wasm files

License

This template is provided as-is for educational and development purposes.

Contributing

This is a template project. Fork and modify as needed for your specific use case.

data
src
tests
.gitignore
CMakeLists.txt
README.md
serve.py
vcpkg.json