Update INSTALL.md
This commit is contained in:
parent
87dec7891d
commit
7a1befb261
181
INSTALL.md
181
INSTALL.md
@ -2,27 +2,14 @@
|
||||
|
||||
These instructions explain how to set up the tools required to build **tumbledemerald**, which assembles the source files into a ROM.
|
||||
|
||||
If you're just ready to compile a ROM, and you have a machine running a Debian/Ubuntu-based distro or Arch Linux:
|
||||
|
||||
```fish
|
||||
git clone https://github.com/tumbledemerald-org/te-utils.git
|
||||
cd te-utils
|
||||
cd scripts
|
||||
cd linux
|
||||
cd game
|
||||
sh pacman # if you use Debian or Ubuntu, enter "sh apt" here instead.
|
||||
```
|
||||
|
||||
For other systems, follow the manual install instructions below:
|
||||
|
||||
These instructions come with notes which can be expanded by clicking the "<i>Note...</i>" text.
|
||||
In general, you should not need to open these unless if you get an error or if you need additional clarification.
|
||||
|
||||
If you run into trouble, ask for help on Matrix (see [README.md](README.md)).
|
||||
If you run into trouble, ask for help on Matrix.
|
||||
|
||||
## Windows
|
||||
Windows has instructions for building with three possible terminals, providing 3 different options in case the user stumbles upon unexpected errors.
|
||||
- [Windows 10 (WSL1)](#windows-10-wsl1) (**Fastest, highly recommended**, Windows 10 only)
|
||||
- [Windows 10 (WSL1)](#windows-10-wsl1) (**Fastest, highly recommended**, Windows 10 and later only)
|
||||
- [Windows (msys2)](#windows-msys2) (Second fastest)
|
||||
- [Windows (Cygwin)](#windows-cygwin) (Slowest)
|
||||
|
||||
@ -35,7 +22,7 @@ Unscientific benchmarks suggest **msys2 is 2x slower** than WSL1, and **Cygwin i
|
||||
> may <a href="https://bugreports.qt.io/browse/QTBUG-86277">have problems with parsing the <code>\\wsl$</code> network drive path</a>.
|
||||
</details>
|
||||
|
||||
All of the Windows instructions assume that the default drive is C:\\. If this differs to your actual drive letter, then replace C with the correct drive letter when reading the instructions.
|
||||
All of the Windows instructions assume that the default drive is "C". If this differs to your actual drive letter, then replace C with the correct drive letter when reading the instructions.
|
||||
|
||||
**A note of caution**: As Windows 7 is officially unsupported by Microsoft and Windows 8 has very little usage, 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 instructions.
|
||||
|
||||
@ -58,7 +45,7 @@ WSL1 is the preferred terminal to build **tumbledemerald**. The following instru
|
||||
<details>
|
||||
<summary><i>Note for advanced users...</i></summary>
|
||||
|
||||
> You can pick a preferred Linux distribution, but setup instructions may differ. Debian should work with the given instructions, but has not been tested.
|
||||
> You can pick a preferred Linux distribution, but setup instructions may differ. Debian should work with the given instructions.
|
||||
</details>
|
||||
|
||||
4. Open the [Microsoft Store Linux Selection](https://aka.ms/wslstore), click Ubuntu, then click Get, which will install the Ubuntu distribution.
|
||||
@ -90,7 +77,7 @@ Some tips before proceeding:
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
|
||||
> Note: If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/pokeemerald/blob/571c598/INSTALL.md)**,which **tumbledemerald does ***not***, then follow the [legacy WSL1 instructions](docs/legacy_WSL1_INSTALL.md) from here.
|
||||
> Note: If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/tumbledemerald/blob/571c598/INSTALL.md)**, which tumbledemerald does _not_, then follow the [legacy WSL1 instructions](docs/legacy_WSL1_INSTALL.md) from here.
|
||||
|
||||
4. Certain packages are required to build tumbledemerald. Install these packages by running the following command:
|
||||
|
||||
@ -122,7 +109,7 @@ cd /mnt/c/Users/<user>/Desktop/decomps
|
||||
|
||||
If this works, then proceed to [Installation](#installation).
|
||||
|
||||
Otherwise, ask for help on Matrix (see [README.md](README.md)), or continue reading below for [Windows instructions using msys2](#windows-msys2).
|
||||
Otherwise, ask for help on Matrix, or continue reading below for [Windows instructions using msys2](#windows-msys2).
|
||||
|
||||
## Windows (msys2)
|
||||
|
||||
@ -138,12 +125,12 @@ Otherwise, ask for help on Matrix (see [README.md](README.md)), or continue read
|
||||
|
||||
Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
|
||||
|
||||
1. Open msys2 at C:\devkitPro\msys2\msys2_shell.bat.
|
||||
1. Open msys2 at C:\devkitPro\msys2\mingw64.exe or run `C:\devkitPro\msys2\msys2_shell.bat -mingw64`.
|
||||
|
||||
2. Certain packages are required to build tumbledemerald. Install these by running the following command:
|
||||
|
||||
```bash
|
||||
pacman -S make gcc zlib-devel git
|
||||
pacman -S make zlib-devel git mingw-w64-x86_64-gcc mingw-w64-x86_64-libpng
|
||||
```
|
||||
<details>
|
||||
<summary><i>Note...</i></summary>
|
||||
@ -151,39 +138,6 @@ Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
|
||||
> This command will ask for confirmation, just enter the yes action when prompted.
|
||||
</details>
|
||||
|
||||
3. Download [libpng](https://sourceforge.net/projects/libpng/files/libpng16/1.6.37/libpng-1.6.37.tar.xz/download).
|
||||
|
||||
4. Change directory to where libpng was downloaded. By default, msys2 will start in the current user's profile folder, located at **C:\Users\\⁠_\<user>_**, where *\<user>* is your Windows username. In most cases, libpng should be saved within a subfolder of the profile folder. For example, if libpng was saved to **C:\Users\\_\<user>_\Downloads** (the Downloads location for most users), enter this command:
|
||||
|
||||
```bash
|
||||
cd Downloads
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><i>Notes...</i></summary>
|
||||
|
||||
> Note 1: While not shown, msys uses forward slashes `/` instead of backwards slashes `\` as the directory separator.
|
||||
> Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "Downloads/My Downloads"`.
|
||||
> Note 3: Windows path names are case-insensitive so adhering to capitalization isn’t needed.
|
||||
> Note 4: If libpng was saved elsewhere, you will need to specify the full path to where libpng was downloaded, e.g. `cd c:/devkitpro/msys2` if it was saved there.
|
||||
</details>
|
||||
|
||||
5. Run the following commands to uncompress and install libpng.
|
||||
|
||||
```bash
|
||||
tar xf libpng-1.6.37.tar.xz
|
||||
cd libpng-1.6.37
|
||||
./configure --prefix=/usr
|
||||
make check
|
||||
make install
|
||||
```
|
||||
|
||||
6. Then finally, run the following command to change back to the user profile folder.
|
||||
|
||||
```bash
|
||||
cd
|
||||
```
|
||||
|
||||
### Choosing where to store tumbledemerald (msys2)
|
||||
At this point, you can choose a folder to store tumbledemerald into. If you're okay with storing tumbledemerald in the user profile folder, then proceed to [Installation](#installation). Otherwise, you'll need to account for where tumbledemerald is stored when changing directory to the tumbledemerald folder.
|
||||
|
||||
@ -195,7 +149,7 @@ cd Desktop/decomps
|
||||
|
||||
If this works, then proceed to [Installation](#installation).
|
||||
|
||||
Otherwise, ask for help on Matrix (see [README.md](README.md)), or continue reading below for [Windows instructions using Cygwin](#windows-cygwin).
|
||||
Otherwise, ask for help on Matrix, or continue reading below for [Windows instructions using Cygwin](#windows-cygwin).
|
||||
|
||||
## Windows (Cygwin)
|
||||
1. If devkitARM is **not installed**, then follow the instructions used to [install devkitARM](#installing-devkitarm) for the msys2 setup before continuing. *Remember to not continue following the msys2 instructions by mistake!*
|
||||
@ -263,7 +217,7 @@ Note that the directory **must exist** in Windows. If you want to store tumblede
|
||||
> Note 2: Windows path names are case-insensitive so adhering to capitalization isn't needed
|
||||
</details>
|
||||
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix (see [README.md](README.md)).
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix.
|
||||
|
||||
## macOS
|
||||
1. If the Xcode Command Line Tools are not installed, download the tools [here](https://developer.apple.com/xcode/resources/), open your Terminal, and run the following command:
|
||||
@ -333,41 +287,42 @@ Note that the directory **must exist** in the folder system. If you want to stor
|
||||
> Note: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "Desktop/decomp folder"`
|
||||
</details>
|
||||
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix (see [README.md](README.md)).
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix.
|
||||
|
||||
## Linux
|
||||
Open Terminal and enter the following commands, depending on which distro you're using.
|
||||
|
||||
### Debian/Ubuntu-based distributions
|
||||
Run the following commands to install the necessary packages:
|
||||
Run the following command to install the necessary packages:
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
|
||||
```
|
||||
Then proceed to [Choosing where to store tumbledemerald (Linux)](#choosing-where-to-store-tumbledemerald-linux).
|
||||
<details>
|
||||
<summary><i>Note for legacy repos...</i></summary>
|
||||
|
||||
> If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/pokeemerald/blob/571c598/INSTALL.md)**, which **tumbledemerald** does ***not***,
|
||||
> If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/tumbledemerald/blob/571c598/INSTALL.md)**, which tumbledemerald does _not_,
|
||||
> then you will have to install devkitARM. Install all the above packages except binutils-arm-none-eabi, and follow the instructions to
|
||||
> [install devkitARM on Debian/Ubuntu-based distributions](#installing-devkitarm-on-debianubuntu-based-distributions).
|
||||
</details>
|
||||
|
||||
### Arch Linux based systems (Arch, Manjaro, Garuda, etc.)
|
||||
Run the following commands to install the necessary packages:
|
||||
```fish
|
||||
sudo pacman -Syu
|
||||
sudo pacman -S gcc g++ make arm-none-eabi-binutils git libpng
|
||||
### Arch Linux, Manjaro, and other Arch-based distributions
|
||||
Run this command as root to install the necessary packages:
|
||||
```bash
|
||||
pacman -S base-devel arm-none-eabi-binutils git libpng
|
||||
```
|
||||
|
||||
A `pacman -Syu` is also recommended but not strictly required.
|
||||
|
||||
Then proceed to [Choosing where to store tumbledemerald (Linux)](#choosing-where-to-store-tumbledemerald-linux).
|
||||
<details>
|
||||
<summary><i>Note for legacy repos...</i></summary>
|
||||
|
||||
> If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/pokeemerald/blob/571c598/INSTALL.md)**, which **tumbledemerald** does ***not***,
|
||||
> then you will have to install devkitARM. Install all the above packages except binutils-arm-none-eabi, and follow the instructions to
|
||||
> [install devkitARM on Debian/Ubuntu-based distributions](#installing-devkitarm-on-debianubuntu-based-distributions).
|
||||
> If the repository you plan to build has an **[older revision of the INSTALL.md](https://github.com/pret/tumbledemerald/blob/571c598/INSTALL.md)**, which tumbledemerald does _not_,
|
||||
> then you will have to install devkitARM. Install all the above packages except arm-none-eabi-binutils, and follow the instructions to
|
||||
> [install devkitARM on Arch Linux](#installing-devkitarm-on-arch-linux).
|
||||
</details>
|
||||
|
||||
|
||||
### Other distributions
|
||||
_(Specific instructions for other distributions would be greatly appreciated!)_
|
||||
|
||||
@ -376,14 +331,12 @@ _(Specific instructions for other distributions would be greatly appreciated!)_
|
||||
- `g++`
|
||||
- `make`
|
||||
- `git`
|
||||
- `libpng-dev`
|
||||
- `arm-none-eabi binutils`
|
||||
- `libpng-dev` (sometimes called `libpng-devel` or just `libpng`)
|
||||
|
||||
2. Follow the instructions [here](https://devkitpro.org/wiki/devkitPro_pacman) to install devkitPro pacman. (unless you decided to use arm binutils) As a reminder, the goal is to configure an existing pacman installation to recognize devkitPro's repositories.
|
||||
2. Follow the instructions [here](https://devkitpro.org/wiki/devkitPro_pacman) to install devkitPro pacman. As a reminder, the goal is to configure an existing pacman installation to recognize devkitPro's repositories.
|
||||
3. Once devkitPro pacman is configured, run the following commands:
|
||||
|
||||
```bash
|
||||
sudo pacman -Syu
|
||||
sudo pacman -Sy
|
||||
sudo pacman -S gba-dev
|
||||
```
|
||||
@ -393,7 +346,7 @@ _(Specific instructions for other distributions would be greatly appreciated!)_
|
||||
### Choosing where to store tumbledemerald (Linux)
|
||||
At this point, you can choose a folder to store tumbledemerald (and agbcc) into. If so, you'll have to account for the modified folder path when changing directory to the tumbledemerald folder.
|
||||
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix (see [README.md](README.md)).
|
||||
If this works, then proceed to [Installation](#installation). Otherwise, ask for help on Matrix.
|
||||
|
||||
## Installation
|
||||
|
||||
@ -408,7 +361,7 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
|
||||
1. If tumbledemerald is not already downloaded (some users may prefer to download tumbledemerald via a git client like GitHub Desktop), run:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Rebirth-Devs/tumbledemerald
|
||||
git clone https://gitlab.com/tbld/game.git
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -424,15 +377,37 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
|
||||
> Where *\<folder where tumbledemerald is to be stored>* is the path of the folder [where you chose to store tumbledemerald](#Choosing-where-to-store-tumbledemerald-WSL1). Then run the `git clone` command again.
|
||||
</details>
|
||||
|
||||
2. Since agbcc is a submodule, here:
|
||||
|
||||
In the game repo:
|
||||
2. Install agbcc into tumbledemerald. The commands to run depend on certain conditions. **You should only follow one of the listed instructions**:
|
||||
- If agbcc has **not been built before** in the folder where you chose to store tumbledemerald, run the following commands to build and install it into tumbledemerald:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/pret/agbcc
|
||||
cd agbcc
|
||||
./build.sh
|
||||
./install.sh ../
|
||||
./install.sh ../tumbledemerald
|
||||
```
|
||||
|
||||
- **Otherwise**, if agbcc has been built before (e.g. if the git clone above fails), but was **last built on a different terminal** than the one currently used (only relevant to Windows, e.g. switching from msys2 to WSL1), then run the following commands to build and install it into tumbledemerald:
|
||||
|
||||
```bash
|
||||
cd agbcc
|
||||
git clean -fX
|
||||
./build.sh
|
||||
./install.sh ../tumbledemerald
|
||||
```
|
||||
|
||||
- **Otherwise**, if agbcc has been built before on the same terminal, run the following commands to install agbcc into tumbledemerald:
|
||||
|
||||
```bash
|
||||
cd agbcc
|
||||
./install.sh ../tumbledemerald
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><i>Note...</i></summary>
|
||||
|
||||
> If building agbcc or tumbledemerald results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.
|
||||
</details>
|
||||
|
||||
3. Once agbcc is installed, change directory back to the base directory where tumbledemerald and agbcc are stored:
|
||||
|
||||
@ -446,11 +421,15 @@ If you aren't in the tumbledemerald directory already, then **change directory**
|
||||
```bash
|
||||
cd tumbledemerald
|
||||
```
|
||||
To build **tumbledemerald.gba** for the first time and confirm it matches the official ROM image (Note: to speed up builds, see [Parallel builds](#parallel-builds)):
|
||||
To build **tumbledemerald.gba** (Note: to speed up builds, see [Parallel builds](#parallel-builds)):
|
||||
```bash
|
||||
make compare
|
||||
```
|
||||
If an OK is returned, then the installation went smoothly.
|
||||
If you see something like:
|
||||
```bash
|
||||
-m01 POKEMON EMER -cBPEE --silent
|
||||
```
|
||||
then the build was successful.
|
||||
<details>
|
||||
<summary>Note for Windows...</summary>
|
||||
> If you switched terminals since the last build (e.g. from msys2 to WSL1), you must run `make clean-tools` once before any subsequent `make` commands.
|
||||
@ -471,6 +450,8 @@ To speed up building, first get the value of `nproc` by running the following co
|
||||
```bash
|
||||
nproc
|
||||
```
|
||||
For example, I use Gitpod to compile the builds in releases, and the output of `nproc` there is `16`. So I would run `make -j16`.
|
||||
|
||||
Builds can then be sped up by running the following command:
|
||||
```bash
|
||||
make -j<output of nproc>
|
||||
@ -479,13 +460,6 @@ 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)).
|
||||
|
||||
## Debug info
|
||||
|
||||
To build **tumbledemerald.elf** with enhanced debug info:
|
||||
```bash
|
||||
make DINFO=1
|
||||
```
|
||||
|
||||
## devkitARM's C compiler
|
||||
|
||||
This project supports the `arm-none-eabi-gcc` compiler included with devkitARM. If devkitARM (a.k.a. gba-dev) has already been installed as part of the platform-specific instructions, simply run:
|
||||
@ -562,7 +536,25 @@ devkitARM is now installed.
|
||||
|
||||
devkitARM is now installed.
|
||||
|
||||
## Other toolchains
|
||||
### Installing devkitARM on Arch Linux
|
||||
|
||||
1. Follow [devkitPro's instructions](https://devkitpro.org/wiki/devkitPro_pacman#Customising_Existing_Pacman_Install) to configure `pacman` to download devkitPro packages.
|
||||
2. Install `gba-dev`: run the following command as root.
|
||||
|
||||
```console
|
||||
pacman -S gba-dev
|
||||
```
|
||||
This will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.
|
||||
|
||||
3. Run the following command to set devkitPro related environment variables (alternatively, close and re-open the Terminal):
|
||||
|
||||
```bash
|
||||
source /etc/profile.d/devkit-env.sh
|
||||
```
|
||||
|
||||
devkitARM is now installed.
|
||||
|
||||
### 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`.
|
||||
```bash
|
||||
@ -574,8 +566,17 @@ 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 under a modern toolchain
|
||||
|
||||
To build **tumbledemerald.elf** with debug symbols under a modern toolchain:
|
||||
```bash
|
||||
make modern DINFO=1
|
||||
```
|
||||
Note that this is not necessary for a non-modern build since those are built with debug symbols by default.
|
||||
|
||||
# Useful additional tools
|
||||
|
||||
* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps
|
||||
* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript))
|
||||
* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code/VSCodium extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript))
|
||||
* [Tilemap Studio](https://github.com/Rangi42/tilemap-studio) for viewing and editing tilemaps
|
||||
* [VSCodium](https://vscodium.com)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user