Tools

Most helper scripts are located in /tools. Some are downloaded automatically by ninja (through download_tool.py), and these will appear in /build/tools.

Ninja targets

Command	Result
ninja	Build Matching objects and link main.elf
ninja all_source	Build Matching and NonMatching objects without linking
ninja diff	If the DOL checksum is invalid, prints a diff of the mismatch
ninja baseline	Sets the current state of function progress for later use with changes or changes_all. Stored in build/GALE01/baseline.json
ninja changes	Prints all functions that have been broken since the baseline. A broken function was 100% and is now less.
ninja changes_all	Prints all functions whose progress has gone down since the baseline.
ninja -t clean	Cleans (deletes) all files produced by Ninja. Generally it is preferably to delete build/GALE01 instead.

Python tools

Most of our tools are written in Python. Many of them are a part of our build system, dtk-template.

Installing dependencies

It's recommended that you create a virtual environment in your melee directory. If it's named venv or .venv it will be ignored by git.

If you are missing a Python module when executing one of our tools, look for that module's name in the txt files in the /reqs directory. Once you've found it, install the requirements with pip:

pip install -r reqs/misc.txt

Generating stubs in headers and source files

/tools/scaffold.py will fill a .c file with a doc comment, or a .h file with a placeholder declaration, for each function. Accepts multiple paths.

Example using bash substitution

tools/scaffold.py src/melee/gm/gm_1601.{c,h}

Rust tools

Several of our tools are built in Rust using the Cargo workspaces feature. To compile and run one of these tools, ensure Cargo is installed and then run:

cargo run -rqp <package-name> -- [args]

The flags are -r (release, not debug), -q (quiet, suppress output from cargo itself), and -p (package name, from the workspace). Refer to the Cargo documentation for further information. These tools can also be compiled into userspace binaries using Cargo install.

Renaming symbols

To rename a symbol project-wide, run:

cargo run -rqp melee-replace-symbols -- [args]

This tool takes a series of replacements in the form of FROM:TO. You can pass the path of a text file to receive input from, or "-" (or leave it empty) to receive from stdin.

Examples

Multiple replacements, one line

echo 'fn_DEADBEEF:myNamedFunction lbl_12345678:someCallback' | cargo run -rqp melee-replace-symbols -- -

Multiple lines using cat

cat <<EOF | cargo run -rqp melee-replace-symbols -- -            
fn_DEADBEEF:myNamedFunction
lbl_12345678:someCallback
EOF

Using a text file

cargo run -rqp melee-replace-symbols -- build/replacements.txt

replacements.txt:

fn_DEADBEEF:myNamedFunction
lbl_12345678:someCallback