From 0ccade9de89912fb5b49b451f121072998c03e63 Mon Sep 17 00:00:00 2001
From: Mr-Wiseguy <mrwiseguyromhacking@gmail.com>
Date: Sat, 24 Jan 2026 02:27:25 -0500
Subject: [PATCH] Add building instructions

---
 BUILDING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 BUILDING.md

diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 0000000..435925f
--- /dev/null
+++ b/BUILDING.md
@@ -0,0 +1,74 @@
+# Building Guide
+
+This guide will help you build the project on your local machine. The process will require you to provide a decompressed ROM of the US version of the game.
+
+These steps cover: decompressing the ROM, running the recompiler and finally building the project.
+
+## 1. Clone the BanjoRecomp Repository
+This project makes use of submodules so you will need to clone the repository with the `--recurse-submodules` flag.
+
+```bash
+git clone --recurse-submodules
+# if you forgot to clone with --recurse-submodules
+# cd /path/to/cloned/repo && git submodule update --init --recursive
+```
+
+## 2. Install Dependencies
+
+### Linux
+For Linux the instructions for Ubuntu are provided, but you can find the equivalent packages for your preferred distro.
+
+```bash
+# For Ubuntu, simply run:
+sudo apt-get install cmake ninja-build libsdl2-dev libgtk-3-dev lld llvm clang
+```
+
+### Windows
+You will need to install [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/).
+In the setup process you'll need to select the following options and tools for installation:
+- Desktop development with C++
+- C++ Clang Compiler for Windows
+- C++ CMake tools for Windows
+
+The other tool necessary will be `make` which can be installe via [Chocolatey](https://chocolatey.org/):
+```bash
+choco install make
+```
+
+## 3. Decompressing the target ROM
+You will need to decompress the NTSC-U 1.0 N64 Banjo-Kazooie ROM (sha1: d6133ace5afaa0882cf214cf88daba39e266c078) before running the recompiler.
+
+The most straightforward way to do this is to set up the [Banjo-Kazooie decompilation](https://gitlab.com/banjo.decomp/banjo-kazooie), which will decompress the ROM when building. Alternatively, you can run the [bk_rom_compressor tool](https://github.com/MittenzHugg/bk_rom_compressor) directly, which is what the decompilation uses to decompress the ROM.
+
+Regardless of which method you use, copy the decompressed ROM to the root of the BanjoRecomp repository with this filename:
+- `banjo.us.v10.decompressed.z64`
+
+## 4. Generating the C code
+
+Now that you have the required files, you must build [N64Recomp](https://github.com/N64Recomp/N64Recomp) and run it to generate the C code to be compiled. The building instructions can be found [here](https://github.com/N64Recomp/N64Recomp?tab=readme-ov-file#building). That will build the executables: `N64Recomp` and `RSPRecomp` which you should copy to the root of the BanjoRecomp repository.
+
+After that, go back to the repository root, and run the following commands:
+```bash
+./N64Recomp banjo.us.rev0.toml
+./RSPRecomp n_aspMain.us.rev0.toml
+```
+
+## 5. Building the Project
+
+Finally, you can build the project! :rocket:
+
+On Windows, you can open the repository folder with Visual Studio, and you'll be able to `[build / run / debug]` the project from there.
+
+If you prefer the command line or you're on a Unix platform you can build the project using CMake:
+
+```bash
+cmake -S . -B build-cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -G Ninja -DCMAKE_BUILD_TYPE=Release # or Debug if you want to debug
+cmake --build build-cmake --target BanjoRecompiled -j$(nproc) --config Release # or Debug
+```
+
+## 6. Success
+
+Voilà! You should now have a `BanjoRecompiled` executable in the build directory! If you used Visual Studio this will be `out/build/x64-[Configuration]` and if you used the provided CMake commands then this will be `build-cmake`. You will need to run the executable out of the root folder of this project or copy the assets folder to the build folder to run it.
+
+> [!IMPORTANT]
+> In the game itself, you should be using a standard ROM, not the decompressed one.