Skip to content

Latest commit

 

History

History
304 lines (224 loc) · 13.7 KB

INSTALL.md

File metadata and controls

304 lines (224 loc) · 13.7 KB
Raw

Instructions

These instructions explain how to set up the tools required to build pmd-red, which assembles the source files into a ROM.

These instructions come with notes which can be expanded by clicking the "Note..." 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).

Prerequisites

First, you must put a Pokémon Mystery Dungeon Red Rescue Team 1.0 (US) ROM in the root directory of the repository and name it baserom.gba. It should have a SHA1 checksum of 9f4cfc5b5f4859d17169a485462e977c7aac2b89. Then, follow the OS-specific instructions below:

Windows

Note for advanced users: WSL2...

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 may have problems with parsing the \wsl$ network drive path.

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.

Windows 10 (WSL1)

WSL1 is the preferred terminal to build pmd-red. The following instructions will explain how to install WSL1 (referred to interchangeably as WSL).

Installing WSL1

  1. Open Windows Powershell as Administrator, and run the following command (Right Click or Shift+Insert is paste in the Powershell).

    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

  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.

    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.

  4. Open the Microsoft Store Linux Selection, click Ubuntu, then click Get, which will install the Ubuntu distribution.

    Notes...

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

Setting up WSL1

Some tips before proceeding:

  • In WSL, 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.

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

    Note...

    When typing in the password, there will be no visible response, but the terminal will still read in input.

  3. Update WSL/Ubuntu before continuing. Do this by running the following command. These commands will likely take a long time to finish:

    sudo apt update && sudo apt upgrade

Note: If the repository you plan to build has an older revision of the INSTALL.md, then follow the legacy WSL1 instructions from here.

  1. Certain packages are required to build pmd-red. Install these packages by running the following command:

    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.

Choosing where to store pmd-red (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 store pmd-red within Windows.

For example, say you want to store pmd-red (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:

cd /mnt/c/Users/<user>/Desktop/decomps
Notes...

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

If this works, then proceed to Installation.

macOS

  1. If the Xcode Command Line Tools are not installed, download the tools here, open your Terminal, and run the following command:

    xcode-select --install

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.

  1. Open the Terminal.

  2. If Homebrew is not installed, then install Homebrew by following the instructions on the website.

  3. Run the following command to install libpng.

    brew install libpng

    libpng is now installed.

Choosing where to store pmd-red (macOS)

At this point, you can choose a folder to store pmd-red into. If you're okay with storing pmd-red in the user folder, then proceed to Installation. Otherwise, you'll need to account for where pmd-red is stored when changing directory to the pmd-red folder.

For example, if you want to store pmd-red (and agbcc) in ~/Desktop/decomps, enter this command to change directory to the desired folder:

cd Desktop/decomps

Note that the directory must exist in the folder system. If you want to store pmd-red 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...

Note: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "Desktop/decomp folder"

If this works, then proceed to Installation. Otherwise, ask for help on Discord or IRC (see README.md).

Linux

Open Terminal and enter the following commands, depending on which distro you're using.

Debian/Ubuntu-based distributions

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 pmd-red (Linux).

Other distributions

(Specific instructions for other distributions would be greatly appreciated!)

  1. Try to find the required software in its repositories:
    • gcc
    • g++
    • make
    • git
    • libpng-dev

Choosing where to store pmd-red (Linux)

At this point, you can choose a folder to store pmd-red (and agbcc) into. If so, you'll have to account for the modified folder path when changing directory to the pmd-red folder.

If this works, then proceed to Installation. Otherwise, ask for help on Discord or IRC (see README.md).

Installation

Note for Windows users...

Consider adding an exception for the pmd-red and/or decomps folder in Windows Security using these instructions. This prevents Microsoft Defender from scanning them which might improve performance while building.

  1. If pmd-red is not already downloaded (some users may prefer to download pmd-red via a git client like GitHub Desktop), run:

    git clone https://github.com/pret/pmd-red
    Note for WSL1...

    If you get an error stating fatal: could not set 'core.filemode' to 'false', then run the following commands:

    cd
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata,noatime
cd <folder where pmd-red is to be stored>

    Where <folder where pmd-red is to be stored> is the path of the folder where you chose to store pmd-red. Then run the git clone command again.

  2. Install agbcc into pmd-red. 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 pmd-red, run the following commands to build and install it into pmd-red:

    git clone https://github.com/pret/agbcc
cd agbcc
./build.sh
./install.sh ../pmd-red

  • 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 pmd-red:

    cd agbcc
git clean -fX
./build.sh
./install.sh ../pmd-red

  • Otherwise, if agbcc has been built before on the same terminal, run the following commands to install agbcc into pmd-red:

    cd agbcc
./install.sh ../pmd-red
    Note... 
      > If building agbcc or pmd-red results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.

  1. Once agbcc is installed, change directory back to the base directory where pmd-red and agbcc are stored:

    cd ..

Now you're ready to build pmd-red

Build pmd-red

If you aren't in the pmd-red directory already, then change directory to the pmd-red folder:

cd pmd-red

To build pmd-red.gba for the first time and confirm it matches the official ROM image (Note: to speed up builds, see Parallel builds):

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.

To build pmd-red.gba with your changes:

make

Building guidance

Parallel builds

See the GNU docs and this Stack Exchange thread for more information.

To speed up building, first get the value of nproc by running the following command:

nproc

Builds can then be sped up by running the following command:

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

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.

make TOOLCHAIN="/path/to/toolchain/here"

The following is an example:

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.

Useful additional tools