Metadata-Version: 2.1
Name: freighter
Version: 0.2.1
Summary: Kai's GameCube modding library enabling C/C++ code injection into .dol executables.
Home-page: https://github.com/kai13xd/Freighter
Author: Kai (@kai13xd)
Author-email: akaisekai13@gmail.com
License: MIT License
Project-URL: Issues, https://github.com/kai13xd/Freighter/issues
Platform: UNKNOWN
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Compilers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama
Requires-Dist: dolreader
Requires-Dist: pyelftools
Requires-Dist: geckolibs

# Okay, what's Freighter?

### Hey there, Kai here.

Freighter is toolkit made for compiling C, C++, or ASM using DevkitPPC for injecting new code/data sections into GameCube/Wii \*.dol executables. This is an extension of Yoshi2's C-Kit I worked on around middle of 2019 because I was abhorred with the methods modders used abusing C.

# Credits

Yoshi2 (RenolY2)


The OG who made C-kit. He enthused about Python so I had no choice but to learn it.

[MintyMeeo](https://github.com/Minty-Meeo)

 YoshiFirebird
 This man helped me ALOT way back when I was first learning C++. He originally had the idea of using the `#pragma` keyword where C-kit would preprocess the source file and import the injection address.

# How do install?

### Make sure you are using the latest version of [Python 3.10](https://www.python.org/downloads/).

After that, simply install using `pip` on your console of choice:

- Windows: `py -m pip install freighter`
- Unix & Such: `python3 -m pip install freighter`

Dependencies should automatically be downloaded from PyPi.

## Optionals

- [Window's Terminal](https://github.com/microsoft/terminal): It's a nice command-line manager that looks modern, has tabs, and support of emoji unicode characters. ✨
- [VSCode](https://code.visualstudio.com/): My go to code editor. Supports Intellisense and it's what I exclusively use. It's got a huge list of extensions that make coding a breeze.

# What next?

Next just create a `build.py` inside your work directory and import the `Project` class.

> 🛎️NOTE: Freighter does it's best to fetch include and source folders found in the root folder. All source files found will be auto-imported into the project for compilation.

# Example build.py

Better documentation will come.. when I feel like it.

```py
from freighter import Project

# Pick your poison (compiler args)
common_args = [
    "-O3",
    "-fno-asynchronous-unwind-tables",
    "-fno-exceptions",
]

gcc_args = [
    "-std=c17",  # The C standard to compile with
]

gpp_args = [
    "-std=gnu++2b",  # The C++ standard to compile with
]

ld_args = [
    "-gc-sections",  # Runs garbage collector on unused sections
    # "-print-gc-sections", # Shows what symbols are getting thrown out
]

if __name__ == "__main__":
    # Name your project and it's GameID
    project = Project("MyMod", "GPVE01")

    # Assign compiler args to the project
    project.common_args = common_args
    project.gcc_args = gcc_args
    project.gpp_args = gpp_args
    project.ld_args = ld_args

    # Setting an entry function is essential for -gc-sections to work it's magic. Make sure this function has
    # C linkage
    project.set_entry_function("Entry")

    # If you're lucky to have a Codewarrior map, Freighter can append new symbols for debugging in Dolphin
    project.set_symbol_map("GPVE01.map")

    # You can manually define symbols in a linkerscript file.
    project.add_linkerscript("c_symbols.ld")

    # Add additional map outputs with this method
    project.add_map_output("build/files/GPVE01.map")

    # Imports manually defined symbols in .txt foles found within this folder
    project.add_symbols_folder("symbols/")

    # Use these methods so Freighter doesn't compile these files
    project.ignore_file("source/test.c")
    project.ignore_file("source/test.cpp")

    # You can also add source files explicitly if you want
    project.add_asm_file("itWork.s")
    project.add_c_file("uglyCode.c")
    project.add_cpp_file("coolHacks.cpp")

    # Write a b instruction that points to this symbol's address
    # NOTE: Symbols with C-linkage (declared extern "C") don't need their parameters within ()
    project.hook_branch("cringe", 0x800992C8)

    # Write a bl to this symbol's address at each of these addresses
    project.hook_branchlink("OnUpdateDoStuff(Game::BaseGameSection &)", 0x80102040, 0x8036D7E8, 0x80387F74)

    # Write this symbol's address to a specific location. Useful for overriding vtable pointers.
    project.hook_pointer("doMyStuffInstead(GameObject *, int)", 0x802B6708)

    # Specify the input .dol file and injection location for your code/data
    project.build("pikmin2.dol", 0x80520E00, verbose=True, clean_up=True)
```


