Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HarbourMasters/Starship/llms.txt

Use this file to discover all available pages before exploring further.

Starship runs on macOS 10.15 Catalina and later. The build process uses CMake with the Ninja generator and requires Xcode command-line tools plus a handful of Homebrew packages. Install Ninja for the best possible build performance.
You must clone the repository with --recursive, or run git submodule update --init after cloning, to pull in the libultraship submodule. The build will fail without it.

​
Prerequisites

​
Xcode Command-Line Tools

You need either the full Xcode IDE or the lightweight Xcode Command-Line Tools. To install the command-line tools only, run: 
xcode-select --install

​
Homebrew Packages

Install all required libraries via Homebrew: 
brew install sdl2 libpng glew ninja cmake nlohmann-json tinyxml2 libzip vorbis-tools
Install Ninja for maximum performance. Ninja’s incremental build model is significantly faster than the default Makefile generator, especially for large C++ projects like Starship.

​
Building Starship

1

Clone the repository

git clone https://github.com/HarbourMasters/starship.git
cd starship
git submodule update --init
2

Configure CMake

Generate a Ninja build tree in the build-cmake directory:
cmake -H. -Bbuild-cmake -GNinja
Add -DCMAKE_BUILD_TYPE:STRING=Release when preparing a distributable build.
The project targets macOS 10.15 (Catalina) as the minimum deployment version, set via CMAKE_OSX_DEPLOYMENT_TARGET in CMakeLists.txt.
3

Generate sf64.o2r

Extract game assets from your ROM to produce the sf64.o2r archive:
cmake --build build-cmake --target ExtractAssets
4

Generate starship.o2r

Package the port-specific assets into starship.o2r:
cmake --build build-cmake --target GeneratePortO2R
5

Compile the project

Build the final Starship binary:
cmake --build build-cmake
Add --config Release when packaging. Once the build succeeds, launch the game directly:
./build-cmake/Starship
If you are using Visual Studio Code, the CMake Tools extension lets you configure, build, and debug with a single click.

​
Generating a Distributable

After a successful build, generate a macOS distributable package with: 
cd build-cmake
cpack

​
Additional CMake Targets

​
Clean

Remove all build artefacts and force a full rebuild on the next run: 
cmake --build build-cmake --target clean

​
CI Setup for Forks

Starship’s CI pipeline uses GitHub Actions. The Extract Assets step requires a self-hosted runner because it needs access to your ROM file. To configure this on your own fork:
  1. Go to Settings → Actions → Runners in your GitHub repository.
  2. Add a new self-hosted runner and assign it the asset-builder tag.
  3. Follow GitHub’s documentation to configure the runner as a service.
For macOS runners, check macports-deps.txt in the repository root to see the full list of packages expected to be present on your CI machine.

Build docs developers (and LLMs) love

Get started for freeTalk to us