# Building from source

This page is for developers. Players should download a package from the
[releases page](https://github.com/alondero/aerogauge-recomp/releases).

A source build needs:

1. the files in this repository; and
2. your own dump of the supported USA ROM, plus Japanese Rev A to include
   Japanese support in the same executable.

The ROM is read while building and again when the program starts. It is never
committed or included in a release package.

## Supported build targets

For the ARM64 Android APK, follow [Android building and signing](docs/android.md).

| Host | Compiler | Renderer path | Status |
| --- | --- | --- | --- |
| 64-bit Windows | MinGW-w64 GCC and G++ | RT64 with Direct3D 12 | Supported |
| 64-bit Linux | GCC and G++ | RT64 with Vulkan | Supported |
| ARM64 Android | Android NDK 28 and Gradle | RT64 with Vulkan (system or imported driver) | Supported |
| macOS | - | - | Not supported by this branch |

The source tree does not provide the macOS window and input wiring. An upstream
renderer backend does not change that port status.

## Prerequisites

All platforms need:

- Git with recursive submodule support.
- CMake 3.20 or newer.
- Python 3.11 or newer (the mod guard generator reads TOML metadata).
- Ninja.
- A C17/C++20 compiler.

Linux also needs SDL2 development files, Vulkan headers and loader, FreeType
development files, and the desktop development files required by SDL2 and RT64.
On Debian or Ubuntu, the release workflow uses:

~~~bash
sudo apt-get install -y --no-install-recommends   build-essential cmake ninja-build python3 pkg-config   libsdl2-dev libvulkan-dev libfreetype-dev   libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev   libdbus-1-dev
~~~

Windows needs MinGW-w64 GCC, CMake, and Ninja. Put the MinGW `bin` directory
on `PATH` so GCC can find its own runtime DLLs. CMake downloads
DirectX-Headers while configuring the Windows renderer, so the first configure
needs network access.

On Windows, long paths in the RT64 submodule may need the Git long-path
setting:

~~~powershell
git config --global core.longpaths true
~~~

The Windows script also accepts:

~~~powershell
$env:AERO_MINGW_BIN = '<your MinGW bin directory>'
~~~

Use `AERO_PYTHON_SCRIPTS` if CMake was installed by Python and its scripts
directory is not discoverable. These variables affect the build script only.
They are not game settings.

## ROM

Use the USA dump named `AeroGauge (USA).z64`. The accepted file is 8 MiB and
has XXH3-64 value `0x89ea0690f3e22201`. The
[ROM reference](docs/reference/rom.md) explains how this value was measured.

The scripts use this filename by default. The Windows script accepts another
file with `-RomPath`. The Linux script accepts another filename through
`ROM_FILENAME`. The recompiler TOML still contains the default filename, so
update that input before using a non-default name for regeneration.

## Recommended build

To include Japanese support, also place `AeroGauge (Japan) (Rev A).z64`,
`.n64`, or `.v64` at the repository root. Alternatively set
`JAPAN_ROM_FILENAME` to its path before running any build script. The generator
normalizes byte order and validates the complete dump, then generates separate
`RecompiledFuncsJP/` code. Both ROMs use the same verified audio microcode.
Without a Japanese ROM, a fresh source checkout builds USA support only;
existing Japanese generated code requires its ROM for regeneration.

The release workflow requires both dumps in the existing private ROM-assets
repository, with Japanese Rev A named `AeroGauge (Japan) (Rev A).n64`.
Both inputs and the normalized Japanese copy are removed before packaging.
No ROM belongs in this public repository or a release archive.

For manual regeneration after changing Japanese boundaries:

~~~text
python -B scripts/gen_syms_toml.py --region jp --rom "path/to/Japanese dump.n64"
build/lib/N64ModernRuntime/librecomp/N64Recomp/N64Recomp aerogauge.jp.toml
~~~

On Windows add `.exe` to the recompiler command. Reconfigure CMake after
generation so it includes both code libraries and the Japanese overlay table.

Clone the repository with its submodules, or initialise them in an existing
checkout:

~~~bash
git clone --recurse-submodules https://github.com/alondero/aerogauge-recomp.git
cd aerogauge-recomp
~~~

Run the script for the host:

~~~powershell
.\build.ps1
~~~

~~~bash
./build.sh
~~~

Use `-Clean` on Windows or `--clean` on Linux for a clean build. The clean
option removes only `build/`.

Both scripts:

1. check the host tools and ROM;
2. initialise the submodules;
3. reset tracked submodule files and apply this repository's patches;
4. configure CMake once to build N64Recomp and RSPRecomp;
5. generate the ROM-derived CPU and audio code;
6. configure CMake again so the generated files are included; and
7. build `aerogauge_modern`.

The reset in step 3 is important. Do not keep unexported changes in a submodule
when running a build. Export a dependency change as a patch first; see
[Contributing](CONTRIBUTING.md).

The output program is `build\aerogauge_modern.exe` on Windows and
`build/aerogauge_modern` on Linux.

## Dependency patches

The patch files are the source of truth for local dependency changes. See the
[patch inventory](patches/README.md) for their purpose and application order.
The host scripts are the executable build contract. Linux does not use the
Windows-only patches 0005 or 0004. Patch 0013 fixes audio task submission on
both supported platforms.

If a patch no longer applies to its pinned commit, stop and review the
dependency change. Do not edit a patched submodule and leave the change
unexported. The renderer ownership boundary is described in the
[renderer reference](docs/reference/renderer.md).

## Generated files

| Path | Owner | Commit it? |
| --- | --- | --- |
| `aerogauge.syms.toml` | Generated by `scripts/gen_syms_toml.py` | Yes, after reviewing the generated diff |
| `aerogauge.us.toml` | Generated by `scripts/gen_syms_toml.py` | Yes, after reviewing the generated diff |
| `aspMain.us.toml` | Hand-maintained RSPRecomp input | Yes |
| `RecompiledFuncs/` | N64Recomp | No; ignored and regenerated from the ROM |
| `src/aspMain.cpp` | RSPRecomp | No; ignored and regenerated from the ROM |
| `build/` | CMake and Ninja | No |

Edit `scripts/gen_syms_toml.py` when changing the automatic symbol scan, stubs,
or hook blocks. Do not edit the two generated TOML files, `RecompiledFuncs/`, or
`src/aspMain.cpp` by hand. The runtime and generated-code boundary is
described in
[Architecture](docs/architecture.md).

## Manual stages

The scripts are the supported path. Use these stages when investigating a build.

### Build the recompiler tools

From the repository root, after submodules and patches are ready:

~~~bash
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --target N64RecompCLI RSPRecomp
~~~

If ROM evidence, the symbol map, or the stub policy changed, regenerate the
tracked automatic inputs first:

~~~bash
python3 scripts/gen_syms_toml.py
~~~

Review the generated diff before running the recompiler.

### Generate the ROM-derived files

Run from the repository root:

~~~bash
./build/lib/N64ModernRuntime/librecomp/N64Recomp/N64Recomp aerogauge.us.toml
~~~

On Windows, use the `.exe` files in the same directory. The first command
writes `RecompiledFuncs/`. The second writes `src/aspMain.cpp`:

~~~bash
./build/lib/N64ModernRuntime/librecomp/N64Recomp/RSPRecomp aspMain.us.toml
~~~

### Configure again and build the port

The second configure is required because the generated files did not exist at
the first configure:

~~~bash
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --target aerogauge_modern
~~~

The post-build step copies `assets/frontend/` and the RmlUi fonts beside the
executable. Windows also needs `freetype.dll`.

## Run a source build

Run from the repository root so the default ROM filename resolves:

~~~powershell
.\build\aerogauge_modern.exe
~~~

~~~bash
./build/aerogauge_modern
~~~

For a ROM-backed headless smoke run:

~~~bash
AERO_HEADLESS=1 AERO_MODERN_MAX_VIS=120 ./build/aerogauge_modern
~~~

The headless path avoids the window and normal graphics device. It is a test
path, not the normal player path. See [Testing](docs/testing.md) for skip
conditions.

## Common build failures

- **Submodule missing:** run `git submodule update --init --recursive`.
- **Patch does not apply:** check for submodule drift and refresh the patch; do
  not force it.
- **CMake cannot find SDL2 or Vulkan:** install the host development packages.
- **CMake cannot find DirectX-Headers:** configure Windows with network access.
- **The executable links without generated functions:** run both recompiler
  commands, then configure CMake a second time.
- **The game cannot find the ROM:** check the filename, path, size, and ROM
  identity.
- **A stale static library is linked:** use the clean option. Do not remove
  source or generated directories by hand.

Use [Testing](docs/testing.md) after a successful build and
[Debugging](docs/debugging.md) for a reproducible investigation.