Installation

Set up the build environment for pokeemerald on Windows, macOS, or Linux.

Prerequisites

Choose the tab for your platform and follow the steps to install the required packages.

On Windows, WSL1 is the recommended option — it is the fastest terminal for building pokeemerald. msys2 is approximately 2x slower than WSL1, and Cygwin is 5–6x slower.

Windows (WSL1)

WSL1 is the preferred terminal to build pokeemerald on Windows 10 and 11.

1. Install WSL1

   Open Windows PowerShell as Administrator and run:

   wsl --install -d Ubuntu --enable-wsl1
   

   Once the process finishes, restart your machine.

2. Configure Ubuntu to use WSL1

   After restarting, open Windows PowerShell as Administrator again and run:

   wsl --set-version Ubuntu 1
   
3. Set up Ubuntu

   Open Ubuntu (e.g. via Search). WSL will complete its first-time setup and prompt you to create a username and password.

   Then update the system:

   sudo apt update && sudo apt upgrade
   
4. Install required packages

   sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
   

   If the above command does not work, try replacing apt with apt-get.

All Windows instructions assume the default drive is C:\. If your drive letter differs, replace C with the correct letter throughout these instructions.

Windows (msys2)

1. Install devkitARM

   Download the devkitPro installer from GitHub. Run it and, in the “Choose Components” screen, uncheck everything except GBA Development. Keep the install location as C:\devkitPro.

2. Open msys2

   Open msys2 at C:\devkitPro\msys2\msys2_shell.bat.

   In msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.

3. Install required packages

   pacman -Sy msys2-keyring
   pacman -S make gcc zlib-devel git
   
4. Install libpng

   Download libpng 1.6.37. Then change directory to where it was downloaded (e.g. Downloads) and run:

   tar xf libpng-1.6.37.tar.xz
   cd libpng-1.6.37
   ./configure --prefix=/usr
   make check
   make install
   

   Then return to the user profile folder:

   cd
   

Windows (Cygwin)

1. Install devkitARM

   Follow the devkitARM installation steps from the msys2 tab. Do not continue with the msys2-specific instructions after installing devkitARM.

2. Install Cygwin

   Download the Cygwin installer from cygwin.com: setup-x86_64.exe for 64-bit, setup-x86.exe for 32-bit.

   During setup, at Select Packages, set the view to Full and select the following packages:

   • make
   • git
   • gcc-core
   • gcc-g++
   • libpng-devel

   Double-click Skip next to each package to select the latest version, then complete the installation.

3. Configure devkitARM for Cygwin

   Open Cygwin and run:

   export DEVKITPRO=/cygdrive/c/devkitpro
   echo export DEVKITPRO=$DEVKITPRO >> ~/.bashrc
   export DEVKITARM=$DEVKITPRO/devkitARM
   echo export DEVKITARM=$DEVKITARM >> ~/.bashrc
   

   Replace the drive letter c with your actual drive letter if it is not c.

macOS

1. Install Xcode Command Line Tools

   xcode-select --install
   
2. Install Homebrew and libpng

   If Homebrew is not installed, follow the instructions on the Homebrew website to install it. Then run:

   brew install libpng
   
3. Install devkitARM

   Download the devkitpro-pacman-installer.pkg package from GitHub and open it to install devkitPro pacman.

   Then in the Terminal, run:

   sudo dkp-pacman -Sy
   sudo dkp-pacman -S gba-dev
   sudo dkp-pacman -S devkitarm-rules
   

   When prompted for package selection during the gba-dev step, press Enter to install all packages, then enter Y to confirm.

4. Set devkitARM environment variables

   export DEVKITPRO=/opt/devkitpro
   echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc
   export DEVKITARM=$DEVKITPRO/devkitARM
   echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc
   
   echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile
   

Linux (Debian/Ubuntu)

sudo apt install build-essential binutils-arm-none-eabi git libpng-dev

Linux (Arch)

Run the following command as root:

pacman -S base-devel arm-none-eabi-binutils arm-none-eabi-newlib git libpng

NixOS

Start an interactive shell with the necessary packages:

nix-shell -p pkgsCross.arm-embedded.stdenv.cc git pkg-config libpng

Cloning the repository

Once your environment is set up, clone the source and build the custom GBA C compiler (agbcc).

1. Clone pokeemerald

   git clone https://github.com/pret/pokeemerald
   
2. Clone and build agbcc

   agbcc is the custom GBA C compiler required for a byte-identical build. Clone it into the same directory as pokeemerald, then build and install it:

   git clone https://github.com/pret/agbcc
   cd agbcc
   ./build.sh
   ./install.sh ../pokeemerald
   

   After installation, return to the parent directory:

   cd ..
   
3. Enter the pokeemerald directory

   cd pokeemerald
   

   You are now ready to build.