Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Instructions

Install instructions for each supported operating system can be found in their respective directories under docs/install/. Lines to those can be found under each heading. This file only contains a short introduction to each supported system. If you run into trouble, ask for help on Discord (see README.md).

After completing the install instructions for your OS, proceed to Building pokeemerald-expansion.

Windows

Windows needs one of the systems to build the project

A note of caution: As Windows 7 and Windows 8 are officially unsupported by Microsoft, some maintainers are unwilling to maintain the Windows 7/8 instructions. Thus, these instructions may break in the future with fixes taking longer than fixes to the Windows 10/11 instructions.

On Windows, the project can be built using the following systems:

  • WSL2, fastest
  • WSL1, 7 times slower than WSL2
  • Msys2, 20 times slower than WSL2 (NOTE: Currently broken on pret upstream)
  • Cygwin, 30 timer slower than WSL2 (NOTE: Currently broken on pret upstream)

NOTE: Only WSL systems are recommended.

WSL Install instructions

Msys2 Install instructions

Cygwin Install instructions

Linux

The project can be built on any Linux distribution. Distributions with instructions:

Other distributions have to infer what to do from general instructions.

Mac

Some extra considerations exist to get the testing system working.

Mac instructions

ChromeOS

Only tested on x86_64 based systems.

Chrome OS instructions

Building pokeemerald-expansion

Follow these steps to build pokeemerald-expansion.

  1. Navigate to the directory you want to keep the project in, be aware of any system specific limitations.

  2. Download pokeemerald-expansion with git

    git clone https://github.com/rh-hideout/pokeemerald-expansion

  3. Navigate to the newly downloaded project.

    cd pokeemerald-expansion

  4. Build the project.

    make

  5. If everything worked correctly, something very similar to this should be seen.

    arm-none-eabi-ld: warning: ../../pokeemerald.elf has a LOAD segment with RWX permissions
Memory region         Used Size  Region Size  %age Used
           EWRAM:      243354 B       256 KB     92.83%
           IWRAM:       30492 B        32 KB     93.05%
             ROM:    26072244 B        32 MB     77.70%
cd build/modern && arm-none-eabi-ld  -T ../../ld_script_modern.ld --print-memory-usage -o ../../pokeemerald.elf <objs> <libs> | cat
tools/gbafix/gbafix pokeemerald.elf -t"POKEMON EMER" -cBPEE -m01 -r0 --silent
arm-none-eabi-objcopy -O binary pokeemerald.elf pokeemerald.gba
tools/gbafix/gbafix pokeemerald.gba -p --silent

    And the build ROM will be in the directory as pokeemerald.gba.

Building guidance

Parallel builds

See the GNU docs and this Stack Exchange thread for more information.

To speed up building, first get the value of nproc by running the following command:

nproc

Builds can then be sped up by running the following command:

make -j<output of nproc>

Replace <output of nproc> with the number that the nproc command returned.

nproc is not available on macOS. The alternative is sysctl -n hw.ncpu (relevant Stack Overflow thread).

Other toolchains

To build using a toolchain other than devkitARM, override the TOOLCHAIN environment variable with the path to your toolchain, which must contain the subdirectory bin.

make TOOLCHAIN="/path/to/toolchain/here

The following is an example:

make TOOLCHAIN="/usr/local/arm-none-eabi"

To compile the modern target with this toolchain, the subdirectories lib, include, and arm-none-eabi must also be present.

Building with debug info

To build pokeemerald.elf with debug symbols and debug-compatible optimization under a modern toolchain:

make debug

Choosing a branch

pokeemerald-expansion has different branches that users can decide to use.

Latest Patch

This option will have all officially released expansion functionality and bugfixes.

master

The master branch has all of the functionality from "Latest Patch", as well as any bugfixes that have been discovered since that release.

upcoming

The master branch has all of the functionality from "Latest Patch", as well as any functionality that has been added since that release.

The bugfixes on master are occasionally merged into upcoming, but there is no official cadence.

Migrating from pokeemerald

  1. Set RHH as a git remote
git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion
  1. Pull your desired branch There are three different options to pull from.
git pull RHH master # if you've chosen to use the upcoming branch, replace the word master with upcoming. 
# If you've chosen the latest patch, replace the word master with expansion
# If you've chosen Latest Patch, replace the word master with expansion/1.11.0 where 1.11.0 is replaced with whatever the latest released version is.

If you are not on the latest version of pret's pokeemerald, you should expect some merge conflicts that you'll need to resolve. Once complete, you'll be using pokeemerald-expansion.

Updating pokeemerald-expansion

  1. Set RHH as a git remote
git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion

  1. Check your current version Your local copy of the changelog will be updated with the version your repo is on.

  2. Select a target version We recommend incrementally updating to the next version using the following order below. If you are on a version older than 1.6.2, you should target 1.6.2..

    • 1.6.2
    • 1.7.4
    • 1.8.3
    • 1.9.4
    • 1.10.3

For example, if your version is 1.7.0, you should update to 1.7.4.

  1. Pull the target version
git pull RHH expansion/X.Y.Z # Replace X, Y and Z with the target version, such as `1.9.3`, `master`, or `upcoming`.

You may have merge conflicts that you need to resolve.

If you targeted a specific version that is not the latest version listed on the tags page, you should repeat steps 3 and 4 until you are.

Useful additional tools