> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pret/pokeemerald/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  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.
</Tip>

<Tabs>
  <Tab title="Windows (WSL1)">
    WSL1 is the preferred terminal to build pokeemerald on Windows 10 and 11.

    <Steps>
      <Step title="Install WSL1">
        Open **Windows PowerShell as Administrator** and run:

        ```powershell theme={null}
        wsl --install -d Ubuntu --enable-wsl1
        ```

        Once the process finishes, restart your machine.
      </Step>

      <Step title="Configure Ubuntu to use WSL1">
        After restarting, open **Windows PowerShell as Administrator** again and run:

        ```powershell theme={null}
        wsl --set-version Ubuntu 1
        ```
      </Step>

      <Step title="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:

        ```bash theme={null}
        sudo apt update && sudo apt upgrade
        ```
      </Step>

      <Step title="Install required packages">
        ```bash theme={null}
        sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
        ```

        <Note>
          If the above command does not work, try replacing `apt` with `apt-get`.
        </Note>
      </Step>
    </Steps>

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

  <Tab title="Windows (msys2)">
    <Steps>
      <Step title="Install devkitARM">
        Download the devkitPro installer from [GitHub](https://github.com/devkitPro/installer/releases). Run it and, in the "Choose Components" screen, uncheck everything except **GBA Development**. Keep the install location as `C:\devkitPro`.
      </Step>

      <Step title="Open msys2">
        Open msys2 at `C:\devkitPro\msys2\msys2_shell.bat`.

        <Note>
          In msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
        </Note>
      </Step>

      <Step title="Install required packages">
        ```bash theme={null}
        pacman -Sy msys2-keyring
        pacman -S make gcc zlib-devel git
        ```
      </Step>

      <Step title="Install libpng">
        Download [libpng 1.6.37](https://sourceforge.net/projects/libpng/files/libpng16/1.6.37/libpng-1.6.37.tar.xz/download). Then change directory to where it was downloaded (e.g. `Downloads`) and run:

        ```bash theme={null}
        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:

        ```bash theme={null}
        cd
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows (Cygwin)">
    <Steps>
      <Step title="Install devkitARM">
        Follow the [devkitARM installation steps](#windows-msys2) from the msys2 tab. Do not continue with the msys2-specific instructions after installing devkitARM.
      </Step>

      <Step title="Install Cygwin">
        Download the Cygwin installer from [cygwin.com](https://cygwin.com/install.html): `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.
      </Step>

      <Step title="Configure devkitARM for Cygwin">
        Open **Cygwin** and run:

        ```bash theme={null}
        export DEVKITPRO=/cygdrive/c/devkitpro
        echo export DEVKITPRO=$DEVKITPRO >> ~/.bashrc
        export DEVKITARM=$DEVKITPRO/devkitARM
        echo export DEVKITARM=$DEVKITARM >> ~/.bashrc
        ```

        <Note>
          Replace the drive letter `c` with your actual drive letter if it is not `c`.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="macOS">
    <Steps>
      <Step title="Install Xcode Command Line Tools">
        ```bash theme={null}
        xcode-select --install
        ```
      </Step>

      <Step title="Install Homebrew and libpng">
        If [Homebrew](https://brew.sh/) is not installed, follow the instructions on the Homebrew website to install it. Then run:

        ```bash theme={null}
        brew install libpng
        ```
      </Step>

      <Step title="Install devkitARM">
        Download the `devkitpro-pacman-installer.pkg` package from [GitHub](https://github.com/devkitPro/pacman/releases) and open it to install devkitPro pacman.

        Then in the Terminal, run:

        ```bash theme={null}
        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.
      </Step>

      <Step title="Set devkitARM environment variables">
        ```bash theme={null}
        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
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Linux (Debian/Ubuntu)">
    ```bash theme={null}
    sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
    ```
  </Tab>

  <Tab title="Linux (Arch)">
    Run the following command as root:

    ```bash theme={null}
    pacman -S base-devel arm-none-eabi-binutils arm-none-eabi-newlib git libpng
    ```
  </Tab>

  <Tab title="NixOS">
    Start an interactive shell with the necessary packages:

    ```bash theme={null}
    nix-shell -p pkgsCross.arm-embedded.stdenv.cc git pkg-config libpng
    ```
  </Tab>
</Tabs>

## Cloning the repository

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

<Steps>
  <Step title="Clone pokeemerald">
    ```bash theme={null}
    git clone https://github.com/pret/pokeemerald
    ```
  </Step>

  <Step title="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:

    ```bash theme={null}
    git clone https://github.com/pret/agbcc
    cd agbcc
    ./build.sh
    ./install.sh ../pokeemerald
    ```

    After installation, return to the parent directory:

    ```bash theme={null}
    cd ..
    ```
  </Step>

  <Step title="Enter the pokeemerald directory">
    ```bash theme={null}
    cd pokeemerald
    ```

    You are now ready to build.
  </Step>
</Steps>