ninjdai/pokeemerald
1
0
Fork 0
mirror of https://github.com/Ninjdai1/pokeemerald.git synced 2024-12-26 19:54:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Wrap notes in details blocks.

Browse Source
This commit is contained in:
luckytyphlosion 2021-05-01 21:03:40 -04:00 committed by GitHub
parent 52ab1acea1
commit 9ec5a5b468
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 124 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
INSTALL.md
View File

@ -2,17 +2,25 @@
These instructions explain how to set up the tools required to build **pokeemerald**, which assembles the source files into a ROM.
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 Discord or IRC (see [README.md](README.md)).
## Windows
Windows has instructions for building with three possible terminals, providing 3 different options in case the user stumbled upon unexpected errors.
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 (msys2)](#windows-msys2) (Second fastest)
- [Windows (Cygwin)](#windows-cygwin) (Slowest)
Unscientific benchmarks suggest **msys2 is 2x slower** than WSL1, and **Cygwin is 5-6x slower** than WSL1.
<details>
<summary><i>Note for advanced users: <b>WSL2</b>...</i></summary>
> Note for advanced users: **WSL2** is an option and is even faster than **WSL1** if files are stored on the WSL2 file system, but some tools may have trouble interacting with the WSL2 file system over the network drive. For example, tools which use Qt versions before 5.15.2 such as [porymap](https://github.com/huderlem/porymap) may [have problems with parsing the `\\wsl$` network drive path](https://bugreports.qt.io/browse/QTBUG-86277).
> <b>WSL2</b> is an option and is even faster than <b>WSL1</b> if files are stored on the WSL2 file system, but some tools may have trouble interacting
> with the WSL2 file system over the network drive. For example, tools which use Qt versions before 5.15.2 such as <a href="https://github.com/huderlem/porymap">porymap</a>
> 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.
@ -34,13 +42,19 @@ WSL1 is the preferred terminal to build **pokeemerald**. The following instructi
2. Once the process finishes, restart your machine.
3. 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.
<details>
<summary><i>Note for advanced users...</i></summary>
> Note for advanced users: 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, but has not been tested.
</details>
4. Open the [Microsoft Store Linux Selection](https://aka.ms/wslstore), click Ubuntu, then click Get, which will install the Ubuntu distribution.
<details>
<summary><i>Notes...</i></summary>
> Note 1: If a dialog pops up asking for you to sign into a Microsoft Account, then just close the dialog.
> Note 2: 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).
> Note 1: If a dialog pops up asking for you to sign into a Microsoft Account, then just close the dialog.
> Note 2: 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).
</details>
### Setting up WSL1
Some tips before proceeding:
@ -51,15 +65,17 @@ Some tips before proceeding:
1. Open **Ubuntu** (e.g. using Search).
2. 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).
<details>
<summary><i>Note...</i></summary>
> Note: When typing in the password, there will be no visible response, but the terminal will still read in input.
> When typing in the password, there will be no visible response, but the terminal will still read in input.
</details>
3. Update WSL/Ubuntu before continuing. Do this by running the following command:
3. Update WSL/Ubuntu before continuing. Do this by running the following command. These commands will likely take a long time to finish:
```bash
sudo apt update && sudo apt upgrade
```
> Note: These commands will likely take a long time to finish.
> 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)**, then follow the [legacy WSL1 instructions](docs/legacy_WSL1_INSTALL.md) from here.
@ -68,24 +84,28 @@ Some tips before proceeding:
```bash
sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
```
> Note: If the above command does not work, try the above command but replacing `apt` with `apt-get`.
<details>
<summary><i>Note...</i></summary>
> If the above command does not work, try the above command but replacing `apt` with `apt-get`.
</details>
### Choosing where to store pokeemerald (WSL1)
WSL has its own file system that's not natively accessible from Windows, but Windows files *are* accessible from WSL. So you're going to want to install pokeemerald within Windows.
WSL has its own file system that's not natively accessible from Windows, but Windows files *are* accessible from WSL. So you're going to want to store pokeemerald within Windows.
For example, say you want to store pokeemerald (and agbcc) in **C:\Users\\_\<user>_\Desktop\decomps**. First, ensure that the folder already exists. Then, enter this command to **change directory** to said folder, where *\<user>* is your **Windows** username:
For example, say you want to store pokeemerald (and agbcc) in **C:\Users\\_\<user>_\Desktop\decomps**. If pokeemerald and/or agbcc hasn't been installed yet, then enter the following command, where *\<user>* is your **Windows** username:
```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.
> Note 1: The Windows C:\ drive is called /mnt/c/ in WSL.
> Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "/mnt/c/users/<user>/Desktop/decomp folder"`.
> Note 3: Windows path names are case-insensitive so adhering to capitalization isn't needed
> Note 4: If pokeemerald is already installed, then run the following command instead (for the provided example path):
> ```bash
> cd /mnt/c/Users/<user>/Desktop/decomps/pokeemerald
> ```
<details>
<summary><i>Notes...</i></summary>
> Note 1: The Windows C:\ drive is called /mnt/c/ in WSL.
> Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "/mnt/c/users/<user>/Desktop/decomp folder"`.
> Note 3: Windows path names are case-insensitive so adhering to capitalization isn't needed
</details>
If this works, then proceed to [Installation](#installation).
@ -112,20 +132,28 @@ Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
```bash
pacman -S make gcc zlib-devel git
```
> Note: This command will ask for confirmation, just enter the yes action when prompted.
<details>
<summary><i>Note...</i></summary>
> 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:
4. Change directory to where libpng was downloaded. By default, msys2 will start in the current user's profile folder, located at **C:\Users\\&#8288;_\<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
```
> 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>
<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.
@ -146,19 +174,12 @@ Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
### Choosing where to store pokeemerald (msys2)
At this point, you can choose a folder to store pokeemerald into. If you're okay with storing pokeemerald in the user profile folder, then proceed to [Installation](#installation). Otherwise, you'll need to account for where pokeemerald is stored when changing directory to the pokeemerald folder.
For example, say you want to store pokeemerald (and agbcc) in **C:\Users\\_\<user>_\Desktop\decomps**. If pokeemerald and/or agbcc hasn't been installed yet, then enter the following command to **change directory** to the desired folder:
For example, if you want to store pokeemerald (and agbcc) in **C:\Users\\_\<user>_\Desktop\decomps** (where *\<user>* is your **Windows** username), enter this command:
```bash
cd 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.
> Note: If pokeemerald is already installed, then run the following command instead (for the provided example path):
> ```bash
> cd Desktop/decomps/pokeemerald
> ```
If this works, then proceed to [Installation](#installation).
Otherwise, ask for help on Discord or IRC (see [README.md](README.md)), or continue reading below for [Windows instructions using Cygwin](#windows-cygwin).
@ -206,7 +227,11 @@ Note that in Cygwin, Copy is Ctrl+Insert and Paste is Shift+Insert.
echo export DEVKITARM=$DEVKITARM >> ~/.bashrc
```
> Note: Replace the drive letter c with the actual drive letter if it is not c.
<details>
<summary><i>Note...</i></summary>
> Replace the drive letter c with the actual drive letter if it is not c.
</details>
### Choosing where to store pokeemerald (Cygwin)
@ -218,17 +243,17 @@ cd 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.
> Note 1: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "c:/users/<user>/Desktop/decomp folder"`.
> Note 2: Windows path names are case-insensitive so adhering to capitalization isn't needed
> Note 3: If pokeemerald is already installed, then run the following command instead (for the provided example path):
> ```bash
> cd c:/Users/<user>/Desktop/decomps/pokeemerald
> ```
<details>
<summary><i>Notes...</i></summary>
> Note 1: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "c:/users/<user>/Desktop/decomp folder"`.
> 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 Discord or IRC (see [README.md](README.md)).
## macOS
1. If the Xcode Command Line Tools are not installed, download the tools [here](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), open your Terminal, and run the following command:
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:
```bash
xcode-select --install
@ -239,7 +264,11 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
- Otherwise, **open the Terminal** and go to [Choosing where to store pokeemerald (macOS)](#choosing-where-to-store-pokeemerald-macos)
### Installing libpng (macOS)
> Note for advanced users: This guide installs libpng via Homebrew as it is the easiest method, however advanced users can install libpng through other means if they so desire.
<details>
<summary><i>Note for advanced users...</i></summary>
> This guide installs libpng via Homebrew as it is the easiest method, however advanced users can install libpng through other means if they so desire.
</details>
1. Open the Terminal.
2. If Homebrew is not installed, then install [Homebrew](https://brew.sh/) by following the instructions on the website.
@ -279,17 +308,17 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
### Choosing where to store pokeemerald (macOS)
At this point, you can choose a folder to store pokeemerald into. If you're okay with storing pokeemerald in the user folder, then proceed to [Installation](#installation). Otherwise, you'll need to account for where pokeemerald is stored when changing directory to the pokeemerald folder.
For example, say you want to store pokeemerald (and agbcc) in **~/Desktop/decomps**. If pokeemerald and/or agbcc hasn't been installed yet, then enter the following command to **change directory** to the desired folder:
For example, if you want to store pokeemerald (and agbcc) in **~/Desktop/decomps**, enter this command to **change directory** to the desired folder:
```bash
cd Desktop/decomps
```
Note that the directory **must exist** in the folder system. 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 Finder) before executing the `cd` command.
> Note 1: If the path has spaces, then the path must be wrapped with quotations, e.g. `cd "Desktop/decomp folder"`
> Note 2: If pokeemerald is already installed, then run the following command instead (for the provided example path:
> ```bash
> cd Desktop/decomps/pokeemerald
> ```
<details>
<summary><i>Note..</i>.</summary>
> 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 Discord or IRC (see [README.md](README.md)).
@ -302,6 +331,13 @@ Run the following command to install the necessary packages:
sudo apt install build-essential binutils-arm-none-eabi git libpng-dev
```
Then proceed to [Choosing where to store pokeemerald (Linux)](#choosing-where-to-store-pokeemerald-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)**,
> 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>
### Other distributions
_(Specific instructions for other distributions would be greatly appreciated!)_
@ -330,7 +366,13 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
## Installation
> Windows users: Consider adding an exception for the `pokeemerald` and/or `decomps` 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.
<details>
<summary><i>Note for Windows users...</i></summary>
> Consider adding an exception for the `pokeemerald` and/or `decomps` 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.
</details>
1. If pokeemerald is not already downloaded (some users may prefer to download pokeemerald via a git client like GitHub Desktop), run:
@ -338,16 +380,20 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
git clone https://github.com/luckytyphlosion/pokeemerald
```
> Note for WSL1: If you get an error stating `fatal: could not set 'core.filemode' to 'false'`, then run the following commands:
>```bash
>cd
>sudo umount /mnt/c
>sudo mount -t drvfs C: /mnt/c -o metadata,noatime
>cd <folder where pokeemerald is to be stored>
>```
> Where *\<folder where pokeemerald is to be stored>* is the path of the folder [where you chose to store pokeemerald](#Choosing-where-to-store-pokeemerald-WSL1). Then run the `git clone` command again.
<details>
<summary><i>Note for WSL1...</i></summary>
2. Install agbcc into pokeemerald. The commands to run depend on certain conditions:
> If you get an error stating `fatal: could not set 'core.filemode' to 'false'`, then run the following commands:
> ```bash
> cd
> sudo umount /mnt/c
> sudo mount -t drvfs C: /mnt/c -o metadata,noatime
> cd <folder where pokeemerald is to be stored>
> ```
> Where *\<folder where pokeemerald is to be stored>* is the path of the folder [where you chose to store pokeemerald](#Choosing-where-to-store-pokeemerald-WSL1). Then run the `git clone` command again.
</details>
2. Install agbcc into pokeemerald. 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 pokeemerald, run the following commands to build and install it into pokeemerald:
```bash
@ -366,14 +412,18 @@ If this works, then proceed to [Installation](#installation). Otherwise, ask for
./install.sh ../pokeemerald
```
- **Otherwise**, run the following commands to install agbcc into pokeemerald:
- **Otherwise**, if agbcc has been built before on the same terminal, run the following commands to install agbcc into pokeemerald:
```bash
cd agbcc
./install.sh ../pokeemerald
```
> Note: If building agbcc or pokeemerald results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.
<details>
<summary><i>Note...</i></summary>
> If building agbcc or pokeemerald 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 pokeemerald and agbcc are stored:
@ -392,7 +442,10 @@ To build **pokeemerald.gba** for the first time and confirm it matches the offic
make compare
```
If an OK is returned, then the installation went smoothly.
> Note for Windows: 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.
<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.
</details>
To build **pokeemerald.gba** with your changes:
```bash
@ -438,7 +491,11 @@ Otherwise, follow the instructions below to install devkitARM.
```bash
sudo apt install gdebi-core
```
> Note: If the above command does not work, try the above command but replacing `apt` with `apt-get`.
<details>
<summary><i>Note...</i></summary>
> If the above command does not work, try the above command but replacing `apt` with `apt-get`.
</details>
2. Once `gdebi-core` is done installing, download the devkitPro pacman package [here](https://github.com/devkitPro/pacman/releases). The file to download is `devkitpro-pacman.amd64.deb`.
3. 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, where *\<user> is your **Windows** username:
@ -456,7 +513,11 @@ Otherwise, follow the instructions below to install devkitARM.
```
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.
<details>
<summary><i>Note...</i></summary>
> Note: `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.
</details>
5. Run the following command to set devkitPro related environment variables (alternatively, close and re-open WSL):