From c1c8ec125d61ccf69515ec2e5cfccb1729e67868 Mon Sep 17 00:00:00 2001 From: KiritoDv Date: Mon, 19 Jan 2026 01:25:37 -0600 Subject: [PATCH] Updated building docs --- docs/building.md | 220 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 169 insertions(+), 51 deletions(-) diff --git a/docs/building.md b/docs/building.md index 627cfcc4..46fc62e9 100644 --- a/docs/building.md +++ b/docs/building.md @@ -1,112 +1,230 @@ # Building Ghostship -## Setting Up CubeOS - -1. Clone the CubeOS repository and follow the build instructions. -2. Run the executable passing the path to your ROM as an argument. -3. You should now have a smcube.otr in the root folder of the repository, which will be needed when running this application. - ## Windows Requires: + * At least 8GB of RAM (machines with 4GB have seen complier failures) * Visual Studio 2022 Community Edition with the C++ feature set * One of the Windows SDKs that comes with Visual Studio, for example the current Windows 10 version 10.0.19041.0 - * The `MSVC v142 - VS 2019 C++ build tools` component of Visual Studio + * The `MSVC v143 - VS 2022 C++ build tools` component of Visual Studio + * Python 3 (can be installed manually or as part of Visual Studio) * Git (can be installed manually or as part of Visual Studio) * Cmake (can be installed via chocolatey or manually) -### Clone the Ghostship repository +During installation, check the "Desktop development with C++" feature set: + +![image](https://user-images.githubusercontent.com/30329717/183511274-d11aceea-7900-46ec-acb6-3f2cc110021a.png) +Doing so should also check one of the Windows SDKs by default. Then, in the installation details in the right-hand column, make sure you also check the v143 toolset. This is often done by default. + +It is recommended that you install Python and Git standalone, the install process in VS Installer has given some issues in the past. + +1. Clone the Ghostship repository _Note: Be sure to either clone with the ``--recursive`` flag or do ``git submodule update --init`` after cloning to pull in the libultraship submodule!_ -### Building Ghostship +2. After setup and initial build, use the built-in OTR extraction to make your sf64.o2r file. _Note: Instructions assume using powershell_ ```powershell -# Navigate to the Ghostship repo within powershell. ie: cd "C:\yourpath\Ghostship" -cd Ghostship +# Navigate to the ghostship repo within powershell. ie: cd "C:\yourpath\ghostship" +cd ghostship # Setup cmake project -& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v142 -A x64 -DCMAKE_BUILD_TYPE=Debug -# or for VS2019 -& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 16 2019" -T v142 -A x64 -DCMAKE_BUILD_TYPE=Debug -# Compile project -& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 # --config Release (if you're packaging) +# Add `-DCMAKE_BUILD_TYPE:STRING=Release` if you're packaging +& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64 -# If you need to clean the project you can run -& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 --target clean +# Generate sf64.o2r +& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 --target ExtractAssets + +# Generate ghostship.o2r +& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 --target GeneratePortO2R + +# Compile project +# Add `--config Release` if you're packaging +& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 + +# Now you can run the executable in .\build\x64 or run in Visual Studio +``` + +### Developing Ghostship +With the cmake build system you have two options for working on the project: #### Visual Studio To develop using Visual Studio you only need to use cmake to generate the solution file: ```powershell -# Generates Ghostship.sln at `build/x64` for Visual Studio 2022 -& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v142 -A x64 -# or for Visual Studio 2019 -& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 16 2019" -T v142 -A x64 +# Generates ghostship.sln at `build/x64` for Visual Studio 2022 +& 'C:\Program Files\CMake\bin\cmake' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64 ``` -### Running the executable +#### Visual Studio Code or another editor +To develop using Visual Studio Code or another editor you only need to open the repository in it. +To build you'll need to follow the instructions from the building section. -1. Copy over the smcube.otr you have generated into the directory containing your executable, e.g. `.\build\x64\Debug` -2. Download the latest `sm64.otr` from the pins in the discord channel and place that in the same directory as you smcube.otr -3. Now you can run the executable directly or from Visual Studio +_Note: If you're using Visual Studio Code, the [cpack plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) makes it very easy to just press run and debug._ + +_Experimental: You can also use another build system entirely rather than MSVC like [Ninja](https://ninja-build.org/) for possibly better performance._ + + +### Generating the distributable +After compiling the project you can generate the distributable by running: +```powershell +# Go to build folder +cd "build/x64" +# Generate +& 'C:\Program Files\CMake\bin\cpack.exe' -G ZIP +``` + +### Additional CMake Targets +#### Clean +```powershell +# If you need to clean the project you can run +C:\Program Files\CMake\bin\cmake.exe --build build-cmake --target clean +``` ## Linux -Requires `gcc >= 10, x11, sdl2 >= 2.0.22, libpng, ninja, cmake, lld` +### Install dependencies +#### Debian/Ubuntu +```sh +# using gcc +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 -**Important: For maximum performance make sure you have ninja build tools installed!** +# or using clang +apt-get install clang 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 +``` +#### Arch +```sh +# using gcc +pacman -S gcc git cmake ninja lsb-release sdl2 libpng libzip nlohmann-json tinyxml2 spdlog sdl2_net boost libogg libvorbis -_Note: If you're using Visual Studio Code, the [cpack plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) makes it very easy to just press run and debug._ +# or using clang +pacman -S clang git cmake ninja lsb-release sdl2 libpng libzip nlohmann-json tinyxml2 spdlog sdl2_net boost libogg libvorbis +``` +#### Fedora +```sh +# using gcc +dnf install gcc gcc-c++ git cmake ninja-build lsb_release SDL2-devel libpng-devel libzip-devel libzip-tools nlohmann-json-devel tinyxml2-devel spdlog-devel boost-devel libogg-devel libvorbis-devel -### Building Ghostship +# or using clang +dnf install clang git cmake ninja-build lsb_release SDL2-devel libpng-devel libzip-devel libzip-tools nlohmann-json-devel tinyxml2-devel spdlog-devel boost-devel libogg-devel libvorbis-devel +``` +#### openSUSE +```sh +# using gcc +zypper in gcc gcc-c++ git cmake ninja SDL2-devel libpng16-devel libzip-devel libzip-tools nlohmann_json-devel tinyxml2-devel spdlog-devel libogg-devel libvorbis-devel + +# or using clang +zypper in clang libstdc++-devel git cmake ninja SDL2-devel libpng16-devel libzip-devel libzip-tools nlohmann_json-devel tinyxml2-devel spdlog-devel libogg-devel libvorbis-devel +``` + +### Build + +_Note: If you're using Visual Studio Code, the [CMake Tools plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) makes it very easy to just press run and debug._ ```bash -# Clone the repo -git clone https://github.com/HarbourMasters/Ghostship.git -cd Ghostship -# Clone the submodule libultraship +# Clone the repo and enter the directory +git clone https://github.com/HarbourMasters/ghostship.git +cd ghostship + +# Clone the submodules git submodule update --init + # Generate Ninja project -cmake -H. -Bbuild-cmake -GNinja -DCMAKE_BUILD_TYPE= Debug +# Add `-DCMAKE_BUILD_TYPE:STRING=Release` if you're packaging +# Add `-DPython3_EXECUTABLE=$(which python3)` if you are using non-standard Python installations such as PyEnv +cmake -H. -Bbuild-cmake -GNinja + +# Generate sf64.o2r +cmake --build build-cmake --target ExtractAssets + +# Generate ghostship.o2r +cmake --build build-cmake --target GeneratePortO2R + # Compile the project +# Add `--config Release` if you're packaging cmake --build build-cmake +# Now you can run the executable in ./build-cmake/mm/2s2h.elf +# To develop the project open the repository in VSCode (or your preferred editor) +``` + +### Generate a distributable +After compiling the project you can generate a distributable by running of the following: +```bash +# Go to build folder +cd build-cmake +# Generate +cpack -G DEB +cpack -G ZIP +cpack -G External (creates appimage) +``` + +### Additional CMake Targets +#### Clean +```bash # If you need to clean the project you can run cmake --build build-cmake --target clean ``` -### Running the executable - -1. Copy over the smcube.otr you have generated into the root directory if the repository -2. Download the latest `sm64.otr` from the pins in the discord channel and place that in the build directory, e.g. `./build-cmake` -3. Now you can run the executable directly or from Visual Studio Code - ## macOS -Requires Xcode (or xcode-tools) && `ninja, cmake` (can be installed via homebrew, macports, etc) +Requires Xcode (or xcode-tools) && `sdl2, libpng, glew, ninja, cmake, nlohmann-json, tinyxml2, libzip, vorbis-tools` (can be installed via homebrew, macports, etc) **Important: For maximum performance make sure you have ninja build tools installed!** _Note: If you're using Visual Studio Code, the [cpack plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) makes it very easy to just press run and debug._ -### Building Ghostship - ```bash # Clone the repo -git clone https://github.com/HarbourMasters/Ghostship.git -cd Ghostship +git clone https://github.com/HarbourMasters/ghostship.git +cd ghostship # Clone the submodule libultraship git submodule update --init + # Generate Ninja project -cmake -H. -Bbuild-cmake -GNinja -DCMAKE_BUILD_TYPE=Debug +# Add `-DCMAKE_BUILD_TYPE:STRING=Release` if you're packaging +cmake -H. -Bbuild-cmake -GNinja + +# Generate sf64.o2r +cmake --build build-cmake --target ExtractAssets + +# Generate ghostship.o2r +cmake --build build-cmake --target GeneratePortO2R + # Compile the project +# Add `--config Release` if you're packaging cmake --build build-cmake +# Now you can run the executable file: +./build-cmake/Ghostship +# To develop the project open the repository in VSCode (or your preferred editor) +``` + +### Generating a distributable +After compiling the project you can generate a distributable by running of the following: +```bash +# Go to build folder +cd build-cmake +# Generate +cpack +``` + +### Additional CMake Targets +#### Clean +```bash # If you need to clean the project you can run cmake --build build-cmake --target clean ``` -### Running the executable +# Compatible Roms +See [`supportedHashes.json`](supportedHashes.json) -1. Copy over the smcube.otr you have generated into the root directory if the repository -2. Download the latest `sm64.otr` from the pins in the discord channel and place that in the build directory, e.g. `./build-cmake` -3. Now you can run the executable directly or from Visual Studio Code +## Getting CI to work on your fork + +The CI works via [Github Actions](https://github.com/features/actions) where we mostly make use of machines hosted by Github; except for the very first step of the CI process called "Extract assets". This steps extracts assets from the game file and generates an "assets" folder in `mm/`. + +To get this step working on your fork, you'll need to add a machine to your own repository as a self-hosted runner via "Settings > Actions > Runners" in your repository settings. Make sure to add the 'asset-builder' tag to your newly added runner to assign it to run this step. To setup your runner as a service read the docs [here](https://docs.github.com/en/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service?platform=linux). + +### Runner on Windows +You'll have to enable the ability to run unsigned scripts through PowerShell. To do this, open Powershell as administrator and run `set-executionpolicy remotesigned`. Most dependencies get installed as part of the CI process. You will also need to separately install 7z and add it to the PATH so `7z` can be run as a command. [Chocolatey](https://chocolatey.org/) or other package managers can be used to install it easily. + +### Runner on UNIX systems +If you're on macOS or Linux take a look at `macports-deps.txt` or `apt-deps.txt` to see the dependencies expected to be on your machine.