This repository contains the repeatable orchestration layer for the supplied Nintendo 64 Gigaleak ezbuild archives. It follows the useful Project-Y pattern—inputs stay outside the repository, recipes describe the build, and the checked-in tools make the build reproducible—while adding the RHL9 VM, the original DM64 Windows XP/Cygwin workflow, media, compatibility, logging, reuse, and export steps needed by the N64 sources.
The repository intentionally does not contain Red Hat media, Nintendo SDK media, source archives, ROMs, keys, passwords, or VM disks. The operator supplies the media and archives locally.
- Windows with VMware Workstation and
vmrun.exe. - Node.js 18 or newer.
- Red Hat Linux 9 installation media and the Nintendo 64 SDK ISO that the operator is authorized to use.
- A Windows XP build VM with VMware Tools, Cygwin, the historical DM64 toolchain, and PowerShell remoting access from the host when building DM64.
- The N64 ezbuild archives from the source collection.
- VMware Tools installed in the guest. The old Red Hat installer is deliberately guided rather than silently automated.
From a checkout of this repository (or use setup.bat, build.bat and export.bat, which wrap n64ez doctor/init, build all and export):
npm link
n64ez doctor --json
n64ez init --input-dir 'C:\path\to\Ezbuilds\N64' --setup-dir 'C:\path\to\Ezbuilds\N64\setup'
n64ez inputs inspect --json
n64ez vm create
n64ez vm installComplete the RHL9 installation in the VMware console, install VMware Tools, and boot the guest. After installation, attach the SDK ISO to the VM's first CD slot:
n64ez vm tools-install
n64ez vm stop
n64ez vm media attach sdk --slot 0
n64ez vm start --headless
n64ez vm sdk-installWith the SDK installed and the build guest running, stage the archives, compatibility files, and GUI launchers:
n64ez vm provision
n64ez build all --json
n64ez export --out 'C:\Users\Public\Desktop\N64-Ezbuilds'The original DM64 US/Japan build is kept on its required XP machine. Configure that connection once, using a local exported PowerShell credential file for the Windows host and an environment variable for the XP guest password:
n64ez xp configure `
--xp-host '<xp-guest-ip>' `
--xp-vmx 'C:\path\to\XP Build Machine.vmx' `
--xp-credential-file 'C:\path\to\host.credential.xml'
$env:N64EZ_XP_GUEST_PASSWORD = '<XP guest password>'
n64ez xp status --json
n64ez xp provision
n64ez xp build all
n64ez xp export all --out 'C:\Users\Public\Desktop\N64-Ezbuilds\DM64'xp provision stages the supplied dm64_iQue.tgz archive, installs the checked-in Cygwin wrapper, and prepares the source if it is not already present. xp build reuses a matching existing release artifact; pass --force to rebuild a locale. The wrapper selects the Ultra SDK's GNU Make 3.71 and MIPSE tools, supplies the historical _LANGUAGE_C flag, exports the locale for mild, normalizes the legacy makefile to CRLF, applies the required minigzip/dd sequencing fix, preserves the original unmasked .SRB output by default, and records a backup of the original makefile inside the VM. Set N64EZ_XP_MAKEMASK=1 only when a masked ROM is specifically wanted.
The local configuration is stored under .n64ez/config.json, which is ignored by Git. Set N64EZ_GUEST_PASSWORD instead of putting a password in the config when possible.
n64ez doctor [--json]
n64ez init --input-dir <dir> [--setup-dir <dir>] [--vm-dir <dir>]
n64ez inputs inspect [--json]
n64ez vm create [--size 20GB]
n64ez vm install
n64ez vm start [--headless]
n64ez vm stop [--hard]
n64ez vm tools-install
n64ez vm sdk-install
n64ez vm provision
n64ez vm media mount|unmount|attach <name>
n64ez build <recipe-id|all> [--force] [--json]
n64ez status [--json]
n64ez export [--out <dir>] [--json]
n64ez xp configure [XP connection options]
n64ez xp status|provision
n64ez xp build [recipe-id|all] [--force]
n64ez xp export [recipe-id|all] [--out <dir>]
build uses the guest launcher's fingerprinted reuse path by default. --force is an explicit legacy-make pass and may reproduce nondeterminism in old makefiles; logs and the resulting hash are always retained.
The recipe set covers Forest iQue, Star Fox 64 iQue, Wave Race 64 iQue, Super Mario 64 iQue, three Mario Kart variants, CBA, Club-ez, texture viewer release/debug, F-Zero X US/Chinese, Zelda Majora, Zelda Ocarina iQue/US-JP, TFC, and the original DM64 US/Japan variants. DM64 is marked as a Windows XP recipe because its source depends on the historical Cygwin toolchain rather than the RHL9 SDK environment.
recipes/n64.json contains the input archive names, platform-specific commands, expected output names, known-good SHA-256 values, and compatibility notes. guest/n64-install-tools.sh installs the RHL9 build packages from the mounted installation discs, guest/n64-install-sdk.sh runs the SDK ISO's supplied installer, and guest/n64-prepare.sh performs the extraction and compatibility fixes discovered while bringing the collection up on RHL9. guest/n64-ezbuild.sh handles idempotent RHL9 builds and artifact publication. guest/dm64-xp-build.sh handles the XP/Cygwin DM64 source, both locale variants, reuse, logs, and artifact publication. If the RHL9 guest has a GNOME desktop, provisioning also creates the shortcut folder /home/miyamoto/Desktop/N64-Ezbuilds; DM64 is launched from the host with n64ez xp build.
| Path | Contents |
|---|---|
bin/n64ez.js |
CLI entry point (npm link exposes it as n64ez) |
src/ |
CLI, config, recipe, VMware and Windows XP orchestration modules |
recipes/n64.json |
Build recipes: input archives, commands, expected outputs and SHA-256 values |
guest/ |
Shell scripts copied into the RHL9 / XP guests; guest/compat/ holds legacy toolchain shims |
tests/ |
node --test suite (npm test) |
assets/ |
README logo |
setup.bat, build.bat, export.bat |
Double-click wrappers for the common host commands |
- Use only media and source archives you are authorized to use.
- Do not commit
.n64ez/config.json, VM disks, source archives, ROMs, SSH keys, or passwords. - The script never downloads proprietary operating-system media. Missing media is reported as a setup error.
- Build artifacts are exported only when their expected output exists; when a recipe has a known-good hash, the exporter reports a mismatch instead of silently calling it verified. The DM64
nrdcsidecar text produced by this old workflow is retained as a log artifact but is not used as a verification claim.
MIT. See LICENSE. The license covers this repository's own scripts and documentation; it grants no rights to Nintendo SDK material, Red Hat media or the source archives the tool consumes.
This project was developed with AI assistance from OpenAI Codex for reverse-engineering support, build automation, VM and toolchain troubleshooting, scripting, documentation, and visual asset generation. The repository owner directed the work, reviewed the resulting changes and generated assets, and remains responsible for the project's technical claims and final decisions.
The repository logo was generated with AI from the supplied Nintendo-style and N64 visual references. It is a project identifier only and does not imply affiliation with or endorsement by Nintendo.
