melonds-ds/CONTRIBUTING.md

Contributing to melonDS DS

Thanks for your interest in contributing to melonDS DS! There are many ways you can help improve the project, even if you're not a coder.

Contributing Upstream

First and foremost, you can help improve melonDS DS by contributing to the underlying emulator that this project is based on; since parity with standalone melonDS is a priority for melonDS DS, most improvements to the original emulator will eventually make their way here.

Reporting Issues

Found a bug? Have a feature request? You can open a ticket by going here and following the instructions -- or if your issue is something I already know about, you can comment on an existing ticket with details about how it affects you.

Having a record of bugs or feature requests helps me keep my backlog organized and plan long-term improvements to the project, so don't be shy!

When reporting a bug, you'll usually want to include supporting information. Here are some common artifacts that I may ask for:

Logs

Usually, providing a log when reporting a bug or asking for help can eliminate a lot of blind guesswork. When in doubt, include a log.

See here for guidance on generating a log with RetroArch. Instructions may vary for other libretro frontends.

Traces

melonDS DS supports the Tracy frame profiler, which is a great way to diagnose performance issues. Having a Tracy capture can help me learn more about:

You can take a trace with the following steps:

1. Download a Tracy-enabled build of melonDS DS for your platform from the Releases or a GitHub Actions artifact. These builds have RelWithDebInfo in the name.
2. Install the Tracy-enabled build of melonDS DS in place of your normal build.
3. Download, install, and launch Tracy.
4. If you're running RetroArch on a different device than you're running Tracy, enter the device's IP address in the "client address" field.
5. Launch RetroArch with the Tracy-enabled core. The trace will start automatically, and the Tracy window should start updating immediately.
6. Perform the actions that you want to profile (i.e. do the thing that's causing the slowdown).
7. Close RetroArch to stop the trace.
8. Save the trace to a file, then attach it to the relevant ticket.

Note

For most platforms, running RetroArch (or any Tracy-instrumented app) with admin privileges will allow Tracy to capture extra data. However, the resulting trace will contain personal information about everything else that's running on your system.

If you capture a trace with elevated privileges, don't post it publicly. Send it to me privately instead.

Translating Text

melonDS DS is only available in English right now, but support for other languages is planned. Once the infrastructure for that is in place, you'll be able to help translate melonDS DS through libretro's Crowdin project.

Sponsorship

Spare change burning a hole in your bank account? Sponsoring me through GitHub Sponsors is a great way to say thanks! melonDS DS is a passion project that will always be free to use (just like the original emulator), but I'm always grateful for financial support! The fine people behind melonDS and RetroArch certainly wouldn't mind, either.

Note

Right now I can't guarantee specific benefits for sponsors, but I will reevaluate that stance if I see a sustained desire for it.

Spreading the Word

If you enjoy using melonDS DS, you can help me out by spreading the good word! Tweet it, stream it, invite me on your podcast, book a television ad -- whatever you think will help. The more people who use the project, the more likely one of them will want to contribute (and the more joy it'll bring to players)!

Contributing Code

Submitting improvements to melonDS DS is a great way to help out, but it also requires the most attention and coordination. I don't want to see your hard work go to waste, so if there's something specific you want to work on then I strongly recommend you run it by me beforehand.

Installing Dependencies

You will need to install the following beforehand:

• CMake 3.19 or later
• Git
• A C++17 compiler (MSVC is not supported)

Most other dependencies are fetched automatically by CMake.

Windows

1. Install MSYS2.

2. Open the MSYS2 MinGW 64-bit terminal from the Start Menu.

3. Install dependencies like so:

   pacman -Syu # update the package database
   pacman -S git mingw-w64-x86_64-{cmake,toolchain} # install dependencies
   

4. Proceed to Compilation. You may need to remain in the MSYS2 terminal.

macOS

1. Install Homebrew.

2. Install dependencies like so:

   brew install cmake git pkg-config cmake
   

3. Install Xcode and the Xcode command-line tools.

4. Proceed to Compilation.

Note

macOS builds exclude OpenGL by default, as the OpenGL renderer doesn't currently work on the platform. To enable it anyway, pass -DENABLE_OPENGL=ON to CMake.

Linux

1. Install dependencies like so:

   sudo apt install cmake git pkg-config # Ubuntu/Debian
   sudo pacman -S base-devel cmake extra-cmake-modules git # Arch Linux
   

2. Proceed to Compilation.

Android

1. Install the Android SDK and NDK. The simplest way to do this is through Android Studio.
2. Proceed to Compilation.

iOS

These steps can only be done on macOS.

1. Install Xcode and the Xcode command-line tools.
2. Proceed to Compilation.

Compilation

Once you've installed the dependencies, the process for building melonDS DS is mostly the same on all platforms:

git clone https://github.com/JesseTG/melonds-ds
cd melonds-ds
cmake -B build # Generate the build system, and add any -D or --toolchain flags here
cmake --build build # Build the project

However, some platforms or features need you to add some extra flags to the first cmake command:

macOS

If building for the macOS architecture that your device uses, no extra flags are required. To produce a build for a specific architecture, pass -DCMAKE_OSX_ARCHITECTURES:STRING=$ARCH to the initial cmake command, where $ARCH is one of the following:

• x86_64 for x86_64 builds.
• arm64 for Apple Silicon builds.
• x86_64;arm64 for universal builds.

Warning

Universal builds of melonDS DS are not supported, as there is a history of them not working reliably.

Android

You'll need to add the following flags to build for Android.

• --toolchain=...: The path to the android.toolchain.cmake file in your NDK installation. The location varies depending on how you installed the NDK; it will most likely be in $ANDROID_NDK/build/cmake.
• -DANDROID_ABI=...: The ABI to build for. This should be arm64-v8a or x86_64. If in doubt, use arm64-v8a.
• -DANDROID_PLATFORM=...: The Android API level to target. The minimum level supported by melonDS DS is 24.

You should also use the version of cmake that the NDK includes.

Here's an example configure step for cmake on Windows. This command uses the NDK-bundled toolchain to prepare a 64-bit ARM build for Android API level 24.

PS C:\Users\Jesse\Projects\melonds-ds> $Env:ANDROID_SDK_ROOT\cmake\3.22.1\bin\cmake.exe `
    -DANDROID_ABI=arm64-v8a `
    -DANDROID_PLATFORM=24 `
    -DCMAKE_TOOLCHAIN_FILE=$Env:ANDROID_NDK\build\cmake\android.toolchain.cmake

The command will be more or less the same on other platforms, but the paths will be different.

See here for more information about these and other Android-specific CMake variables.

iOS/tvOS

You will need to add the following flags to build for iOS or tvOS:

• --toolchain=./cmake/toolchain/ios.toolchain.cmake: The path to the ios.toolchain.cmake that's bundled with melonDS DS.
• -DPLATFORM=...: The target platform to build for. Use OS64 for iOS and TVOS for tvOS. See cmake/toolchain/ios.toolchain.cmake for more information about the available CMake variables that this toolchain defines.
• -DDEPLOYMENT_TARGET=...: The minimum SDK version to target. The minimum level supported by melonDS DS is 14.

Tracy Integration

melonDS DS supports the Tracy frame profiler. To enable it, add -DTRACY_ENABLE=ON to the initial cmake command. For best results, build with the RelWithDebInfo configuration by adding -DCMAKE_BUILD_TYPE=RelWithDebInfo when running cmake.

Customizing the Build

These are some of the most important CMake variables that can be used to configure the build. To see the rest, run cmake -LH in the build directory.

Variable	Description
ENABLE_OPENGL	Whether to build the OpenGL renderer. Defaults to ON on Windows and Linux, OFF on other platforms.
TRACY_ENABLE	Enables the Tracy frame profiler.
MELONDS_REPOSITORY_URL	The Git repo from which melonDS will be cloned. Set this to use a fork.
MELONDS_REPOSITORY_TAG	The melonDS commit to use in the build.
FETCHCONTENT_SOURCE_DIR_MELONDS	Path to a copy of the melonDS repo on your system. Set this to use a local branch instead of cloning.
LIBRETRO_COMMON_REPOSITORY_URL	The Git repo from which libretro-common will be cloned. Set this to use a fork.
LIBRETRO_COMMON_REPOSITORY_TAG	The libretro-common commit to use in the build.

See here and here for more information about the variables that CMake and its modules define; these can also be used to customize the build.

Getting Your Patch Merged

Remember, I ultimately have to maintain whatever changes you submit. Submissions that complicate this would harm melonDS DS in the long run, so I will be picky about what gets merged.

That said, I want you to succeed! If you come to me in advance with your idea, I can guide you towards a solution that everyone can be happy with -- or at least prevent you from wasting time on a non-starter.

Here are some rules and guidelines you'll need to follow as you implement your contribution:

Tests

melonDS DS has a suite of tests to ensure that most of the core works as expected. The tests will automatically be run on the CI pipeline when new commits are pushed.

Tip

You are strongly encouraged to run the test suite locally, as doing so will help you catch issues early and speed up iteration. See here for instructions on doing so.

All builds must succeed and all test cases must pass for your contribution to be merged, barring exceptional circumstances.

You encouraged to write new tests if doing so makes sense for your contribution (and libretro.py supports it) -- I may even ask you to do so as a condition of merging.

Note that tests are only run on GitHub Actions -- they are not run on libretro's build infrastructure.

Style

There isn't currently a style guide for the codebase (C++ or otherwise). But I do have some rules you'll need to follow:

• Do not introduce new dependencies unless absolutely necessary.
• If you do need to introduce a new dependency, then fetch it at configure-time with FetchContent instead of vendoring it. See here for more details.
• All C++ code (including dependencies) must be built as C++17.
• All text should use Semantic Line Breaks (aka SemBr), including comments and string literals in the code. It helps with readability and version control.
• Please update documentation and comments as you work, if relevant to your changes.