Add make update-dependencies

.gitignore

@@ -23,4 +23,5 @@ asm/st/*/nonmatchings/*.s
 asm/st/*/nonmatchings/*/*.s
 asm/st/*/nonmatchings/*/*/*.s
 assets/
-build/
+build/
+expected/

Makefile

@@ -214,8 +214,9 @@ ctx.c: $(M2CTX_APP)
 	$(M2CTX) $(SOURCE)
 
 require-tools: $(SPLAT_APP) $(ASMDIFFER_APP)
-update-tools: require-tools $(M2CTX_APP) $(M2C_APP)
-	pip3 install -r $(SPLAT_DIR)/requirements.txt
+update-dependencies: require-tools $(M2CTX_APP) $(M2C_APP)
+	sudo apt-get install -y $(cat tools/requirements-debian.txt)
+	pip3 install -r $(TOOLS_DIR)/requirements-python.txt
 
 $(SPLAT_APP):
 	git submodule init $(SPLAT_DIR)
@@ -244,4 +245,4 @@ SHELL = /bin/bash -e -o pipefail
 .PHONY: main, dra, ric, dre, mad, no3, np3, st0, wrp, rwrp
 .PHONY: %_dirs
 .PHONY: extract, extract_%
-.PHONY: require-tools,update-tools
+.PHONY: require-tools,update-dependencies

README.md

@@ -26,37 +26,44 @@ All the files refers to the `SLUS-00067` version of the game.
 | `3bbdd3b73f8f86cf5f6c88652e9e6452a7fb5992` | ST/RWRP.BIN | ![progress RWRP.BIN](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Xeeynamo/sotn-decomp/gh-report/assets/progress-rwrp.json)
 
 
-## How to setup the project (assuming linux ubuntu/debian or windows with WSL)
- * `sudo apt-get install gcc-mipsel-linux-gnu binutils-mips-linux-gnu`
- * `pip install spimdisasm tqdm intervaltree`
- * Inside the folder of your choice `git clone https://github.com/Xeeynamo/sotn-decomp.git`
- * `git submodule update --init`
- * Inside the newly created repo, create a new `iso/` folder, and extract the content of the game disc
+## How to setup the project (assuming Ubuntu 22.04/Debian 11 or Windows with WSL)
+
+ 1. Inside the folder of your choice `git clone https://github.com/Xeeynamo/sotn-decomp.git`
+ 1. Run `make update-dependencies`
+ 1. Inside the newly created repo, create a new `iso/` folder, and extract the content of the game disc
 
 ## How to build
- * Run `make extract` to generate the assembly files in the `asm/` directory
- * Run `make all` to compile the binaries in the `build/` directory
-you don’t need to use it now but note that `make clean` deletes the build directory
+
+ 1. Run `make extract` to generate the assembly files in the `asm/` directory
+ 1. Run `make all` to compile the binaries in the `build/` directory
+
+In case there are any changes in the `config/` folder, you might need to run `make clean` to reset the extraction.
+
 Some non-matching functions are present in the source preprocessed by the macro `NON_MATCHING`. You can still compile the game binaries by running `CPP_FLAGS=-DNON_MATCHING make`. In theory they might be logically equivalent in-game, but I cannot promise that. Few of them could match by tuning or changing the compiler.
 
 ## How to decompile
-* After setup and build, choose an overlay (eg. `ST/WRP`)
-* Look for one of those function which hasn't successfully decompiled yet (eg. `INCLUDE_ASM("asm/st/wrp/nonmatchings/6FD0", func_801873A0);`)
-* Look for its assembly file (eg. `asm/st/wrp/nonmatchings/6FD0/func_801873A0.s`)
-* Run `SOURCE=src/st/wrp/6FD0.c make ctx.c` then `ASSEMBLY=asm/st/wrp/nonmatchings/6FD0/func_801873A0.s make decompile` to dump the decompiled code into ctx.c.m2c
-* Replace the `INCLUDE_ASM(...);` you targeted with the content of `ctx.c.m2c`
-* run `make expected` and invoke `python3 ./tools/asm-differ/diff.py -mwo --overlay st/wrp func_801873A0`
+
+1. Run `make clean extract all expected` at least once
+1. After setup and build, choose an overlay (eg. `ST/WRP`)
+1. Look for one of those function which hasn't successfully decompiled yet (eg. `INCLUDE_ASM("asm/st/wrp/nonmatchings/6FD0", func_801873A0);`)
+1. Look for its assembly file (eg. `asm/st/wrp/nonmatchings/6FD0/func_801873A0.s`)
+1. Run `SOURCE=src/st/wrp/6FD0.c ASSEMBLY=asm/st/wrp/nonmatchings/6FD0/func_801873A0.s make decompile` to dump the decompiled code on the console
+1. Replace the `INCLUDE_ASM(...);` you targeted with the console output content
+1. and invoke `python3 ./tools/asm-differ/diff.py -mwo --overlay st/wrp func_801873A0`
+
 You will probably have some differences from your compiled code to the original; keep refactoring the code and move variables around until you have a 100% match.
 
 There are a few tricks to make the process more streamlined:
