Port docs from PH

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 - [Project structure](#project-structure)
 - [Decompiling](#decompiling)
 - [Code style](#code-style)
-- [Creating new `.c`/`.cpp` files](#creating-new-ccpp-files)
+<!-- - [Creating new `.c`/`.cpp` files](#creating-new-ccpp-files) -->
 
 ## Project structure
 - `build/`: Build output

INSTALL.md

@@ -5,7 +5,7 @@ Contents:
 - [Prerequisites](#prerequisites)
 - [Build the ROM](#build-the-rom)
     - [Matching the base ROM](#matching-the-base-rom)
-    - [Building with non-matching code](#building-with-non-matching-code)
+    <!-- - [Building with non-matching code](#building-with-non-matching-code) -->
 - [[Optional] LSP setup](#lsp-setup)
 
 ## Prerequisites
@@ -40,6 +40,8 @@ Now you can run `ninja` to build a ROM for the chosen version.
 > [!NOTE]
 > For Linux users: Wibo is used by default. If you want to use Wine instead, run `configure.py` with `-w <path/to/wine>`.
 
+## Build the ROM
+
 ### Matching the base ROM
 
 **This is optional!** You only need to follow these steps if you want a matching ROM.

README.md

@@ -9,8 +9,7 @@ The Legend of Zelda: Spirit Tracks
 [Discord Badge]: https://img.shields.io/discord/688807550715560050?color=%237289DA&logo=discord&logoColor=%23FFFFFF
 [discord]: https://discord.com/invite/DqwyCBYKqf/
 
-**Work in progress!** This project aims to recreate source code for ***The Legend of Zelda: Spirit Tracks*** by decompiling its code by hand. **The repository does not contain assets or assembly code.** To build the ROM, you must own an existing
-copy of the game to extract assets from.
+**Work in progress!** This project aims to recreate source code for ***The Legend of Zelda: Spirit Tracks*** by decompiling its code by hand. **The repository does not contain assets or assembly code.** To build the ROM, you must own an existing copy of the game to extract assets from.
 
 > [!NOTE]
 > The project targets the European and Japanese versions, and other versions might be supported later.

docs/decompiling.md

@@ -0,0 +1,104 @@
+# Decompiling
+This document describes how you can start decompiling code and contribute to the project. Feel free to ask for help if you get
+stuck or need assistance.
+- [Pick a source file](#pick-a-source-file)
+- [Decompiling a source file](#decompiling-a-source-file)
+- [Decompiling a function](#decompiling-a-function)
+- [Decompiling `.init` functions](#decompiling-init-functions)
+- [The Ghidra project](#the-ghidra-project)
+
+## Pick a source file
+A reservation sheet exists for a list of delinked source files that are ready to be decompiled. This list grows as more source files are delinked from the rest of the base ROM. You can request access to the sheet in the ZeldaRet discord [channels for ST](https://discord.com/channels/688807550715560050/1453177153502969977) (you can join the server with [this invite link](https://discord.gg/6tjntnU8hC)).
+
+You can claim a source file (called an "actor") by filling in the "Reserved by" column. Once you started decompilation, create a PR on the ST repository for the actor you're decompiling. The decomp-dev bot will follow your PR and give information about the decompilation progress of your code.
+
+<!-- TODO -->
+If you want to unclaim the file, <!-- leave another comment so we can be certain that the source file is available to be claimed again. -->
+Remember to make a pull request of any progress you made on the source file, whether it is just header files or partially decompiled code.
+
+## Decompiling a source file
+We use the object diffing tool [`objdiff`](https://github.com/encounter/objdiff) to track differences between our decompiled C++ code and the base ROM's code.
+1. [Download the latest release.](https://github.com/encounter/objdiff/releases/latest)
+1. Run `configure.py <eur|usa>` and `ninja` to generate `objdiff.json` in the repository root (don't forget to follow the instructions in [INSTALL.md](../INSTALL.md) first).
+1. In `objdiff`, set the project directory to the repository root (it should load `objdiff.json` itself).
+   1. [WSL only] If you're using WSL (which is possible), navigate to the project directory with window's directory picker tool and select
+1. Select your source file in the left sidebar:  
+![List of objects in objdiff](https://github.com/zeldaret/ph/blob/main/docs/images/objdiff_objects.png)
+1. See the list of functions and data to decompile:  
+![List of symbols in objdiff](images/objdiff_symbols.png)
+
+> [!NOTE]
+> If a source file is missing in `objdiff`, or `objdiff` fails to build a file, first rerun `ninja` to update `objdiff.json`.
+> If the problem persists, feel free to ask for help.
+
+## Decompiling a function
+Once you've opened a source file in `objdiff`, you can choose to decompile the functions in any order. We recommend starting
+with a small function if you're unfamiliar with decompilation. Here's an example:
+
+![Function in objdiff](images/objdiff_function.png)
+
+As a starting point, we look at the decompiler output in Ghidra. You can request access to our shared Ghidra project [in this section](#the-ghidra-project).
+
+![Decompiler in Ghidra](images/ghidra_decomp.png)
+
+Looking at this output, we might try writing something like this:
+```cpp
+ARM bool Actor::Drop(Vec3p *vel) {
+    if (mGrabbed) {
+        mVel     = *vel;
+        mGrabbed = false;
+        return true;
+    }
+    return false;
+}
+```
+
+Now we can go back to `objdiff` and look at the result:
+
+![Matching function in objdiff](images/objdiff_match.png)
+
+Success! Note that this was a simple example and that you'll sometimes get stuck on a function. In that case, try the
+following:
+- Decompile a different function and come back later.
+- Export to [decomp.me](https://decomp.me/):
+    1. Press the `decomp.me` button in `objdiff`.
+    1. Once you're sent to `decomp.me`, go to "Options" and change the preset to "Phantom Hourglass".
+    1. Paste your code into the "Source code" tab.
+    1. Share the link with us!
+
+## Decompiling `.init` functions
+> [!NOTE]
+> This section will be updated as we learn more about global objects. Feel free to contribute or provide us with more
+> information!
+
+Functions in the `.init` section are static initializers. Their purpose is to call C++ constructors on global objects, and to
+register destructors so the global objects can be destroyed when their overlay unloads.
+
+Static initializers are generated implicitly and do not require us to write any code ourselves. So, to generate one, you must
+define a global variable by using a constructor.
+
+If the static initializer calls `__register_global_object`, that means the global object has a destructor. This means you'll
+have to declare a destructor if it doesn't exist already.
+
+Another consequence of having a destructor is that a `DestructorChain` object will be added to the `.bss` section. This struct
+is 12 (`0xc`) bytes long and is also implicit, so we don't need to define it ourselves.
+
+> [!IMPORTANT]
+> An important thing to keep in mind is that a static initializer can construct multiple global objects.
+
+## Decompiling data
+> [!NOTE]
+> Under construction! It's not fully clear how data is decompiled, as the compiler is strict on how it orders global variables.
+> Feel free to contribute to this section or provide us with more information!
+
+Other than `.text` and `.init` which contain code, there are the following sections for data:
+- `.rodata`: Global or static constants
+- `.data`: Global or static variables
+- `.bss`/`.sbss`: Global or static uninitialized variables
+
+You can see examples of these data sections in the [compilation section in `build_system.md`](/docs/build_system.md#compiling-code).
+
+## The Ghidra project
+We use a shared Ghidra project to analyze the game and decompile functions. To gain access to the project, install
+[Ghidra version 11.2.1](https://github.com/NationalSecurityAgency/ghidra/releases/tag/Ghidra_11.2.1_build) and request access
+from @aetias on Discord.