185 lines
7.1 KiB
Markdown
185 lines
7.1 KiB
Markdown
# 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](README.md)).
|
|
|
|
After completing the install instructions for your OS, proceed to [Building pokeemerald-expansion](#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
|
|
- Cygwin, 30 timer slower than WSL2
|
|
|
|
**NOTE**: Only WSL systems are recommended.
|
|
|
|
[WSL Install instructions](docs/install/windows/WSL.md)
|
|
|
|
[Msys2 Install instructions](docs/install/windows/MSYS2.md)
|
|
|
|
[Cygwin Install instructions](docs/install/windows/CYGWIN.md)
|
|
|
|
## Linux
|
|
The project can be built on any Linux distribution.
|
|
Distributions with instructions:
|
|
- [Ubuntu](docs/install/linux/UBUNTU.md)
|
|
- [Debian](docs/install/linux/DEBIAN.md)
|
|
- [Arch Linux](docs/install/linux/ARCH_LINUX.md)
|
|
- [NixOS](docs/install/linux/NIXOS.md)
|
|
|
|
Other distributions have to infer what to do from [general instructions](docs/install/linux/OTHERS.md).
|
|
|
|
## Mac
|
|
Some extra considerations exist to get the testing system working.
|
|
|
|
[Mac instructions](docs/install/mac/MAC_OS.md)
|
|
|
|
## ChromeOS
|
|
Only tested on x86_64 based systems.
|
|
|
|
[Chrome OS instructions](docs/install/chromeos/CHROME_OS.md)
|
|
|
|
# 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`
|
|
|
|
```console
|
|
git clone https://github.com/rh-hideout/pokeemerald-expansion
|
|
```
|
|
3. Navigate to the newly downloaded project.
|
|
|
|
```console
|
|
cd pokeemerald-expansion
|
|
```
|
|
4. Build the project.
|
|
|
|
```console
|
|
make
|
|
```
|
|
5. If everything worked correctly, something very similar to this should be seen.
|
|
|
|
```console
|
|
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](https://www.gnu.org/software/make/manual/html_node/Parallel.html) and [this Stack Exchange thread](https://unix.stackexchange.com/questions/208568) for more information.
|
|
|
|
To speed up building, first get the value of `nproc` by running the following command:
|
|
```console
|
|
nproc
|
|
```
|
|
Builds can then be sped up by running the following command:
|
|
```console
|
|
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](https://stackoverflow.com/questions/1715580)).
|
|
|
|
### 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`.
|
|
```console
|
|
make TOOLCHAIN="/path/to/toolchain/here
|
|
```
|
|
The following is an example:
|
|
```console
|
|
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:
|
|
```console
|
|
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
|
|
```console
|
|
git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion
|
|
```
|
|
|
|
2. Pull your desired branch
|
|
There are three different options to pull from.
|
|
```console
|
|
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
|
|
```console
|
|
git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion
|
|
```
|
|
|
|
2. Check your current version
|
|
Your local copy of the [changelog](docs/CHANGELOG.md) will be updated with the version your repo is on.
|
|
|
|
3. 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.
|
|
|
|
4. Pull the target version
|
|
```console
|
|
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](https://github.com/rh-hideout/pokeemerald-expansion/tags) page, you should repeat steps 3 and 4 until you are.
|
|
|
|
# Useful additional tools
|
|
|
|
* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps
|
|
* [porytiles](https://github.com/grunt-lucas/porytiles) for add new metatiles for maps
|
|
* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript))
|
|
* [Tilemap Studio](https://github.com/Rangi42/tilemap-studio) for viewing and editing tilemaps
|