# Lighthouse CMake Targets and Build Configuration Options

> Explore Lighthouse CMake targets and build configuration options. Customize sanitizers, networking, and platform settings for your build.

- Repository: [Harbour Masters/Lighthouse](https://github.com/HarbourMasters/Lighthouse)
- Tags: how-to-guide
- Published: 2026-08-04

---

**The HarbourMasters/Lighthouse project defines one primary executable target, multiple helper targets for asset processing, and extensive `option()` flags for sanitizers, networking, game selection, and platform customization.**

All source files flow into a single `${PROJECT_NAME}` executable linked against the **libultraship** engine library, with build behavior controlled through CMake options located in the root [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt) and supplemental `.cmake` modules.

---

## Primary CMake Targets

The build system centers on one main executable with supporting targets that handle preprocessing, packaging, and platform-specific tasks.

### `${PROJECT_NAME}` — The Main Executable

The central target aggregates all source files into the game binary:

```cmake
add_executable(${PROJECT_NAME} ${ALL_FILES})

```

This declaration appears at line 52 of [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt), where `ALL_FILES` collects C, C++, and header files from across the project tree. The executable immediately links to the engine:

```cmake
target_link_libraries(${PROJECT_NAME} PRIVATE libultraship)

```

### `libultraship` — Engine Library

Added via `add_subdirectory` at line 69, this external library provides the core rendering, audio, and platform abstraction layers. The subdirectory resides at `${CMAKE_CURRENT_SOURCE_DIR}/libultraship`.

### `TorchExternal` — Asset Tool Builder

An `ExternalProject` definition starting at line 735 builds the **Torch** tool from the `Torch/` subdirectory. This compiled binary performs asset extraction and format conversion.

### `ExtractAssets` — Asset Extraction Target

```cmake
add_custom_target(ExtractAssets ...)

```

Defined at line 750, this target invokes the built Torch binary to extract original game assets into the format Lighthouse requires. Run it explicitly:

```bash
cmake --build . --target ExtractAssets

```

### `GeneratePortO2R` — Packaging Target

At line 759, this custom target packs the port directory into an `.o2r` archive format for distribution.

### `CreateOSXIcons` — macOS Resource Target

Present at line 774 and active only on macOS builds, this generates proper `.icns` icon sets for application bundles.

---

## Core Build Configuration Options

Lighthouse exposes platform-agnostic toggles through `option()` declarations near the top of [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt), with platform-specific blocks handling toolchain details.

### Sanitizer and Debugging Options

| Option | Default | Purpose |
|--------|---------|---------|
| `ENABLE_ASAN` | `OFF` | Activates AddressSanitizer via `/fsanitize=address` on MSVC or `-fsanitize=address` on GCC/Clang; adjusts debug symbol generation (`/Zi`) |

Lines 75-78 declare this option. When enabled, the build injects sanitizer flags and disables incompatible optimizations.

### Networking and Dependencies

| Option | Default | Purpose |
|--------|---------|---------|
| `USE_NETWORKING` | `ON` | Pulls in SDL2_net and defines `USE_NETWORKING` preprocessor macro |
| `EXCLUDE_MPQ_SUPPORT` | `ON` | Disables MPQ archive handling (original game format) |
| `BUILD_STORMLIB` | `OFF` | Adds StormLib support for alternate asset formats |

### Game Selection Toggles

Multiple `BUILD_*` options control which game assets compile into the binary:

- `BUILD_BK64` — Banjo-Kazooie
- `BUILD_PM64` — Paper Mario
- `BUILD_SM64` — Super Mario 64

Most default to `ON`, with some platform-specific variations. Disable unneeded games to reduce binary size and build time.

### Standalone and Packaging Options

| Option | Default | Purpose |
|--------|---------|---------|
| `USE_STANDALONE` | `OFF` | Builds a fully self-contained executable with no external asset dependencies |

### Compiler Standards

```cmake
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_C_STANDARD 11)

```

These are hardcoded in the main [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt), establishing C++20 and C11 as baseline requirements.

---

## Platform-Specific Build Configuration

The root [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt) branches into platform-specific sections that configure toolchains, find dependencies, and set packaging behavior.

### Windows Configuration

Three distinct blocks handle Windows builds:

- **vcpkg integration** (lines 95-107): Bootstraps the package manager and sets `VCPKG_TRIPLET` to `x64-windows-static` by default
- **MSVC runtime** (lines 158-196): Configures static/dynamic runtime library selection
- **Compiler flags** (lines 260-286): Adds `/W4` warning levels and link-time optimization controls

### iOS Configuration

Lines 21-28 load `cmake/ios.toolchain.cmake` and define `PLATFORM_IOS` for conditional compilation. The `SKIP_XCODE_VERSION_CHECK` option (default `ON`) bypasses strict Xcode version validation.

### macOS and Linux Configuration

Lines 80-84 configure OpenGL linkage for UNIX platforms. Lines 447-458 handle Ogg/Vorbis audio libraries on non-Switch builds. `CMAKE_OSX_DEPLOYMENT_TARGET` defaults to `"10.15"`.

### Nintendo Switch Configuration

Lines 59-71 set up SDL2, Ogg/Vorbis, and additional Horizon OS libraries. The `EXCLUDE_MPQ_SUPPORT` option typically remains `ON` for this platform due to storage constraints.

---

## Typical Build Invocations

Configure a release build with default options:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

```

Enable debugging features and specific game support:

```bash
cmake -S . -B build -DENABLE_ASAN=ON -DBUILD_BK64=ON -DBUILD_PM64=OFF

```

Windows Visual Studio 2022 with static vcpkg libraries:

```bash
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

```

Extract assets after initial compilation:

```bash
cmake --build build --target ExtractAssets

```

Generate distributable `.o2r` package:

```bash
cmake --build build --target GeneratePortO2R

```

---

## Key Source Files and Locations

| File | Lines | Contents |
|------|-------|----------|
| [`CMakeLists.txt`](https://github.com/HarbourMasters/Lighthouse/blob/main/CMakeLists.txt) | 1-786+ | Root build script with all targets and options |
| `cmake/lighthouse-cvars.cmake` | — | Project-wide CMake variable definitions |
| `cmake/lus-cvars.cmake` | — | libultraship-specific configuration |
| `cmake/ios.toolchain.cmake` | — | iOS cross-compilation toolchain |
| `cmake/packaging.cmake` | — | CPACK installer configuration |
| [`docs/BUILDING.md`](https://github.com/HarbourMasters/Lighthouse/blob/main/docs/BUILDING.md) | 35-45 | User-facing build examples |

---

## Summary

- **Single executable target** — `${PROJECT_NAME}` aggregates all sources and links `libultraship`
- **Four helper targets** — `TorchExternal`, `ExtractAssets`, `GeneratePortO2R`, `CreateOSXIcons` handle tooling and packaging
- **Sanitizer control** — `ENABLE_ASAN` enables AddressSanitizer across compilers
- **Network toggle** — `USE_NETWORKING` activates SDL2_net integration
- **Game selection** — Per-game `BUILD_*` options filter compiled assets
- **Platform specialization** — Conditional blocks for Windows (vcpkg/MSVC), iOS, macOS/Linux, and Nintendo Switch

These configuration points allow precise control over binary features, debugging capabilities, and target platforms without modifying source code.

---

## Frequently Asked Questions

### How do I enable AddressSanitizer in a Lighthouse build?

Pass `-DENABLE_ASAN=ON` during the CMake configuration step. The build system automatically applies `/fsanitize=address` on MSVC or `-fsanitize=address` on GCC/Clang, along with compatible debug symbol settings.

### What is the Torch tool and when do I need to build it?

Torch is an external asset processing tool defined as the `TorchExternal` target. You must build it before running `ExtractAssets`, as the extraction target depends on the compiled `torch` binary to convert original game files into Lighthouse's runtime format.

### Can I build Lighthouse without networking support?

Yes. Set `-DUSE_NETWORKING=OFF` to disable SDL2_net integration and remove all networking-related code from compilation. This reduces dependencies and binary size for offline-only deployments.

### Which CMake target produces the distributable game package?

The `GeneratePortO2R` target creates the `.o2r` archive containing all port assets in distribution format. Run `cmake --build . --target GeneratePortO2R` after successful compilation and asset extraction.