From ff4c1840dfaf9e8d2382a3a549edcec658e757cb Mon Sep 17 00:00:00 2001 From: Nadia Holmquist Pedersen Date: Sun, 14 Feb 2021 23:56:28 +0100 Subject: [PATCH] Update readme with relevant build instructions --- README.md | 168 ++++++------------------------------------------------ 1 file changed, 19 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index 4cd8159a..2e37b45c 100644 --- a/README.md +++ b/README.md @@ -1,157 +1,26 @@ -# Super Mario 64 +# Super Mario 64 (1996) for Nintendo DSi -- This repo contains a full decompilation of Super Mario 64 (J), (U), (E), and (SH). +- This repo contains a full decompilation of Super Mario 64 (J), (U), (E), and (SH), ported to the Nintendo DSi. - Naming and documentation of the source code and data structures are in progress. -It builds the following ROMs: - -* sm64.jp.z64 `sha1: 8a20a5c83d6ceb0f0506cfc9fa20d8f438cafe51` -* sm64.us.z64 `sha1: 9bef1128717f958171a4afac3ed78ee2bb4e86ce` -* sm64.eu.z64 `sha1: 4ac5721683d0e0b6bbb561b58a71740845dceea9` -* sm64.sh.z64 `sha1: 3f319ae697533a255a1003d09202379d78d5a2e0` - This repo does not include all assets necessary for compiling the ROMs. A prior copy of the game is required to extract the assets. -## Quick Start (for Ubuntu) - -1. Install prerequisites: `sudo apt install -y build-essential git binutils-mips-linux-gnu python3` -2. Clone the repo from within Linux: `git clone https://github.com/n64decomp/sm64.git` -3. Place a Super Mario 64 ROM called `baserom..z64` into the project folder for asset extraction, where `VERSION` can be `us`, `jp`, or `eu`. -4. Run `make` to build. Qualify the version through `make VERSION=`. Add `-j4` to improve build speed (hardware dependent). - -Ensure the repo path length does not exceed 255 characters. Long path names result in build errors. - ## Installation - -### Windows - -Install WSL and a distro of your choice following -[Windows Subsystem for Linux Installation Guide for Windows 10.](https://docs.microsoft.com/en-us/windows/wsl/install-win10) -We recommend either Debian or Ubuntu 18.04 Linux distributions under WSL. -Note: WSL1 does not currently support Ubuntu 20.04. - -Next, clone the SM64 repo from within the Linux shell: -`git clone https://github.com/n64decomp/sm64.git` - -Then continue following the directions in the [Linux](#linux) installation section below. - -### Linux - -There are 3 steps to set up a working build. - -#### Step 1: Install dependencies - -The build system has the following package requirements: - * binutils-mips - * capstone - * pkgconf - * python3 >= 3.6 - -Dependency installation instructions for common Linux distros are provided below: - -##### Debian / Ubuntu -To install build dependencies: -``` -sudo apt install -y binutils-mips-linux-gnu build-essential git libcapstone-dev pkgconf python3 -``` - -##### Arch Linux -To install build dependencies: -``` -sudo pacman -S base-devel capstone python -``` -Install the following AUR packages: -* [mips64-elf-binutils](https://aur.archlinux.org/packages/mips64-elf-binutils) (AUR) - - -##### Other Linux distributions - -Most modern Linux distributions should have equivalent packages to the other two listed above. -You may have to use a different version of GNU binutils. Listed below are fully compatible binutils -distributions with support in the makefile, and examples of distros that offer them: - -* `mips64-elf-` (Arch AUR) -* `mips-linux-gnu-` (Ubuntu and other Debian-based distros) -* `mips64-linux-gnu-` (RHEL/CentOS/Fedora) - -You may also use [Docker](#docker-installation) to handle installing an image with minimal dependencies. - -#### Step 2: Copy baserom(s) for asset extraction - -For each version (jp/us/eu) for which you want to build a ROM, put an existing ROM at -`./baserom..z64` for asset extraction. - -##### Step 3: Build the ROM - -Run `make` to build the ROM (defaults to `VERSION=us`). -Other examples: -``` -make VERSION=jp -j4 # build (J) version instead with 4 jobs -make VERSION=eu COMPARE=0 # build (EU) version but do not compare ROM hashes -``` - -Resulting artifacts can be found in the `build` directory. - -The full list of configurable variables are listed below, with the default being the first listed: - -* ``VERSION``: ``us``, ``jp``, ``eu``, ``sh`` (WIP) -* ``GRUCODE``: ``f3d_old``, ``f3d_new``, ``f3dex``, ``f3dex2``, ``f3dzex`` -* ``COMPARE``: ``1`` (compare ROM hash), ``0`` (do not compare ROM hash) -* ``NON_MATCHING``: Use functionally equivalent C implementations for non-matchings (Currently there aren't any non-matchings, but this will apply to Shindou and iQue). Also will avoid instances of undefined behavior. -* ``CROSS``: Cross-compiler tool prefix (Example: ``mips64-elf-``). - -### macOS - -With macOS, you may either use Homebrew or [Docker](#docker-installation). - -#### Homebrew - -#### Step 1: Install dependencies -Install [Homebrew](https://brew.sh) and the following dependencies: -``` -brew update -brew install capstone coreutils gcc make pkg-config tehzz/n64-dev/mips64-elf-binutils -``` - -#### Step 2: Copy baserom(s) for asset extraction - -For each version (jp/us/eu) for which you want to build a ROM, put an existing ROM at -`./baserom..z64` for asset extraction. - -##### Step 3: Build the ROM - -Use Homebrew's GNU make because the version included with macOS is too old. - -``` -gmake VERSION=jp -j4 # build (J) version instead with 4 jobs -``` - -### Docker Installation - -#### Create Docker image - -After installing and starting Docker, create the docker image. This only needs to be done once. -``` -docker build -t sm64 . -``` - -#### Build - -To build, mount the local filesystem into the Docker container and build the ROM with `docker run sm64 make`. - -##### macOS example for (U): -``` -docker run --rm --mount type=bind,source="$(pwd)",destination=/sm64 sm64 make VERSION=us -j4 -``` - -##### Linux example for (U): -For a Linux host, Docker needs to be instructed which user should own the output files: -``` -docker run --rm --mount type=bind,source="$(pwd)",destination=/sm64 --user $UID:$GID sm64 make VERSION=us -j4 -``` - -Resulting artifacts can be found in the `build` directory. + * First follow [the guide for installing devkitPro packages](https://devkitpro.org/wiki/Getting_Started), also installing the `nds-dev` group as mentioned + * Install the needed tools + * Debian/Ubuntu: `sudo apt install -y build-essential git python` + * Fedora: `sudo dnf install make git python` + * Arch/derivatives like Manjaro: `sudo pacman -S base-devel git python` + * Windows with MSYS2: `pacman -S make git python` + * Clone this repository and change to its directory + ``` + git clone https://github.com/Hydr8gon/sm64.git + cd sm64 + ``` + * Place a copy of the USA version of Super Mario 64 in this directory, named `baserom.us.z64`, it should be in the same directory as `Makefile`. + * Run `make -j$(nproc)` to build the game + * If the build succeeded, the game will be in `build/us_nds`, named `sm64.us.nds` ## Project Structure @@ -178,7 +47,8 @@ Resulting artifacts can be found in the `build` directory. │ ├── engine: script processing engines and utils │ ├── game: behaviors and rest of game source │ ├── goddard: Mario intro screen - │ └── menu: title screen and file, act, and debug level selection menus + │ ├── menu: title screen and file, act, and debug level selection menus + | └── nds: Nintendo DS-specific code ├── text: dialog, level names, act names ├── textures: skybox and generic texture data └── tools: build tools @@ -190,4 +60,4 @@ discuss what you would like to change. Run `clang-format` on your code to ensure it meets the project's coding standards. -Official Discord: [discord.gg/DuYH3Fh](https://discord.gg/DuYH3Fh) +Official Discord for the original decomp: [discord.gg/DuYH3Fh](https://discord.gg/DuYH3Fh)