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 builds on all major Linux distributions using CMake and Ninja. Choose the package manager commands that match your distro below, then follow the common build steps to compile the project and optionally produce a distributable package.
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.

​
Install Dependencies

Select your distribution and preferred compiler: 
sudo apt-get install gcc g++ git cmake ninja-build lsb-release \
  libsdl2-dev libpng-dev libsdl2-net-dev libzip-dev \
  zipcmp zipmerge ziptool nlohmann-json3-dev libtinyxml2-dev \
  libspdlog-dev libboost-dev libopengl-dev libogg-dev libvorbis-dev

​
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
Optional flags:
FlagWhen to use
-DCMAKE_BUILD_TYPE:STRING=ReleaseAdd when creating a distributable package
-DPython3_EXECUTABLE=$(which python3)Add if you manage Python with PyEnv or a non-standard installation
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 executable:
cmake --build build-cmake
Add --config Release when packaging. The compiled binary will be located inside ./build-cmake/.
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, cd into the build directory and run cpack with your desired output format: 
cd build-cmake
cpack -G DEB

​
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 Linux runners, check apt-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