mirror of
https://github.com/pmret/papermario.git
synced 2024-11-08 20:12:30 +01:00
83 lines
3.7 KiB
Markdown
83 lines
3.7 KiB
Markdown
# Contributing
|
|
|
|
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`.
|
|
|
|
|
|
## Build System
|
|
|
|
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 `ninja`. Any errors or warnings generated by the compiler will show up in the _Problems_ tab.
|
|
|
|
|
|
## Tutorial: 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)).
|
|
|
|
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)`:
|
|
```
|
|
git clone https://github.com/matt-kempster/mips_to_c /path/to/mips_to_c
|
|
```
|
|
|
|
Here's a starter function you can use:
|
|
```sh
|
|
# don't forget to replace /path/to/mips_to_c with your path
|
|
function mipstoc() {
|
|
if [ "$#" -gt 1 ]; then
|
|
/path/to/mips_to_c/mips_to_c.py $@;
|
|
else
|
|
printf "Please call mipstoc using this format and make sure you're at the repo root:";
|
|
printf "\nmipstoc \033[0;31marg1 - the nonmatching asm file\033[0m \033[0;34marg2 - the target function\033[0m \033[0;33margN - any of the optional mips_to_c.py flags\033[0m";
|
|
printf "\nmipstoc \033[0;31m./asm/nonmatchings/code_13870_len_6980/func_8003B3D0.s\033[0m \033[0;34mfunc_8003B3D0\033[0m \033[0;33m--flag1 --flag2 --flagN\033[0m\n";
|
|
/path/to/mips_to_c/mips_to_c.py;
|
|
fi
|
|
}
|
|
export -f mipstoc
|
|
```
|
|
|
|
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.
|
|
|
|
### After matching
|
|
|
|
Once you've matched a function, run the following scripts:
|
|
|
|
```sh
|
|
$ ./coverage.py --delete-matched
|
|
$ ./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/papermario/pulls)!
|