environment.md

Make sure you read through the sections corresponding to your OS/distro combo as well as the final section which applies to all of them.

TL;DR

You will need all of the following:

• A POSIX compatible shell such as bash. The Windows Command Prompt and Powershell will not work.
• git, cmake, python3, bc, and your distro's equivalent of build-essential (mostly for gcc and make).
• devkitARM, including environment variables DEVKITARM and DEVKITPRO pointing to the relevant directories.
• ARMIPS should be available on the PATH as armips.
• preproc should be available on the PATH as pret-preproc.

Windows

The only supported Windows environment is WSL. If you don't have a strong preference in Linux distros, I suggest Ubuntu. The one in the Windows Store without an explicit version number should always be the most recent.

Accessing your C: drive from within WSL can have some weird file permissions issues. Following the advice of this official article, do the following:

$ sudo umount /mnt/c
$ sudo mount -t drvfs C: /mnt/c -o metadata

Repeat the above for any other Windows drives you want to access from inside WSL. For example, if you wanted to access your D: drive from within WSL:

$ sudo umount /mnt/d
$ sudo mount -t drvfs D: /mnt/d -o metadata

One tip to keep in mind for WSL is that you're in a folder in Windows Explorer, you can shift + right click and select Open Linux shell here in order to open the terminal directly to that folder.

Otherwise, just follow the instructions relevant to your Linux distro.

Linux

Ubuntu

Basic shell and build tools

$ sudo apt update
$ sudo apt upgrade
$ sudo apt install git cmake bc build-essential

devkitPro and gba-dev

You can check if you have devkitARM installed and set up properly by running:

$ $DEVKITARM/bin/arm-none-eabi-gcc --version

If it's set up properly you should get something along the lines of:

arm-none-eabi-gcc (devkitARM release 61) 13.1.0
Copyright (C) 2023 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

If you instead get an error about "command not found", you'll need to install it. Instructions are here, but the following should work:

$ cd /tmp
$ wget https://apt.devkitpro.org/install-devkitpro-pacman
$ chmod +x ./install-devkitpro-pacman
$ sudo ./install-devkitpro-pacman
$ sudo dkp-pacman -Syu
$ sudo dkp-pacman -Sy --needed gba-dev
$ source /etc/profile.d/devkit-env.sh
$ echo 'source /etc/profile.d/devkit-env.sh' >> ~/.bashrc

Once you've done that, run the above test again to ensure it's installed properly.

macOS

TODO

All

ARMIPS

You can check if you have ARMIPS installed and set up properly by running:

$ armips

If it's set up properly you should get something along the lines of:

ARMIPS64 Assembler v0.10.0 (Aug 24 2019 22:01:47) by Kingcom
Usage: armips [optional parameters] <FILE>

Optional parameters:
 -temp <TEMP>              Output temporary assembly data to <TEMP> file
 -sym  <SYM>               Output symbol data in the sym format to <SYM> file
 -sym2 <SYM2>              Output symbol data in the sym2 format to <SYM2> file
 -root <ROOT>              Use <ROOT> as working directory during execution
 -equ  <NAME> <VAL>        Equivalent to '<NAME> equ <VAL>' in code
 -strequ <NAME> <VAL>      Equivalent to '<NAME> equ "<VAL>"' in code
 -definelabel <NAME> <VAL> Equivalent to '.definelabel <NAME>, <VAL>' in code
 -erroronwarning           Treat all warnings like errors

File arguments:
 <FILE>                    Main assembly code file

If you instead get an error about command not found, you'll need to install it. Build instructions are available in its README, but the following should work:

$ cd /tmp
$ git clone --recursive https://github.com/Kingcom/armips.git
$ mkdir armips/build
$ cd armips/build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build .
$ mkdir -p ~/bin
$ cp ./armips ~/bin/armips

Once you've done that, run the above test again to ensure it's installed properly.

Note: This assumes that ~/bin is a folder that is on the PATH. Different systems handle ~/bin differently; Ubuntu for example will automatically add it to the PATH if it exists, so you'd only have to close and reopen your terminal after creating it and it will be there. Other systems may require you to explicitly add it to the PATH (e.g. in your ~/.basrc).

If ~/bin isn't on the PATH, you will continue to get the command not found error even if the binary is in place.

preproc

You can check if you have preproc set up properly by running:

$ pret-preproc

If it's set up properly you should get something along the lines of:

Usage: pret-preproc SRC_FILE CHARMAP_FILE

If, instead, you got pret-preproc: command not found, it is not set up correctly. To do so, you can do the following:

$ cd /tmp
$ git clone https://github.com/Zeturic/pret-preproc.git
$ cd pret-preproc
$ make
$ mkdir -p ~/bin
$ cp ./preproc ~/bin/pret-preproc

Once you've done that, run the above test again to ensure it's installed properly.

This has the same caveats about ~/bin mentioned in the armips section, though if you already got that working it shouldn't be an issue.