-* Use [decomp.me](https://decomp.me/) with GCC 2.7.2 for PS1. Be aware that the repo is using GCC 2.6.x, so decomp.me will sometimes give a slightly different output. 
-* The “context” section of decomp.me, is provided by the cmd `SOURCE=src/st/wrp/6FD0.c make ctx.c` as mentionned in the how to decompile.
-* Use [decomp-permuter](https://github.com/simonlindholm/decomp-permuter) to solve some mismatches
-* Use [this](https://github.com/mkst/sssv/wiki/Jump-Tables) and [this](https://github.com/pmret/papermario/wiki/GCC-2.8.1-Tips-and-Tricks) guide to understand how some compiler patterns work
-* Use the `#ifndef NON_MATCHING` if your code is logically equivalent but you cannot yet fully match it
+
+1. Use [decomp.me](https://decomp.me/) with GCC 2.7.2 for PS1. Be aware that the repo is using GCC 2.6.x, so decomp.me will sometimes give a slightly different output. 
+1. The “context” section of decomp.me, is provided by the cmd `SOURCE=src/st/wrp/6FD0.c make ctx.c` as mentionned in the how to decompile.
+1. Use [decomp-permuter](https://github.com/simonlindholm/decomp-permuter) to solve some mismatches
+1. Use [this](https://github.com/mkst/sssv/wiki/Jump-Tables) and [this](https://github.com/pmret/papermario/wiki/GCC-2.8.1-Tips-and-Tricks) guide to understand how some compiler patterns work
+1. Use the `#ifndef NON_MATCHING` if your code is logically equivalent but you cannot yet fully match it
 
 
 ## Resources:
+
 * List of resource for sotn https://github.com/TalicZealot/SotN-Utilities (speedrun oriented, but very useful still). 
 * PS1’s CPU R3000 instruction [manual](https://cgi.cse.unsw.edu.au/~cs3231/doc/R3000.pdf) and [cheat sheet](https://vhouten.home.xs4all.nl/mipsel/r3000-isa.html)
 * https://github.com/KernelEquinox/SNEER
@@ -66,13 +73,16 @@ There are a few tricks to make the process more streamlined:
 
 
 ## To do:
+
 The project is very barebone at the moment and there is a massive room of improvement, mostly in the infrastructure:
+
 * Not all the zone overlays (`ST/{ZONE}/{ZONE}.BIN`) are disassembled
 * Integrate ASPSX instead of GNU AS
 * Split binary data (eg. map layout, graphics, other assets) into individual files
 
 
 ## Notes
+
 * The debug room overlay `ST/MAD.BIN` was compiled earlier than the first retail release of the game. All the offsets that refers to DRA.BIN points to invalid portions of data or to the wrong API calls, effectively breaking the majority of its original functionalities. That is why the debug room does not contain any object. By compiling the debug room with make mad_fix you can restore it by redirecting the old pointers to the retail version of the game.
 Be aware that not all the offsets have been yet redirected, so it will still be not entirely functional until further update.
 * I suspect that GCC 2.6.x / PSY-Q 3.4 have been used to originally compile DRA.BIN

tools/requirements-debian.txt

@@ -0,0 +1 @@
+gcc-mipsel-linux-gnu binutils-mips-linux-gnu

tools/requirements-python.txt

@@ -0,0 +1,11 @@
+-r n64splat/requirements.txt
+pre-commit
+black
+spimdisasm>=1.7.3
+pycparser
+watchdog
+tqdm
+intervaltree
+colorama
+python-Levenshtein
+cxxfilt