|
# 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
|
|
```bash
|
|
git clone https://github.com/Microsoft/vcpkg.git
|
|
cd vcpkg
|
|
./bootstrap-vcpkg.sh # On Windows: .\bootstrap-vcpkg.bat
|
|
```
|
|
|
|
### Setup Emscripten
|
|
```bash
|
|
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)
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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`:
|
|
```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
|
|
```bash
|
|
# 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`:
|
|
```cmake
|
|
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.
|