cmake-sdl3-emscripten/README.md

# 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.