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

# Building

> Compile pokeemerald.gba from source and verify it against the original ROM.

## Default build

From the `pokeemerald` directory, run:

```bash theme={null}
make
```

If the build succeeds, `pokeemerald.gba` will be produced in the project folder.

<Note>
  The default build uses **agbcc** — the custom GBA C compiler originally used by Game Freak — which is required to produce output that is byte-identical to the original retail ROM. The modern build (described below) uses the system `arm-none-eabi-gcc` and produces a functionally equivalent but not byte-identical ROM.
</Note>

## Parallel builds

Building with multiple CPU cores significantly reduces compile times. First, get your core count:

<Tabs>
  <Tab title="Linux / WSL">
    ```bash theme={null}
    nproc
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    sysctl -n hw.ncpu
    ```
  </Tab>
</Tabs>

Then pass that number to `make -j`:

```bash theme={null}
make -j4
```

Replace `4` with the number returned by your core-count command.

## Verify against the original

To confirm your build is byte-identical to the original Pokémon Emerald ROM, run:

```bash theme={null}
make compare
```

If it matches, you will see:

```
pokeemerald.gba: OK
```

If there are any differences from the original, you will instead see:

```
pokeemerald.gba: FAILED
shasum: WARNING: 1 computed checksum did NOT match
```

## Modern compiler build

This project also supports the `arm-none-eabi-gcc` compiler included with devkitARM. If devkitARM is installed, run:

```bash theme={null}
make modern
```

This produces `pokeemerald_modern.gba`. Build output is placed in `build/modern/` instead of `build/emerald/`.

## Debug build

To build with debug symbols under a modern toolchain:

```bash theme={null}
make modern DINFO=1
```

This produces `pokeemerald_modern.elf` with full debug symbols attached. Debug symbols are included by default in non-modern builds without needing `DINFO=1`.

## Custom toolchain

To build using a toolchain other than devkitARM, override the `TOOLCHAIN` variable with the path to your toolchain. The path must contain a `bin/` subdirectory:

```bash theme={null}
make TOOLCHAIN="/path/to/toolchain"
```

For example:

```bash theme={null}
make TOOLCHAIN="/usr/local/arm-none-eabi"
```

<Note>
  To use a custom toolchain for the `modern` target, the toolchain directory must also contain `lib/`, `include/`, and `arm-none-eabi/` subdirectories.
</Note>

## Build output

| Directory        | Contents                                                |
| ---------------- | ------------------------------------------------------- |
| `build/emerald/` | Object files for the default (agbcc) build              |
| `build/modern/`  | Object files for the modern (`arm-none-eabi-gcc`) build |

## Switching terminals on Windows

If you switch terminals between builds (for example, from msys2 to WSL1), you must run the following command once before any subsequent `make` invocations:

```bash theme={null}
make clean-tools
```

Failing to do this after switching terminals may result in build errors caused by incompatible tool binaries.

## Preserving intermediate files

By default, intermediate files (`.i` preprocessed sources and `.s` assembly files) are deleted after compilation. To keep them for inspection, set `KEEP_TEMPS=1`:

```bash theme={null}
make KEEP_TEMPS=1
```

Intermediate files will be written alongside the object files in the `build/` directory.