Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
231 lines (129 loc) · 4.31 KB

CONTRIBUTING.md

File metadata and controls

231 lines (129 loc) · 4.31 KB

Contributing

We will be glad to answer any questions
for people who wish to contribute.

All pull requests and issues are welcome.


Before Submission

Be sure that all of your submitted code
follows the guidelines that are listed below.

When running ninja, it is REQUIRED that the output is 1:1 for a file to be marked MATCHING (otherwise the linking sequence will fail).

After the code matches, be sure to run objdiff
to check the functions to ensure that they are matching.

If it matches, it will automatically be marked as decompiled.

When each function you've matched has been marked as decompiled,
run ninja to see the current percentages.


Questions

If you have any questions or concerns,
please join our Discord server.



Requirements


Tools

  • A Disassembler / IDA Pro / Ghidra

    You can also use a decompiler, it can make some things easier

  • CodeWarrior

    We specifically use version 3.0a3

  • Python

    Version 3.7+

  • Any Code IDE (Visual Studio Code recommended) *If you are using Visual Studio Code, dtk automatically creates a compile_commands.json file that will help with clangd.


Knowledge

  • C / C++

    However C++ is recommended

  • PowerPC Assembly

  • PowerPC ➝ C / C++ reverse engineering instructions


Decompilers such as Hex-Rays (included in IDA Pro) are
useful as they can make the decompilation easier to write.



Guidelines


General


  • clang-format will do a lot of the work for you. Just be sure that it is enabled to run on save.

  • Use nullptr instead of 0 when assigning / comparing a pointer in C++ code, use NULL in C.

    Only use 0 when assigning or comparing a value.


Headers


  • Use forward-declared types when possible

  • At the top of every header place:

    #pragma once

Classes


  • Follow the proper syntax for documenting a class's functions and variables:

    /* member-offset */     s32 varName;    ///< Description of varName.
    /// @brief Function does a thing.
/// @param argumentName Is an argument to a function that does a thing.
/// @return If the function did a thing.
/// @note Might have not done a thing...
bool func(s32 argumentName);

    If there is a function that does not have this implemented (ie in headers before the new documentation revamp), please take the time to help reimplement them to document this repository better!

  • At the top of every header place:

    #pragma once

Includes


  • For system library includes use:

    #include <...>

  • For game header includes use:

    #include "..."

    These includes must be relative to the include folder.


Names


  • Names for known symbols should match exactly,
    even including typos in the symbol.

  • Member variables must be prefixed with m.

  • Arguments for functions must be prefixed with:

    • p for pointers

    • r for passed-by-reference

  • Static variables with:

    • No known symbol must be prefixed with s

    • Global scope must be prefixed with g

  • Functions with no symbols must use camelCase.

    Such as inlined functions.


Classes


  • When referencing a class member, do not use
    this->, unless it is required for compilation.

  • Functions for classes must be put in the following order:

    • Constructor

    • Destructor

    • Operators

    • Virtual Functions

    • Member Functions

    If the virtual functions are not in the order that
    they are in the vtable, then the rule above can be
    ignored as these functions must be placed in order.


Nonmatching Code

If your code does NOT match, explain in a comment why it does not match.
Be sure to also include a decomp.me scratch in a comment as well.


Types

If the function arguments in the symbol use int,
do NOT use s32, you have to use int, as they
do not mangle to the same symbol.