pmret/papermario
1
0
Fork 0
mirror of https://github.com/pmret/papermario.git synced 2024-11-18 00:42:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #25 from nanaian/readme-arch

Browse Source 
update readme and add install script
This commit is contained in:
Ethan Roseman 2020-08-17 13:25:27 -04:00 committed by GitHub
commit 6901860e16
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 171 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
README.md Normal file
View File

@ -0,0 +1,110 @@
# Paper Mario
This is a WIP decompilation of Paper Mario (USA). It builds the following ROM:
* papermario.z64 `md5: a722f8161ff489943191330bf8416496`
Discord: [Paper Mario Modding](https://discord.gg/urUm3VG)
## Setup
You'll need Linux, a Linux VM, or Windows 10 (WSL) to work on this project.
#### Clone the repository
```sh
$ git clone https://github.com/ethteck/papermario.git
$ cd papermario
```
#### Install build dependencies
```sh
$ ./install.sh
```
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!
#### 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).
## Contributing
### Dependencies
There are a few additional dependencies needed when contributing to this project. You can install them with `./install.sh --extra`.
### Rebuilding
Setting the `PM_HEADER_REBUILD` environment variable will cause `make` to rebuild all `.c` files whenever a `.h` file is modified.
```sh
$ PM_HEADER_REBUILD=1 make
```
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.
### Matching a function
#### Setup
Once you've created a successful (`OK`) build, copy `build/` to `expected/build/`:
```sh
$ mkdir -p expected
$ cp -r build expected
```
#### 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.
Take the relevant `.s` file and pass it to [mips_to_c](https://github.com/matt-kempster/mips_to_c) ([web version](https://simonsoftware.se/other/mips_to_c.py)).
If mips_to_c gives you an error about branch-likely instructions, edit the `.s` file and rename any branch-likely instructions to their unlikely equivalent (i.e. remove the `l` suffix). Add a `nop` after the branches and move the instruction that was originally in the delay slot (directly after the branch instruction) to the start of the target label. Don't commit the edited assembly.
Open up the relevant `.c` file and replace the function's `INCLUDE_ASM` macro with the output from mips_to_c. Run the following command to attempt to compile, replacing `function_name` with the name of the function you're working with:
```sh
./diff.py -mwo function_name
```
Fix any errors and rerun `diff.py`. This will involve typing the function signature correctly, which you will probably find in [Star Rod's library database](https://github.com/nanaian/star-rod/blob/master/database/common_func_library.lib). See also [common_structs.h](include/common_structs.h).
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
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.
## FAQ
* If you received the following error when running `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
>
> This is a Windows line ending issue run `git checkout checksum.sha1` to fix it.

61
Readme.md
View File

@ -1,61 +0,0 @@
# Paper Mario Decompilation
## Setup
### Requirements
You'll need Linux or Windows 10 (WSL) to work on this project.
### Dependencies
* *mips-linux-gnu binutils: You may be able to just download this via your package manager (`sudo apt install binutils-mips-linux-gnu`), or you'll have to build it yourself. (guide todo)
#### Ubuntu and co (easy mode):
For a quick and easy way to install all relevant decomp-related tools on Ubuntu and other similar distros,
```
sudo apt install -y binutils-mips-linux-gnu build-essential pkg-config python3 python3-pip wget git clang-tidy clang-format nano vbindiff zlib1g-dev libyaml-dev libcapstone-dev
```
#### Building mips-linux-gnu
todo
### Fork and clone the repo
Click the "fork" button in the top right corner of the main repo's webpage (https://github.com/ethteck/papermario) to fork this repo to your own GitHub account. After this, clone the repo to your computer via the command below:
`git clone https://github.com/YOUR_GITHUB_USERNAME/papermario.git`
### The Rom
You'll need a US Paper Mario rom to work on this project. Copy it into the root directory of the repository with the name `baserom.z64`.
### Make setup
run `make setup` to set up tools and extract the rom
### Make
run `make` to rebuild the rom. Get `OK`? If so, you're all set! Otherwise, please feel free to reach out to us in the discord.
Use `PM_HEADER_REBUILD=1 make` to rebuild C sources when any header files change.
## FAQ
* If you received the following error when running `make setup`:
```
/bin/bash: mips-linux-gnu-as: command not found
Makefile:92: recipe for target 'build/asm/boot.o' failed
make: *** [build/asm/boot.o] Error 127
```
> 💡 Solution
>
> One of the packages from the _Ubuntu and co (easy mode)_ script did not install correctly. Elevate your user permissions using `sudo su`, run the script again and append `--fix-missing` to it.
>
<br />
<br />
* If you received the following error when running `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
>
> This is a Windows line ending issue run `git checkout checksum.sha1` to fix it.

61
install.sh Executable file
View File

@ -0,0 +1,61 @@
#!/bin/sh
# Ubuntu
if command -v apt-install &> /dev/null; then
echo "Installing packages for Ubuntu"
sudo apt install -y git build-essential binutils-mips-linux-gnu zlib1g-dev libcapstone-dev libyaml-dev || exit 1
if [[ $1 == "--extra" ]]; then
echo "Installing extra"
sudo apt install -y python3 python3-pip clang-tidy clang-format
python3 -m pip install stringcase
fi
echo "Done"
exit
fi
# Arch
if command -v pacman &> /dev/null; then
echo "Installing packages for Arch"
# Upgrade existing packages (note: no --noconfirm)
sudo pacman -Syu || exit 1
# Install dependencies
sudo pacman -S --noconfirm --needed git base-devel zlib capstone libyaml || exit 1
# Install binutils if required
if ! command -v mips-linux-gnu-ar &> /dev/null; then
PKG="mips-linux-gnu-binutils"
if command -v aura &> /dev/null; then
sudo aura -A --noconfirm $PKG || exit 1
elif command -v yay &> /dev/null; then
yay -S --noconfirm $PKG || exit 1
elif command -v yaourt &> /dev/null; then
sudo yaourt -S --noconfirm $PKG || exit 1
else
echo "AUR manager not found, installing $PKG without one"
git clone "https://aur.archlinux.org/$PKG.git" || exit 1
cd $PKG
makepkg -si || exit 1
cd ..
rm -rf $PKG
fi
fi
if [[ $1 == "--extra" ]]; then
echo "Installing extra"
sudo pacman -S --noconfirm --needed python python-pip clang || exit 1
python3 -m pip install stringcase || exit 1
fi
echo "Done"
exit
fi
echo "Only Ubuntu (apt) and Arch Linux (pacman) are supported by install.sh."
echo "Please consider contributing and adding an installation script for your distro."
exit 1