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

Python 3.12 is the minimum supported version for our scripts. 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 one or more symbols 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