zeldaret/oot: rebuilding Ocarina of Time from a ROM you supply

A work in progress that is explicit about not being a port

The project opens with a warning rather than a feature list. It says the repository is a work in progress, that while it can be used to make certain changes it is still constantly evolving, and that the codebase can drastically change at any time. It also warns that some parts of the ROM may not be shiftable yet, so modifying them could be difficult. The stated purpose is to recreate a source code base for the game from scratch, using information found inside the game together with static and dynamic analysis. One line removes the most common misunderstanding, and it is worth keeping in mind: this is not producing a PC port. What a successful build gives you is a reconstruction that matches the original bytes, not a game that runs on your desktop.

Sixteen target versions, each pinned by an MD5

Inputs are identified by hash rather than by filename. Sixteen versions are supported, each listed with a build timestamp and the MD5 of the input ROM or ROMs. The set spans NTSC 1.0 and 1.1, PAL 1.0 and 1.1, the GameCube Japanese, US and European releases including the Master Quest and Debug variants, the Collector's Edition disc, and the Simplified Chinese iQue Player build. The default target is gc-eu-mq-dbg, the GameCube Europe and PAL Master Quest Debug ROM, with a build timestamp of 03-02-21 00:16:31.

gc-eu-mq-dbg
gc-eu-dbg
gc-eu
gc-eu-mq
gc-jp-mq
gc-us-mq
ntsc-1.0
ntsc-1.1
ntsc-1.2
pal-1.0
pal-1.1
gc-jp-ce
ique-cn

Some versions list more than one accepted input ROM hash.

No assets ship with the repository, and the ROM is the only input

The repository includes none of the assets necessary to build the ROM, and a prior copy of the game is required to extract them. The Makefile names the exact place it looks, and the version you pick decides the subdirectory.

baseroms/$(VERSION)/baserom.z64
9f04c8e68534b870f707c247fa4b50fc
2c27b4e000e85fd78dbca551f1b1c965

The first hash is one of the two listed for NTSC 1.0 and the second is the GameCube Europe/PAL build. Once the build runs, COMPARE defaults to 1 and checks the output MD5 against the target, so a green run means byte-identical output.

Two switches separate a matching build from a modding build

The Makefile exposes the choice directly. COMPARE defaults to 1, which checks the output md5sum after building, and the comment says to set it to 0 when modding. NON_MATCHING defaults to 0, and setting it to 1 defines the NON_MATCHING C flag when building, again for modding. Two more change how the code is produced: ORIG_COMPILER set to 1 compiles with QEMU_IRIX and the original compiler, and COMPILER set to gcc compiles with GCC instead of IDO, which is the default. If you are modding and leave COMPARE at 1, every build reports a mismatch, which is expected rather than a broken toolchain.

make setup VERSION=ntsc-1.0
make VERSION=ntsc-1.0

Settings can be appended to each make command as shown, written into a file called .make_options.mk that is gitignored by default, or edited into the Makefile itself. The file also sets SHELL to bash with pipefail, so a build fails when a piped command inside a recipe fails rather than swallowing the error.

Build dependencies, a Python 3.10 floor, and a MIPS toolchain

The documented package list is short, and Python 3.10 or newer is required.

sudo apt-get update
sudo apt-get install git build-essential curl python3 python3-pip python3-venv libxml2-dev

Beyond those packages you need MIPS binutils. Three families are recognised, only one is required, and it is detected automatically: mips64-ultra-elf- or mips64- from the practicerom toolchain, mips64-elf- from the libdragon n64 homebrew library, and mips-linux-gnu- or mips64-linux-gnu- as shipped by distributions. If none of those can be installed, the Makefile exposes MIPS_BINUTILS_PREFIX for your own prefix. Choosing GCC as the compiler also means installing the matching gcc for that toolchain, which for the distribution packages is often a separate one.

crunch64>=0.5.1,<1.0.0
ipl3checksum>=1.2.0,<2.0.0
pyyaml>=6.0.1,<7.0.0
pyelftools==0.30
rabbitizer>=1.0.0,<2.0.0
spimdisasm>=1.28.1,<2.0.0

Those six come from requirements.txt; pyelftools is pinned to one exact version, while the asm-differ and decomp-permuter entries carry no version constraint at all.

The container never exits, which is the point of it

Windows 10 and 11 users are pointed at WSL with a Linux distribution, Ubuntu recommended, and older Windows at a Linux VM or Docker. The Docker path is a real image definition rather than a paragraph, built from Ubuntu 24.04 with the distribution MIPS binutils plus clang-tidy and clang-format already inside.

FROM ubuntu:24.04 AS build
WORKDIR /oot
RUN git config --global --add safe.directory /oot
CMD make -j $(nproc) setup && make -j $(nproc) && tail -f /dev/null

That last line is the design: the image runs setup and the build, then holds the container open with tail so you can exec into a finished build. The compose file mounts the repository at /oot, builds from the local Dockerfile, and keeps a TTY with stdin open. WSL users get one strong warning, to clone into the Linux filesystem using Linux git rather than cloning from the Windows side, and the project notes that some platform instructions may be out of date or unmaintained while WSL, Linux and macOS are the ones contributors use.

The Python tooling is how a decompilation actually advances

The repository is not only a C codebase. At the top level sit the scripts that measure progress against the retail game, and requirements.txt groups their dependencies by purpose: setup and compression, then the asm-differ set, then the decomp-permuter set, then the general tools.

diff.py
first_diff.py
sym_info.py
retail_progress.py
undefined_syms.txt

A first-timer should expect to spend time in those scripts rather than in src. Formatting and linting are pinned by .clang-format and .clang-tidy rather than left to review comments, linker_scripts and rsp sit at the top level, and docs holds the per-platform guides including BUILDING_MACOS.md and BUILDING_DOCKER.md. There is one more thing to know about the project's shape: it publishes no GitHub releases, so there is no versioned tarball to download, and the last push landed on 2026-10-18. Pin a commit before you start.

Editorial conclusion

zeldaret/oot is for people who want to read and modify Ocarina of Time as source code, and not for anyone expecting a playable PC build, because the project states outright that it is not producing one. Before you start, get a ROM whose MD5 matches the version row you intend to build, decide whether you are matching retail bytes or modding, since COMPARE and NON_MATCHING both default to the matching case and have to be flipped deliberately, and accept that the codebase can change drastically between pulls.

Frequently asked questions

Official sources

1. Issues
2. README
3. zeldaret/oot on GitHub