diff --git a/.gitignore b/.gitignore index 80a660d77d..54e0d3226d 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ venv/ .DS_Store ctx.c expected/ -settings.mk .vscode/launch.json # Build artifacts @@ -17,6 +16,7 @@ build.ninja *.ld *.z64 *.Yay0 +*.msg.h /build/ /docs/doxygen/ /include/ld_addrs.h diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 1b8575b6cd..6060022c79 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -2,9 +2,9 @@ "version": "2.0.0", "tasks": [ { - "label": "make", + "label": "ninja", "type": "shell", - "command": "PM_HEADER_REBUILD=1 make all", + "command": "ninja", "problemMatcher": [ { "fileLocation": ["relative", "${workspaceFolder}"], @@ -35,7 +35,7 @@ { "label": "diff", "type": "shell", - "command": "PM_HEADER_REBUILD=1 ./diff.py -mwo ${input:funcName}", + "command": "./diff.py -mwo ${input:funcName}", "isBackground": true, "problemMatcher": [ { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56234054c1..412af57536 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,22 @@ -## Contributing +# Contributing -### Dependencies +Thank you for your interest in contributing to this project! + +## Dependencies There are a few additional dependencies needed when contributing to this project. You can install them with `./install.sh --extra`. -### WSL -We provide [windows_terminal.bat](tools/windows_terminal.bat) to open a [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) with a recommended layout. Make sure a default distro (e.g. `wsl --set-default ubuntu`) is set beforehand. +## Build System -### Rebuilding +You will need to re-run `./configure.py` whenever `splat.yaml` or the number of source files changes (e.g. a function is matched and its `.s` file is removed). If you `git pull` and `ninja` breaks, you probably need to re-run `./configure.py`. -If you use Visual Studio Code, you can use _Run Build Task_ (Ctrl+Shift+B) to run `make`. Any errors or warnings generated by the compiler will show up in the _Problems_ tab. +If you use Visual Studio Code, you can use _Run Build Task_ (Ctrl+Shift+B) to run `ninja`. Any errors or warnings generated by the compiler will show up in the _Problems_ tab. -### Matching a function -#### Setup +## Tutorial: Matching a function + +### Setup Once you've created a successful (`OK`) build, copy `build/` to `expected/build/`: @@ -23,7 +25,7 @@ $ mkdir -p expected $ cp -r build expected ``` -#### Roughly converting assembly to C +### Roughly converting assembly to C Decide on a function to match. These can be found in the subdirectories of `asm/nonmatchings/`. Currently, functions which use float constants, data sections, or jump tables are unmatchable. @@ -31,9 +33,7 @@ Take the relevant `.s` file and pass it to [mips_to_c](https://github.com/matt-k You can also use mips_to_c locally installed to a destination of your choice. Then register a function in `~/.bashrc` that calls `path/to/mips_to_c.py (with args)`: ``` -sudo apt update -sudo apt install python3-pip -sudo git clone https://github.com/matt-kempster/mips_to_c.git path/to/mips_to_c +git clone https://github.com/matt-kempster/mips_to_c /path/to/mips_to_c ``` Here's a starter function you can use: @@ -62,13 +62,13 @@ Fix any errors and rerun `diff.py`. This will involve typing the function signat Once a successful build is made, `diff.py` will show you the difference between the original game's assembly (on the left) and what your C code generated (on the right). -#### Matching the function +### Matching the function You're on your own now. Get your C code compiling to match the original assembly! `diff.py`, when running, will automatically recompile your code whenever you save the `.c` file. If you use Visual Studio Code, you can use _Run Test Task_ to run `diff.py` and show you errors and warnings from the compiler inline. You might want to attach _Run Test Task_ to a keybinding, as you'll be using it often. -#### After matching +### After matching Once you've matched a function, run the following scripts: @@ -78,3 +78,5 @@ $ ./format.sh ``` If `format.sh` has any problems with your code, go and fix the issues. If you can't fix a warning without making the function not match anymore, append `// NOLINT` to the offending line. + +Then, please [create a pull request](https://github.com/pmret/nananian/pulls)! diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000000..60707d768b --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,62 @@ +# Setup + +This repository supports: + +- [Linux](#unix) +- [macOS](#unix) +- [Windows Subsystem for Linux 2](#wsl-2) +- [Docker](#docker) (any host OS) + +If you encounter any issues setting up the repo, please feel free to [reach out to us on Discord](https://discord.gg/urUm3VG). + + +## Unix + +Clone the repository: +```sh +git clone https://github.com/pmret/papermario +cd papermario +``` + +Install build dependencies: +```sh +./install.sh +``` + +Copy a Paper Mario (USA) ROM into the root directory of the repository with the name `baserom.z64`. If you're using WSL, you can enter the Linux filesystem by opening `\\wsl$` in File Explorer; e.g. `\\wsl$\Ubuntu\home\\papermario`. + +Configure the build and extract assets from the base ROM: +```sh +./configure.py +``` + +Compile the game: +``` +ninja +``` + +If you get `papermario.z64: OK` at the end, the build succeeded! + +The output ROM is `papermario.z64` - you can run this in any N64 emulator. + + +## WSL 2 + +1. Install or upgrade to **WSL 2** following [these instructions](https://aka.ms/wsl2-install) (Ubuntu is recommended) +2. Open a WSL terminal +3. Run the following command: `sudo apt update && sudo apt upgrade && cd ~` +4. Continue with [the instructions for Linux](#unix) + +If you have Visual Studio Code, you can type `code .` to open the repo within it. +`Ctrl + J` opens up a Linux terminal within VS Code. + + +## Docker + +A Docker image containing all dependencies can be built and ran as follows: +```sh +docker build . -t pm +docker run --rm -ti -v $(pwd):/papermario pm +``` + +Then continue with [the instructions for Linux](#unix). diff --git a/Jenkinsfile b/Jenkinsfile index af83a1eed5..5da835cee9 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -18,6 +18,7 @@ pipeline { } steps { sh 'python3 progress.py --csv >> /var/www/papermar.io/html/reports/progress.csv' + sh 'python3 progress.py --shield-json >> /var/www/papermar.io/html/reports/progress_shield.json' } } } diff --git a/README.md b/README.md index d599574a5f..bc37b29312 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,22 @@ # Paper Mario -This is a WIP decompilation of Paper Mario (USA). It builds the following ROM: +[![Build Status][jenkins-badge]][jenkins] [![Progress][progress-badge]][progress] [![Discord Channel][discord-badge]][discord] -* papermario.z64 `md5: a722f8161ff489943191330bf8416496` +[jenkins]: https://jenkins.zelda64.dev/job/papermario/job/master +[jenkins-badge]: https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fjenkins.zelda64.dev%2Fjob%2Fpapermario%2Fjob%2Fmaster -Discord: [Paper Mario Modding](https://discord.gg/urUm3VG) +[progress]: https://papermar.io/progress +[progress-badge]: https://img.shields.io/endpoint?url=https://papermar.io/reports/progress_shield.json -## Setup +[discord]: https://discord.gg/urUm3VG +[discord-badge]: https://img.shields.io/discord/279322074412089344?color=%237289DA&logo=discord&logoColor=ffffff -You'll need Linux, a Linux VM, or [Windows 10 (WSL2)](#wsl) to work on this project. +This is a work-in-progress decompilation of Paper Mario (USA). -#### Clone the repository -```sh -$ git clone https://github.com/ethteck/papermario.git -$ cd papermario -``` +It builds the following ROM: -#### Install build dependencies +* [**papermario.z64**](https://datomatic.no-intro.org/index.php?page=show_record&s=24&n=0537) `sha1: 3837f44cda784b466c9a2d99df70d77c322b97a0` -```sh -$ ./install.sh -``` +To set up the repository, see [INSTALL.md](INSTALL.md). -Our install script does not yet support distros other than Ubuntu, Arch, and their derivatives. Please consider contributing to the script if you use another distro! - -##### Docker - -A Docker image containing all dependencies can be built and ran as follows: -```sh -# build image -$ docker build . -t pm -# spin up container, mounting current directory inside -$ docker run --rm -ti -v $(pwd):/papermario pm -``` - -#### Base ROM - -You'll need a Paper Mario (USA) ROM to work on this project. Copy it into the root directory of the repository with the name `baserom.z64`. - -#### Install tools and extract ROM - -```sh -$ make setup -``` - -### Compile the game - -```sh -$ make -``` - -If you get `OK`, you're all set! Otherwise, please feel free to reach out to us in [our Discord channel](https://discord.gg/urUm3VG). - -## Star Rod GUI - -You can open [our modified version of Star Rod](https://github.com/nanaian/star-rod-for-decomp) with `make editor`. - -## Contributing Please see [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to the project. Any and all help is welcome! - -## Troubleshooting - -* If you are using Windows, you may encounter the following when you run `make`: -``` -sha1sum -c checksum.sha1 -sha1sum: 'papermario.z64'$'\r': No such file or directory -: FAILED open or read -sha1sum: WARNING: 1 listed file could not be read -Makefile:118: recipe for target 'verify' failed -make: *** [verify] Error 1 -``` -> 💡 Solution - -> Run `git checkout checksum.sha1` and retry building. Windows has different line endings than Linux, causing some of our tools to break. diff --git a/configure.py b/configure.py index 4fa510881d..1b4257b062 100755 --- a/configure.py +++ b/configure.py @@ -153,12 +153,6 @@ async def main(): cpp = args.cpp or "cpp" - """ - # update submodules - await shell("git submodule init tools/n64splat") - await shell("git submodule update --recursive") - """ - # compile n64splat dependencies await shell("make -C tools/n64splat") diff --git a/progress.py b/progress.py index 8db0ceac63..1eb10aa80c 100755 --- a/progress.py +++ b/progress.py @@ -79,6 +79,16 @@ def main(args): csv_list = [str(version), timestamp, git_hash, str(len(all_funcs)), str(len(nonmatching_funcs)), str(len(matching_funcs)), str(total_size), str(nonmatching_size), str(matching_size)] print(",".join(csv_list)) + elif args.shield_json: + import json + + # https://shields.io/endpoint + print(json.dumps({ + "schemaVersion": 1, + "label": "progress", + "message": f"{matching_ratio:.2f}%", + "color": "yellow", + })) else: if matching_size + nonmatching_size != total_size: print("Warning: category/total size mismatch!\n") @@ -89,6 +99,7 @@ def main(args): if __name__ == "__main__": parser = argparse.ArgumentParser(description="Reports progress for the project") parser.add_argument("--csv", action="store_true") + parser.add_argument("--shield-json", action="store_true") args = parser.parse_args() main(args) diff --git a/requirements_extra.txt b/requirements_extra.txt index bed63f8773..6fa8c3bcf3 100644 --- a/requirements_extra.txt +++ b/requirements_extra.txt @@ -3,3 +3,4 @@ cxxfilt python-Levenshtein stringcase watchdog +gitpython diff --git a/tools/windows_terminal.bat b/tools/windows_terminal.bat deleted file mode 100644 index 3bca3f8137..0000000000 --- a/tools/windows_terminal.bat +++ /dev/null @@ -1,2 +0,0 @@ -REM first set your default distro using: wsl --set-default -wt --title "diff.py" -d "../" ; split-pane -d "../" -V ; new-tab --title "mips_to_c.py" -d "../" ; focus-tab -t 0