diff --git a/Dockerfile b/Dockerfile index 92a0729960..8f23b1df7f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -8,17 +8,14 @@ RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone & apt-get install -y \ binutils-mips-linux-gnu \ build-essential \ - pkg-config \ python3 \ python3-pip \ python3-venv \ git \ curl \ - wget \ - unzip \ clang-tidy \ clang-format \ - libpng-dev && \ + && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* diff --git a/README.md b/README.md index 4ba7d2c3d8..2155c31042 100644 --- a/README.md +++ b/README.md @@ -67,8 +67,8 @@ Some of these may also be out of date or unmaintained; usually our contributors ### 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. +[WSL Installation Guide](https://learn.microsoft.com/en-us/windows/wsl/install). +We recommend using Ubuntu as the Linux distribution. For older versions of Windows, install a Linux VM or refer to [Docker](docs/BUILDING_DOCKER.md) instructions. @@ -86,20 +86,27 @@ The build process has the following package requirements: * python3 * python3-pip * python3-venv -* libpng-dev * libxml2-dev +Python 3.10+ is required. + 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 +sudo apt-get install git build-essential binutils-mips-linux-gnu curl python3 python3-pip python3-venv libxml2-dev ``` If you are using GCC as the compiler for Ocarina of Time, you will also need: * gcc-mips-linux-gnu +which can be installed under Debian / Ubuntu with: + +```bash +sudo apt-get install 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`. @@ -119,7 +126,12 @@ cd oot #### 3. Prepare a base ROM -Place a copy of the Master Quest (Debug) ROM inside the `baseroms/gc-eu-mq-dbg/` folder. +First, pick the version of the game you want to build. +The supported versions and ROM checksums can be found in the table above. +As an example, the `ntsc-1.0` version will be used in these instructions. + +Place a copy of the ROM inside the `baseroms//` folder for your version of choice. +For example for `ntsc-1.0`, inside the `baseroms/ntsc-1.0/` folder. If you are under WSL, you can run the command `explorer.exe .` to open the current directory in the Windows file explorer. Rename the file to `baserom.z64`, `baserom.n64` or `baserom.v64`, depending on the original extension. @@ -129,11 +141,15 @@ Rename the file to `baserom.z64`, `baserom.n64` or `baserom.v64`, depending on t Setup and extract everything from your ROM with the following command: ```bash -make setup +make setup VERSION= ``` +For example for `ntsc-1.0`, run `make setup VERSION=ntsc-1.0`. + This downloads some dependencies (from pip), and compiles tools for the build process. -Then it generates a new ROM `baseroms/gc-eu-mq-dbg/baserom-decompressed.z64` that will have the overdump removed and the header patched. +Then it generates a new ROM `baseroms//baserom-decompressed.z64`. +For retail (non-debug) versions, that ROM will be the decompressed equivalent of the ROM. +For the `gc-eu-mq-dbg` version, that ROM will have the overdump removed and the header patched. It will also extract the individual assets from the ROM. #### 5. Build the ROM @@ -142,19 +158,21 @@ Run make to build the ROM. Make sure your path to the project is not too long, otherwise this process may error. ```bash -make +make VERSION= ``` -If all goes well, a new ROM should be built at `build/gc-eu-mq-dbg/oot-gc-eu-mq-dbg.z64`, and the following text printed: +For example for `ntsc-1.0`, run `make VERSION=ntsc-1.0` -```bash -build/gc-eu-mq-dbg/oot-gc-eu-mq-dbg.z64: OK +If all goes well, a new ROM should be built at `build//oot-.z64` (for example `build/ntsc-1.0/oot-ntsc-1.0.z64`), and the following text printed: + +``` +build//oot-.z64: OK ``` If you instead see the following: -```bash -build/gc-eu-mq-dbg/oot-gc-eu-mq-dbg.z64: FAILED +``` +build//oot-.z64: FAILED md5sum: WARNING: 1 computed checksum did NOT match ``` @@ -169,7 +187,10 @@ Both of these have the disadvantage that the ordering of the terminal output is ## Changing build options -The project Makefile is fairly configurable and can be used to build other versions of the game or prepare the repo for modding. +By default, if you don't specify a version to build with `VERSION=` in the make commands, the `gc-eu-mq-dbg` version is used. +This default can be changed in the Makefile. + +The project Makefile is fairly configurable and can also be used to prepare the repo for modding. See the options outlined at the top of the Makefile for more information. ## Contributing diff --git a/docs/BUILDING_MACOS.md b/docs/BUILDING_MACOS.md index 8d2f67458e..f6bb2391bf 100644 --- a/docs/BUILDING_MACOS.md +++ b/docs/BUILDING_MACOS.md @@ -10,7 +10,6 @@ For macOS, use Homebrew to install the following dependencies: * coreutils * make * python3 -* libpng * bash * clang-format * libxml2 @@ -20,7 +19,7 @@ You can install them with the following commands: ```bash brew update -brew install coreutils make python3 libpng bash clang-format libxml2 libiconv +brew install coreutils make python3 bash clang-format libxml2 libiconv ``` (The repository expects Homebrew-installed programs to be either linked correctly in `$PATH` etc. or in their default locations.) @@ -43,8 +42,8 @@ cd ~/binutils-tmp Get and extract binutils source ```bash -curl -O https://ftp.gnu.org/gnu/binutils/binutils-2.35.tar.bz2 -tar xjf binutils-2.35.tar.bz2 +curl -O https://ftp.gnu.org/gnu/binutils/binutils-2.46.0.tar.xz +tar xjf binutils-2.46.0.tar.xz ``` Create and enter a build directory @@ -55,7 +54,7 @@ cd build-binutils Configure the build ```bash -../binutils-2.35/configure --target=mips-linux-gnu --prefix=/opt/cross --with-system-zlib --disable-gprof --disable-gdb --disable-werror +../binutils-2.46.0/configure --target=mips-linux-gnu --prefix=/opt/cross --with-system-zlib --disable-gprof --disable-gdb --disable-werror ``` Make and install binutils @@ -90,7 +89,7 @@ If you'd like to compile with GCC instead of IDO (e.g. for modding), you can bui Install dependences ```bash -brew install gcc@14 gmp isl libmpc mpfr +brew install gcc@15 gmp isl libmpc mpfr ``` Create and enter local working dir @@ -101,8 +100,8 @@ cd ~/gcc-tmp Get and extract gcc source ```bash -curl -O https://ftp.gnu.org/gnu/gcc/gcc-14.2.0/gcc-14.2.0.tar.xz -tar xvf gcc-14.2.0.tar.xz +curl -O https://ftp.gnu.org/gnu/gcc/gcc-15.2.0/gcc-15.2.0.tar.xz +tar xvf gcc-15.2.0.tar.xz ``` Create and enter a build directory @@ -113,12 +112,12 @@ cd build-gcc Configure the build ```bash -CC=gcc-14 CXX=g++-14 ../gcc-14.2.0/configure --target=mips-linux-gnu --prefix=/opt/cross --disable-nls --enable-languages=c --with-gmp=$(brew --prefix)/opt/gmp --with-mpfr=$(brew --prefix)/opt/mpfr --with-mpc=$(brew --prefix)/opt/libmpc --with-isl=$(brew --prefix)/opt/isl +CC=gcc-15 CXX=g++-15 ../gcc-15.2.0/configure --target=mips-linux-gnu --prefix=/opt/cross --disable-nls --enable-languages=c --with-gmp=$(brew --prefix)/opt/gmp --with-mpfr=$(brew --prefix)/opt/mpfr --with-mpc=$(brew --prefix)/opt/libmpc --with-isl=$(brew --prefix)/opt/isl ``` Make and install gcc ```bash -CC=gcc-14 CXX=g++-14 make all-gcc -j$(nproc) +CC=gcc-15 CXX=g++-15 make all-gcc -j$(nproc) sudo make install-gcc ```