mirror of https://github.com/pret/pokeemerald.git
Partially work on the new Install.MD.
Todo: - Legacy Windows instructions - macOS, Linux instructions - figure out what to do with the base_tools note for macOS - dkp installation instructions for platforms which do not install dkp.
This commit is contained in:
luckytyphlosion
parent
51e8b8b8db
commit
90d8bb1d33
171
INSTALL.md
171
INSTALL.md
|
|
@ -1,82 +1,170 @@
|
|||
# Prerequisites
|
||||
# Instructions
|
||||
|
||||
| Linux | macOS | Windows 10
|
||||
| - | - | -
|
||||
| none | [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl]
|
||||
These instructions explain how to set up the tools required to build **pokeemerald**, which assembles the source files into a ROM.
|
||||
|
||||
[xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html
|
||||
[terminal]: https://docs.microsoft.com/windows/terminal/get-started
|
||||
[wsl]: https://docs.microsoft.com/windows/wsl/install-win10
|
||||
If you run into trouble, ask for help on IRC or Discord (see [README.md](README.md)).
|
||||
|
||||
Independently from the specific OS, make sure that the `gcc`, `g++`, `make`, `git`, and `libpng-dev` packages or their equivalents are installed and accessible to the development tools that are used by the project (this means that, for example, on Windows, the packages have to be installed in the WSL environment). The package names and installation methods may vary with each OS.
|
||||
## Windows 10
|
||||
WSL1 is the preferred terminal to build **pokeemerald**. The following instructions will explain how to install WSL1. These steps can be skipped if WSL1 is already installed.
|
||||
|
||||
Install the devkitARM toolchain of devkitPro as per [the instructions on their wiki](https://devkitpro.org/wiki/devkitPro_pacman). On Windows, follow the Linux instructions inside WSL as any steps about the Windows installer do not apply.
|
||||
### Installing WSL1
|
||||
Open [Windows Powershell **as Administrator**](https://i.imgur.com/QKmVbP9.png), and run the following command (Shift+Insert is paste in the terminal).
|
||||
```
|
||||
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
|
||||
```
|
||||
Once the process finishes, restart your machine.
|
||||
|
||||
**Debian-based distro users:** This applies to Debian, Ubuntu, and similar distros, including in WSL. If necessary, install the `libarchive13`, `pkg-config`, and `gdebi-core` packages to be able to install devkitPro.
|
||||
The next step is to choose and install a Linux distribution from the Microsoft Store. The following instructions will assume Ubuntu as the Linux distribution of choice. Advanced users can pick a preferred Linux distribution, but build instructions may differ.
|
||||
|
||||
**Windows 10 users:** WSL 2 is available in the 1903 release (build 18362) and later, therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button or press `Win`+`X`, choose Run, and run `ms-settings:about` to determine the Windows version. Also check Windows Update to make sure your installation is up-to-date.
|
||||
Open the [Microsoft Store Linux Selection](https://aka.ms/wslstore), click Ubuntu, then click Get, which will install the Ubuntu distribution. If the link does not work, then open the Microsoft Store manually, and search for the Ubuntu app (choose the one with no version number).
|
||||
|
||||
**Windows 7 and 8.1 users:** pret is no longer focusing on support in pokeemerald for [old versions of Windows](https://support.microsoft.com/help/13853) so consider upgrading to a current release of Windows 10 or try a third-party guide like [this one](https://www.pokecommunity.com/showthread.php?t=425246) instead.
|
||||
### Setting up WSL1
|
||||
Open **Ubuntu** (e.g. using Search). WSL/Ubuntu will set up its own installation when it runs for the first time. Once WSL/Ubuntu finishes installing, it will ask for a username and password (to be input in). Note that there will be no visible response when typing in the password, but the terminal will still read in input.
|
||||
|
||||
A few notes before proceeding
|
||||
- In the terminal, Copy and Paste is either done via
|
||||
- **right-click** (selection + right click to Copy, right click with no selection to Paste)
|
||||
- **Ctrl+Shift+C/Ctrl+Shift+V** (enabled by right-clicking the title bar, going to Properties, then checking the checkbox next to "Use Ctrl+Shift+C/V as Copy/Paste").
|
||||
- Some of the commands that you'll run will ask for your WSL password and/or confirmation to perform the stated action. This is to be expected, just enter your WSL password and/or the yes action when necessary.
|
||||
|
||||
# Installation
|
||||
Update WSL/Ubuntu before continuing. Do this by running the following command:
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
Note that these commands will likely take a long time to finish.
|
||||
|
||||
To set up the repository:
|
||||
Certain packages are required to build pokeemerald. Install these packages by running the following command:
|
||||
```bash
|
||||
sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
|
||||
```
|
||||
(If the above command does not work, try the above command but replacing `apt` with `apt-get`).
|
||||
|
||||
git clone https://github.com/pret/pokeemerald
|
||||
git clone https://github.com/pret/agbcc
|
||||
WSL has its own file system that's not accessible from Windows, but Windows files *are* accessible from WSL. So you're going to want to install pokeemerald within Windows. You'll have to change the **current working directory** every time you open WSL.
|
||||
|
||||
cd ./agbcc
|
||||
./build.sh
|
||||
./install.sh ../pokeemerald
|
||||
For example, if you want to store pokeemerald (and agbcc) in **C:\Users\\_\<user>_\Desktop\decomps**, enter this command:
|
||||
```bash
|
||||
cd /mnt/c/Users/<user>/Desktop/decomps
|
||||
```
|
||||
Note that the directory **must exist** in Windows. If you want to store pokeemerald in a dedicated folder that doesn't exist (e.g. the example provided above), then create the folder (e.g. using Windows Explorer) before executing the `cd` command.
|
||||
|
||||
cd ../pokeemerald
|
||||
(The Windows C:\ drive is called /mnt/c/ in WSL. Replace <user> in the example path with your **Windows** username, and the drive letter with the letter of the drive of the folder where the package was saved to. Windows path names are case-insensitive so adhereing to capitalization isn't needed)
|
||||
|
||||
If this works, then proceed to [Installation](#Installation).
|
||||
|
||||
Otherwise, continue reading below for [the older Windows instructions](#windows).
|
||||
|
||||
## Windows
|
||||
TODO: add general Windows instructions
|
||||
|
||||
## macOS
|
||||
TODO: add macOS instructions
|
||||
|
||||
## Linux
|
||||
TODO: add Linux instructions
|
||||
|
||||
## Installation
|
||||
To download the pokeemerald repository:
|
||||
```bash
|
||||
git clone https://github.com/pret/pokeemerald
|
||||
```
|
||||
If agbcc isn't built, run the following commands to build and install it into pokeemerald:
|
||||
```
|
||||
git clone https://github.com/pret/agbcc
|
||||
cd agbcc
|
||||
./build.sh
|
||||
./install.sh ../pokeemerald
|
||||
```
|
||||
Otherwise, run the following commands to install agbcc into pokeemerald:
|
||||
```
|
||||
cd agbcc
|
||||
./install.sh ../pokeemerald
|
||||
```
|
||||
Then, change directory back to the base directory where pokeemerald and agbcc are stored:
|
||||
```
|
||||
cd ..
|
||||
```
|
||||
Now you're ready to [build **pokeemerald**](#build-pokeemerald)
|
||||
## Build pokeemerald
|
||||
First, change directory to the pokeemerald folder:
|
||||
```bash
|
||||
cd pokeemerald
|
||||
```
|
||||
To build **pokeemerald.gba** for the first time and confirm it matches the official ROM image:
|
||||
|
||||
make compare
|
||||
|
||||
```bash
|
||||
make compare
|
||||
```
|
||||
If an OK is returned, then the installation went smoothly.
|
||||
|
||||
**Windows users:** Consider adding exceptions for the `pokeemerald` and `agbcc` folders in Windows Security using [these instructions](https://support.microsoft.com/help/4028485). This prevents Microsoft Defender from scanning them which might improve performance while building.
|
||||
|
||||
|
||||
# Start
|
||||
|
||||
To build **pokeemerald.gba** with your changes:
|
||||
```bash
|
||||
make
|
||||
```
|
||||
|
||||
make
|
||||
|
||||
**macOS users:** If the base tools are not found in new Terminal sessions after the first successful build, run `echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile` once to prevent the issue from occurring again. Verify that the `devkitarm-rules` package is installed as well; if not, install it by running `sudo dkp-pacman -S devkitarm-rules`.
|
||||
**Windows users:** Consider adding an exception for the `pokeemerald` folder in Windows Security using [these instructions](https://support.microsoft.com/help/4028485). This prevents Microsoft Defender from scanning them which might improve performance while building.
|
||||
|
||||
**macOS users (this is probably outdated):** If the base tools are not found in new Terminal sessions after the first successful build, run `echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile` once to prevent the issue from occurring again. Verify that the `devkitarm-rules` package is installed as well; if not, install it by running `sudo dkp-pacman -S devkitarm-rules`.
|
||||
|
||||
# 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, run:
|
||||
|
||||
make -j$(nproc)
|
||||
To speed up building, first get the value of `nproc`:
|
||||
```bash
|
||||
nproc
|
||||
```
|
||||
Builds can then be sped up by running the following command:
|
||||
```bash
|
||||
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)).
|
||||
|
||||
|
||||
## Debug info
|
||||
|
||||
To build **pokeemerald.elf** with enhanced debug info:
|
||||
|
||||
make DINFO=1
|
||||
|
||||
```bash
|
||||
make DINFO=1
|
||||
```
|
||||
|
||||
## devkitARM's C compiler
|
||||
|
||||
This project supports the `arm-none-eabi-gcc` compiler included with devkitARM r52. To build this target, simply run:
|
||||
This project supports the `arm-none-eabi-gcc` compiler included with devkitARM. If devkitARM has already been installed as part of the platform-specific instructions, simply run:
|
||||
```bash
|
||||
make modern
|
||||
```
|
||||
Otherwise, follow the instructions below to install devkitARM.
|
||||
### Installing devkitARM on WSL1
|
||||
|
||||
make modern
|
||||
`gdebi-core` must be installed beforehand in order to install devkitPro (which facilitates the installation of devkitARM). Install this with the following command:
|
||||
```bash
|
||||
sudo apt install gdebi-core
|
||||
```
|
||||
(If the above command does not work, try the above command but replacing `apt` with `apt-get`).
|
||||
|
||||
Once `gdebi-core` is done installing, download the devkitPro software package [here](https://github.com/devkitPro/pacman/releases). The file to download is `devkitpro-pacman.amd64.deb`.
|
||||
|
||||
Change directory to where the package was downloaded. For example, if the package file was saved to **C:\Users\\_\<user>_\Downloads** (the Downloads location for most users), enter this command:
|
||||
```bash
|
||||
cd /mnt/c/Users/<user>/Downloads
|
||||
```
|
||||
(Replace <user> with your Windows username)
|
||||
|
||||
Once the directory has been changed to the folder containing the devkitPro package, run the following commands to install devkitPro.
|
||||
```bash
|
||||
sudo gdebi devkitpro-pacman.amd64.deb
|
||||
sudo dkp-pacman -Sy
|
||||
sudo dkp-pacman -S gba-dev
|
||||
```
|
||||
Note: the last command 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. `devkitpro-pacman.amd64.deb` is the expected filename of the devkitPro package downloaded (for the first command). If the downloaded package filename differs, then use that filename instead.
|
||||
|
||||
Run the following command to set devkitPro related environment variables (alternatively, close and re-open WSL):
|
||||
```bash
|
||||
source /etc/profile.d/devkit-env.sh
|
||||
```
|
||||
devkitARM is now installed.
|
||||
|
||||
## Other toolchains
|
||||
|
||||
|
|
@ -90,7 +178,6 @@ The following is an example:
|
|||
|
||||
To compile the `modern` target with this toolchain, the subdirectories `lib`, `include`, and `arm-none-eabi` must also be present.
|
||||
|
||||
|
||||
# Useful additional tools
|
||||
|
||||
* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps
|
||||
|
|
|
|||
Loading…
Reference in New Issue