mirror of
https://github.com/HackerN64/HackerOoT.git
synced 2026-01-21 10:37:37 -08:00
141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
# Installation
|
|
|
|
We recommend using WSL on Windows, or native Linux, which the rest of this readme describes. We currently have instructions for
|
|
|
|
* [Windows](#Windows), with and without WSL
|
|
* [macOS](docs/BUILDING_MACOS.md)
|
|
* [Linux](#Linux-Native-or-under-WSL--VM), natively or using WSL / VM
|
|
* [Docker](docs/BUILDING_DOCKER.md)
|
|
|
|
(These will also depend on the Linux instructions.)
|
|
Some of these may also be out of date or unmaintained; usually our contributors use WSL, Linux, and macOS, so these instructions should be up to date.
|
|
|
|
### Compiler
|
|
|
|
The compiler to use is automatically detected by the build system. We recommend using [Modern SDK](https://crashoveride95.github.io/modernsdk/startoff.html).
|
|
|
|
### Windows
|
|
|
|
For Windows 10 or 11, install WSL and a distribution by following this
|
|
[WSL Installation Guide](https://docs.microsoft.com/en-us/windows/wsl/install).
|
|
We recommend using Ubuntu 20.04 as the Linux distribution.
|
|
|
|
For older versions of Windows, install a Linux VM or refer to [Docker](docs/BUILDING_DOCKER.md) instructions.
|
|
|
|
|
|
### Linux (Native or under WSL / VM)
|
|
|
|
#### 1. Install build dependencies
|
|
|
|
The build process has the following package requirements:
|
|
|
|
* git
|
|
* build-essential
|
|
* binutils-mips-linux-gnu
|
|
* curl
|
|
* python3
|
|
* python3-pip
|
|
* python3-venv
|
|
* libpng-dev
|
|
* libxml2-dev
|
|
* gcc-mips-linux-gnu
|
|
|
|
Note: you can use another GCC as long as it target MIPS.
|
|
|
|
Under Debian / Ubuntu (which we recommend using), you can install them with the following commands:
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install git build-essential binutils-mips-linux-gnu curl python3 python3-pip python3-venv libpng-dev libxml2-dev gcc-mips-linux-gnu
|
|
```
|
|
|
|
#### 2. Clone the repository
|
|
|
|
**N.B.** If using WSL, we strongly encourage you to clone into WSL's Linux filesystem using Linux's `git`.
|
|
Cloning into the Windows filesystem will result in much slower read/write speeds, and often causes issues when Windows copies the files with the wrong line endings, which the compiler IDO cannot handle correctly.
|
|
|
|
Clone `https://github.com/HackerN64/HackerOoT.git` where you wish to have the project, with a command such as:
|
|
|
|
```bash
|
|
git clone https://github.com/HackerN64/HackerOoT.git
|
|
```
|
|
|
|
This will copy the GitHub repository contents into a new folder in the current directory called `HackerOoT`. Change into this directory before doing anything else:
|
|
|
|
```bash
|
|
cd HackerOoT
|
|
```
|
|
|
|
#### 3. Prepare a base ROM
|
|
|
|
Place a copy of the Master Quest (Debug) ROM inside the `baseroms/ntsc-1.2/` folder.
|
|
|
|
Rename the file to `baserom.z64`, `baserom.n64` or `baserom.v64`, depending on the original extension.
|
|
|
|
**NOTE:** to make a Wii VC build you will need to place a copy of the Ocarina of Time.wad file in this folder too, with the ``common-key.bin`` file. This project won't provide both.
|
|
|
|
#### 4. Setup the ROM and build process
|
|
|
|
Setup and extract everything from your ROM with the following command:
|
|
|
|
```bash
|
|
make setup
|
|
```
|
|
|
|
This downloads some dependencies (from pip), and compiles tools for the build process.
|
|
Then it generates a new ROM "baseroms/ntsc-1.2/baserom-decompressed.z64" that will have the overdump removed and the header patched.
|
|
It will also extract the individual assets from the ROM. This command will also setup F3DEX3 binaries.
|
|
|
|
**NOTE:** the decompressed baserom will be copied to ``baseroms/gc-eu-mq-dbg/``, this is a temporary solution.
|
|
|
|
#### 5. Build the ROM
|
|
|
|
Run make to build the ROM.
|
|
Make sure your path to the project is not too long, otherwise this process may error.
|
|
|
|
```bash
|
|
make
|
|
```
|
|
|
|
If all goes well, a new ROM should be built at `build/ntsc-1.2/hackeroot-ntsc-1.2.z64`.
|
|
|
|
**NOTE:** to speed up the build, you can either:
|
|
|
|
* pass `-jN` to `make setup` and `make`, where N is the number of threads to use in the build. The generally-accepted wisdom is to use the number of virtual cores your computer has.
|
|
* pass `-j` to `make setup` and `make`, to use as many threads as possible, but beware that this can use too much memory on lower-end systems.
|
|
|
|
Both of these have the disadvantage that the ordering of the terminal output is scrambled, so for debugging it is best to stick to one thread (i.e. not pass `-j` or `-jN`).
|
|
|
|
#### 6. Other targets
|
|
|
|
##### Compressing the rom
|
|
To compress the rom, run the following command:
|
|
|
|
```bash
|
|
make compress
|
|
```
|
|
|
|
##### Building for Wii VC
|
|
To build a .wad for Wii VC, run the following command:
|
|
|
|
```bash
|
|
make wad
|
|
```
|
|
|
|
**NOTE:** this is assuming you followed the instructions for Wii VC in [step 3](#3-prepare-a-base-rom).
|
|
|
|
##### Creating a BPS patch
|
|
To generate a .bps patch you can run the following command:
|
|
|
|
```bash
|
|
make patch
|
|
```
|
|
|
|
The patch will be in the ``build/ntsc-1.2/`` folder.
|
|
|
|
#### 7. Toggle HackerOoT Features
|
|
|
|
You can customize which HackerOoT features you want in your project and which not in the `include/config/` folder.
|
|
Just define the features as `true` or `false` or, if necessary, put in the value you want (e.g. Text speed).
|
|
|
|
**TIP:** if you are using VS Code, look at [vscode.md](docs/vscode.md) for useful customization that make working with this project easier. |