spm-decomp/CONTRIBUTING.md

# Contact

If you're interested in contributing, it's recommended you reach out to us in the #reverse-engineering channel of the [SPM Speedrunning Discord](https://discord.gg/dbd733H) first. Here you can ask for any help you might need and discuss what you plan to decompile to prevent any duplicated work.

# ppcdis

This project is build around the [ppcdis](https://github.com/SeekyCt/ppcdis) tools. These handle generation of assembly code (**you should never edit the assembly output manually**) and helpers for allowing partially-decompiled C files to match.

## YMLs

### Overrides

Overrides allow hints to be given to the analysis / disassembly to improve accuracy or work around issues. Generally you won't need to change anything about analysis (`config/analysis_overrides.yml`), though changing the disassembly is more common (`config/analysis_overrides.yml`).

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#analyser-overrides).

### Slices

`config/dol_slices.yml` / `config/rel_slices.yml` control how the disassembly is split around the decompiled C code for the dol / rel.
See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#slice-yml-format)

**You must re-run configure.py after changing this file**

### Symbols

`config/symbols.yml` controls the naming of functions and data in disassembly.

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#symbol-map)

## Generated includes

These can be generated by adding the include statement to a C file and re-running configure.py.

### Orderstrings

`#include orderstrings/XXXXXXXX_YYYYYYYY.inc` will generate a workaround for the ordering of strings in a file, with strings starting at address XXXXXXXX (inclusive) and ending at address YYYYYYYY (exclusive).

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#orderstrings)

### Orderfloats

`#include orderfloats/XXXXXXXX_YYYYYYYY.inc` will generate a workaround for the ordering of floats in a file, with floats starting at address XXXXXXXX (inclusive) and ending at address YYYYYYYY (exclusive).
`#include orderfloatsm/XXXXXXXX_YYYYYYYY.inc` will generate a 'manual' version of that (see documentation below).

`#include orderdoubles/XXXXXXXX_YYYYYYYY.inc` will generate a version of that for doubles. 'Manual' doubles are not needed for this project.

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#orderfloats)

### Jumptable

`#include jumptable/XXXXXXXX.inc` will generate a workaround for an undecompiled jumptable at address XXXXXXXX. 

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#c-jumptable-generation)

### Asm

`#include asm/XXXXXXXX.s` will generate inline assembly for an undecompiled function.

See also the [ppcdis documentation of this](https://github.com/SeekyCt/ppcdis/blob/main/TOOLS.md#inline-function-generation)

# diff.py

A setup for [asm-differ](https://github.com/simonlindholm/asm-differ/blob/main/diff.py) is included. To use it:
- First get a matching build and run expected.py
    - If you use the `-o` flag (see below), this will need to be re-ran whenever you add new source files
- You can now run `diff.py symbolName` to diff a function
- It's recommended to run it with the flags `-mwos`, see `-h` for details on these and the other flags available
- If you want to diff a function in the rel, you'll need to add the `-r` flag

# Project-Specific Tools

## decompme.py

Generates a scratch on [decomp.me](https://decomp.me/) for a function. This gives a web-based UI for editing & diffing a function, and the ability to share it with other people. Usage is `decompme.py XXXXXXXX` to upload the function at XXXXXXXX.
By default, an M2C decompiler compatible context is made, which strips definitions and macros that you have wanted included. You can replace this with a context from makectx.py (see below) after the decompiler runs if you'd like.

## getfunction.py

Gets the assembly of a single function. Usage is `getfunction.py XXXXXXXX` to get the function at XXXXXXXX.

## makectx(_m2c).py

Creates a context of all header files in the project concatenated and prints it to stdout. If using makectx_m2c, this will have the C preprocessor ran on it.