Developer Guide

Remarks: You should use the pre-configured dev container in VSCode to ensure easy development.

Expected pre-requsites:

Docker or Podman container environment (for dev container support).
VSCode.

A quick start video tutorial on how to set up your environment

.

How to debug

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

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.

How to deploy and/or debug to the SC64

Make sure that your firmware is compatible (currently v2.20.2+). See: here

You will need to download a copy of the sc64deployer from here or build your own depending on the scenario.

Remarks: 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):

Remarks: 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.
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 (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.

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.

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:

apt-get install ruby-full build-essential zlib1g-dev

gem install jekyll bundler

You can then serve the webpage:

cd output/docs && jekyll serve