Lighthouse CMake Targets and Build Configuration Options

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 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:

add_executable(${PROJECT_NAME} ${ALL_FILES})

This declaration appears at line 52 of CMakeLists.txt, where ALL_FILES collects C, C++, and header files from across the project tree. The executable immediately links to the engine:

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

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:

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, 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

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_C_STANDARD 11)

These are hardcoded in the main CMakeLists.txt, establishing C++20 and C11 as baseline requirements.

---

Platform-Specific Build Configuration

The root 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:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

Enable debugging features and specific game support:

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

Windows Visual Studio 2022 with static vcpkg libraries:

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

Extract assets after initial compilation:

cmake --build build --target ExtractAssets

Generate distributable .o2r package:

cmake --build build --target GeneratePortO2R

---

Key Source Files and Locations

File	Lines	Contents
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	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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}