[Return to the index](./00_index.md)
## Developer Guide

> [!TIP]
> You should use the pre-configured dev container in VSCode to ensure easy development.

Expected pre-requsites:
* [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) container environment (for dev container support).
* [VSCode](https://code.visualstudio.com/download).

### A quick start video tutorial on how to set up your environment
[![Docker Devcontainer quick start guide](http://img.youtube.com/vi/h05ufOsRgZU/0.jpg)](http://www.youtube.com/watch?v=h05ufOsRgZU "Docker Devcontainer quick start guide").

### How to debug
Within the code, use the `debugf` command, and then deploy using a debug build e.g. `make run-debug`.

```c
    debugf("joybus_rtc_detect_async: %s %s %s %s\n",
        detected ? "detected" : "not detected",
        status.stopped ? "stopped" : "running",
        status.crystal_bad ? "crystal:BAD" : "crystal:OK",
        status.battery_bad ? "battery:BAD" : "battery:OK"
    );
```
The output will then be shown within the console.

For the future:
`ms-vscode.makefile-tools` will hopefully help (installed automatically in dev container).  
NOTE: it does not yet work with `F5`: see [this blog post](https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/).  


### How to deploy and/or debug to the SC64
Make sure that your firmware is compatible (currently v2.20.2+).
See: [here](https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.20.2/docs/00_quick_startup_guide.md#firmware-backupupdate)

You will need to download a copy of the `sc64deployer` from [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.2/) or build your own depending on the scenario.

> [!TIP]
> Toggle the N64 POWER switch to load and run the ROM.

#### From within the devcontainer
##### To the native OS
It is not currently possible to directly communicate with USB devices from a devcontainer. BUT, you can use a proxy TCP/IP connection as a workaround.  
To set up a "proxy", open a terminal window on the native OS, then `cd ./tools/sc64` and then `./sc64deployer.exe server`.
Keep this terminal window open.

Then, in the dev container, use `make run` or `make run-debug`.

##### To a remote LAN device
If you want to Deploy and debug to a fully remote target (over your LAN)
Make sure that the remote target device (i.e. the one with the carts USB connected) has the server running (similar as specified in To the native OS, but):

> [!TIP]
> Make sure you specify its accessible IP and port.

```
./sc64deployer server [THE_LAN_IP_ADDRESS]:9064
```


The following commands can then be run from the docker environment terminal:

To upload and run the ROM (requires power toggle):
```
REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run
```

To debug the ROM (requires power toggle):
```
REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run-debug
```

To debug the ROM with upload and auto reboot:
(note: the current debugging session menu may not be the same as the file uploaded. you need to `make all` first to ensure the latest menu is uploaded).
```
REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run-debug-upload
```

#### Directly From your host (Windows) OS
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.2/sc64-deployer-windows-v2.20.2.zip).
* Extract and place `sc64deployer.exe` in the `tools/sc64` directory.
* Then use `make run` or `make run-debug` in the terminal.


#### To an SD Card
NOTE: A "release" version of the SC64 menu is called `sc64menu.n64` and can be generated by running `make all` or running `make sc64`. You can then copy the resulting `sc64menu.n64` file to your SD card.


### How to deploy and/or debug to other flashcarts/emulators
#### Ares Emulator
For ease of development and debugging, the N64FlashcartMenu ROM can run in the [Ares emulator](https://ares-emu.net/) (without most flashcart features).

* Ensure you have the Ares emulator on your computer.
* Load the `N64FlashcartMenu.n64` ROM.

#### Others
* Add the required file to the correct folder on your SD card.


### How to add debug code
Within the code, use the `debugf` command, and then deploy using a debug build e.g. `make run-debug`.

```c
    debugf("joybus_rtc_detect_async: %s %s %s %s\n",
        detected ? "detected" : "not detected",
        status.stopped ? "stopped" : "running",
        status.crystal_bad ? "crystal:BAD" : "crystal:OK",
        status.battery_bad ? "battery:BAD" : "battery:OK"
    );
```
The output will then be shown within the terminal.

### Using feature flags
To enable features that are not build by default, you can input flags as part of the build.
i.e. the current notible flags are:
```
FEATURE_AUTOLOAD_ROM_ENABLED
FEATURE_PATCHER_GUI_ENABLED
BETA_SETTINGS
FEATURE_DEPRECATED_FUNCTIONALITY
```
An example build command would be:
`make clean && FLAGS="-DFEATURE_PATCHER_GUI_ENABLED -DFEATURE_DEPRECATED_FUNCTIONALITY" make all`


### Update submodules
To update to the latest version, use `git submodule update --remote` from the terminal.

#### libdragon
This repo currently uses the `preview` branch as a submodule at a specific commit.
* To ensure your local instance is building against it, use `cd ./libdragon && make clobber -j && make libdragon tools -j && make install tools-install -j && cd ..`

### Generate documentation
Run `doxygen` from the dev container terminal. Make sure you fix the warnings before creating a PR!  
Generated documentation is located in the `output/docs` folder and auto-published to the `gh-pages` branch when merged with `main`.

Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/).

#### Test generated docs in the dev-container
Testing the documentation locally allows you to preview changes and ensure everything renders correctly before submitting your changes.

Install Prerequisites:
```bash
apt-get install ruby-full build-essential zlib1g-dev
gem install jekyll bundler
```

You can then serve the webpage:
```bash
cd output/docs && jekyll serve
```