papermario/CONTRIBUTING.md

84 lines
3.5 KiB
Markdown
Raw Normal View History

2021-01-15 17:28:05 +01:00
# Contributing
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
Thank you for your interest in contributing to this project!
## Dependencies
2020-12-24 09:38:37 +01:00
There are a few additional dependencies needed when contributing to this project. You can install them with `./install.sh --extra`.
2021-01-15 17:28:05 +01:00
## 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`.
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
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.
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
## Tutorial: Matching a function
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
### Setup
2020-12-24 09:38:37 +01:00
Once you've created a successful (`OK`) build, copy `ver/us/build/` to `ver/us/expected/build/`:
2020-12-24 09:38:37 +01:00
```sh
./make_expected.sh
2020-12-24 09:38:37 +01:00
```
(If you're working with other versions of the game, replace `us` in the file paths.)
2021-01-15 17:28:05 +01:00
### Roughly converting assembly to C
2020-12-24 09:38:37 +01:00
Decide on a function to match. These can be found in the subdirectories of `ver/us/asm/nonmatchings/`.
2020-12-24 09:38:37 +01:00
Take the relevant `.s` file and pass it to [mips_to_c](https://github.com/matt-kempster/mips_to_c) ([online version](https://simonsoftware.se/other/mips_to_c.py)).
2020-12-24 09:38:37 +01:00
Splat refactor (#257) * all non-world rodata migrated * data disasm * kinda working * updated yaml * bloop * linker header * configure 2.0 * bin * mass rename to remove code_ * pause rename * battle partner stuff * whew * more renames * more renames * more renaming * it builds! * updates * remove main prefix * one more thing * crc, yay0 * .data, .rodata, .bss * img * dead_atan2 * it buildsgit add -A * split battle/partner/6FAD10 * rm &s on sleepy_sheep syms * sha1sum ninja rule description * OK but commented out PaperMarioMapFS and PaperMarioNpcSprites * uncomment * fix mapfs * match func_8003CFB4 * . * clean up and name npc_iter_no_op * npc.c * enable cc warnings * name npc_find_near * use singular options.asset_path * smores * cc_dsl only when needed * kinda fix configure for splat refactor2 * ok! * new msg format * remove old msg format docs * slight bug fixes, splat adjustment * git subrepo pull (merge) --force tools/splat subrepo: subdir: "tools/splat" merged: "cfc140bb76" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "cfc140bb76" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" * git subrepo pull (merge) --force tools/splat subrepo: subdir: "tools/splat" merged: "85349befcd" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "85349befcd" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" * Update symbol addrs * git subrepo pull tools/splat subrepo: subdir: "tools/splat" merged: "a44631e194" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "a44631e194" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" Co-authored-by: Alex Bates <hi@imalex.xyz>
2021-04-13 09:47:52 +02:00
Open up the `.c` file that uses your function and replace the function's `INCLUDE_ASM` macro with the output from mips_to_c. For example, for a function `asm/nonmatchings/FOO/func_DEADBEEF`:
```diff
Splat refactor (#257) * all non-world rodata migrated * data disasm * kinda working * updated yaml * bloop * linker header * configure 2.0 * bin * mass rename to remove code_ * pause rename * battle partner stuff * whew * more renames * more renames * more renaming * it builds! * updates * remove main prefix * one more thing * crc, yay0 * .data, .rodata, .bss * img * dead_atan2 * it buildsgit add -A * split battle/partner/6FAD10 * rm &s on sleepy_sheep syms * sha1sum ninja rule description * OK but commented out PaperMarioMapFS and PaperMarioNpcSprites * uncomment * fix mapfs * match func_8003CFB4 * . * clean up and name npc_iter_no_op * npc.c * enable cc warnings * name npc_find_near * use singular options.asset_path * smores * cc_dsl only when needed * kinda fix configure for splat refactor2 * ok! * new msg format * remove old msg format docs * slight bug fixes, splat adjustment * git subrepo pull (merge) --force tools/splat subrepo: subdir: "tools/splat" merged: "cfc140bb76" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "cfc140bb76" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" * git subrepo pull (merge) --force tools/splat subrepo: subdir: "tools/splat" merged: "85349befcd" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "85349befcd" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" * Update symbol addrs * git subrepo pull tools/splat subrepo: subdir: "tools/splat" merged: "a44631e194" upstream: origin: "https://github.com/ethteck/splat.git" branch: "master" commit: "a44631e194" git-subrepo: version: "0.4.3" origin: "https://github.com/ingydotnet/git-subrepo" commit: "2f68596" Co-authored-by: Alex Bates <hi@imalex.xyz>
2021-04-13 09:47:52 +02:00
// src/FOO.c
- INCLUDE_ASM("FOO", func_DEADBEEF);
+ s32 func_DEADBEEF() {
+ // ...
+ }
2020-12-24 09:38:37 +01:00
```
Compile the ROM:
2020-12-24 09:38:37 +01:00
```sh
ninja
2020-12-24 09:38:37 +01:00
```
This will probably end up either `FAIL`ing (the resulting ROM does not match the baserom), or the compilation of the C file you just modified did not succeed. mips_to_c loves to use void pointers and weird syntax that won't compile properly. Fixing this will involve typing the function signature correctly, which you may find in [Star Rod's library database](https://github.com/nanaian/star-rod/blob/master/database/common_func_library.lib). For structs, see [common_structs.h](include/common_structs.h).
Once the C file compiles, you can compare the assembly generated by your code versus the original assembly with the following command, replacing `function_name` with the name of the function you're working on:
2020-12-24 09:38:37 +01:00
```sh
./diff.py -mwo function_name
```
(Sometimes, `-mwo` doesn't work. We don't know why yet; use `-mw` if you encounter issues.)
2020-12-24 09:38:37 +01:00
`diff.py` displays the difference between the original game's assembly (on the left) and what your C code generated (on the right).
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
### Matching the function
2020-12-24 09:38:37 +01:00
You're on your own now. Get your C code compiling to match the original assembly! `diff.py`, when running with `-m`, 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.)
2020-12-24 09:38:37 +01:00
If you have any questions or encounter any issues, we suggest:
- Reaching out [on Discord](https://discord.gg/urUm3VG)
- Using [decomp permuter](https://github.com/simonlindholm/decomp-permuter) if your code is logically equivalent
- Wrapping what you have in `#ifdef NON_MATCHING` (see other examples of this in the codebase) and trying a smaller function
2020-12-24 09:38:37 +01:00
2021-01-15 17:28:05 +01:00
### After matching
2020-12-24 09:38:37 +01:00
Once you've matched a function, run the following:
2020-12-24 09:38:37 +01:00
```sh
./coverage.py --delete-matched
2020-12-24 09:38:37 +01:00
```
Then, go ahead and [create a pull request](https://github.com/pmret/papermario/pulls)!