Lunos
Random Uruguayan User
- 3,136
- Posts
- 16
- Years
- Montevideo (Uruguay)
- Seen yesterday
27 of January from 2023. I'm rewriting this tutorial. I should have done it much sooner, but y'all know me; I'm lazy.
What are the goals? To explain in simple steps how to set up an environment to build Pret's Pokémon Decompilation Projects on WSL.
What is being added? Explanations on how to set up a WSL2 environment and considerations to keep in mind and such.
What's driving me to do this after so long? Devkitpro, in a way. I won't say more.
Let's get to it.
Before we start, I'll need you to make a choice; WSL1 or WSL2.
List of Pros and Cons:
Spoiler:
Advantages of using WSL1:
-Fast work speed on Windows' own filesystem.
-Much faster than Cygwin or MSys2.
Disadvantages of using WSL1:
-Considerably slower than WSL2, unless your hardware can power through to close the gap.
Advantages of using WSL2:
-Super fast work speed on its Linux distributions' own filesystem.
-Considerably faster than WSL1.
Disadvantages of using WSL2:
-Working on Windows' own filesystem is slow. It's a known issue. This means you WILL want to do your work on the Linux filesystem exclusively.
After you made up your choice, follow the correspondent section of the tutorial.
Personally, I do my decomp work on the filesystem of my Ubuntu installation using WSL2.
WSL1:
Spoiler:
1) Open the Windows Command Prompt as Administrator (look up "Command Prompt on your Start Menu, Right Click -> Run as Administrator).
After that, execute the following command:
Code:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all
When the process finishes you'll have to restart your PC by pressing "Y" to finish the process. Keep that in mind.
2) Go to the Microsoft Store and search "Ubuntu". Enter the page for the version with the highest version numer.
At the time of this writing, it's Ubuntu 22.04.1 LTS.
If for X or Y reason you don't have access to the Microsoft Store, check the FAQ. I explain how to install Ubuntu manually through a .appx package there.
The installation is as straightforward as any other program's. Open it, hit Install and wait until it's done.
Launch Ubuntu when the installation finishes, so it can start its own setup.
When Ubuntu opens, we'll be greeted by a command line window telling us that Ubuntu is: "Installing, this may take a few minutes...".
Once we're ready to proceed, we'll be asked to introduce a username (in lowercase letters) and a password. Don't worry if you can't see the latter as you're typing it, it's a security measure.
After that, the installation will be completed and we can safely close the window of Ubuntu.
Why is that? Because from here on, we'll run Ubuntu by typing "wsl" on the Run window (Win Key + R).
By running WSL this way, we'll be taken directly to the Windows Filesystem instead of Ubuntu's. More specifically, WSL will always open pointing to the C:\Users\USER folder.
3) The very first thing you generally do after installing a distribution of Linux, is to update its list of packages.
To do this, we'll use the following merged command:
Code:
sudo apt update -y && sudo apt upgrade -y
Once we hit Enter, we will see that Ubuntu will retrieve different lists of packages from multiple sources. This is done so it can find the latest versions of each package and library you need.
When that process is completed, Ubuntu will then update all the packages obtaining the latest files from said sources.
Keep in mind that this process may take a long time. There's nothing to be done about it. Endure it.
Thanks to the
-y
argument, the process should happen completely on its own without any intervention of your own. Just let it run until it's all done.Is it done yet? Good. Let's move on.
4) Now we are ready to install the packages that the decomps need in order to be built.
To install them, we will use:
Code:
sudo apt install build-essential git libpng-dev
Alternatively, if for whatever reason the command above gave you an error, try:
Code:
sudo apt-get install build-essential git libpng-dev
We'll be asked to confirm the installation with "y". We do so, press Enter and wait.
At this point, there's 2 options we can take in order to proceed.
The first one is to install devkitpro-pacman and through it, devkitARM, to get its own distribution of GCC which is used by both, older and newer versions of Pokeemerald, and perhaps Pokefirered.
The second is to install the package
binutils-arm-none-eabi
in the exact same manner we installed the other prerequisite packages above.What's the difference? Devkitpro allows you to run copies of Pokeemerald made both, before and after June 2021, while
binutils-arm-none-eabi
does not.Also keep in mind that devkitPro's developers do not offer support for certain operating systems after X amount of time.
If you came across unexpected errors here, please refer to the FAQ Section of this post.
Choose whichever option you prefer.
devkitPro:
Spoiler:
5) The next thing we'll do is to install devkiPro Pacman.
In order to do this we'll use the following commands:
Note: If your Windows account username contains empty spaces, you will need to use reverse backslashes to parse them.
For example, if your Windows username is "Alfredo's Computer", you will need to input your path like this:
What these commands do is:
- Go to the user's Downloads folder.
-Download the script called "install-devkitpro-pacman" in there.
- Give permissions to execute it.
- Execute it.
Next we'll install the GBA Development package of devkitPro by using:
After we input this command, devkitPro Pacman will let us choose specific packages within the gba-dev package to download.
We'll just press Enter to tell it that we want all of them, and then we'll be asked if we want to proceed with the installation, to which we'll say "y" and then press Enter again.
6) Close WSL and open it again so devkitPro will make some variables that it needs for its correct functioning.
You can double check if they were made successfully by typing
If they return the following paths:
Congratulations, now you're ready to build the decomps.
In order to do this we'll use the following commands:
cd /mnt/c/Users/USER/Downloads
sudo apt install wget
wget https://apt.devkitpro.org/install-devkitpro-pacman
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
Note: If your Windows account username contains empty spaces, you will need to use reverse backslashes to parse them.
For example, if your Windows username is "Alfredo's Computer", you will need to input your path like this:
cd /mnt/c/Users/Alfredo's\ Computer/Downloads
.What these commands do is:
- Go to the user's Downloads folder.
-Download the script called "install-devkitpro-pacman" in there.
- Give permissions to execute it.
- Execute it.
Next we'll install the GBA Development package of devkitPro by using:
Code:
sudo dkp-pacman -S gba-dev
After we input this command, devkitPro Pacman will let us choose specific packages within the gba-dev package to download.
We'll just press Enter to tell it that we want all of them, and then we'll be asked if we want to proceed with the installation, to which we'll say "y" and then press Enter again.
6) Close WSL and open it again so devkitPro will make some variables that it needs for its correct functioning.
You can double check if they were made successfully by typing
echo $DEVKITPRO
and/or echo $DEVKITARM
.If they return the following paths:
/opt/devkitpro
and /opt/devkitpro/devkitARM
respectively, then we're done here.Congratulations, now you're ready to build the decomps.
binutils:
Spoiler:
5)
Code:
sudo apt install binutils-arm-none-eabi
Alternatively, if for whatever reason the command above gave you an error, try:
Code:
sudo apt-get install binutils-arm-none-eabi
6) Close WSL and open it again as previous told, Win Key + R ->
wsl
7) Alright, so, we're currently in C:\Users\USER, aren't we? We did have to restart WSL just now, after all.
Let's make a dedicated folder to use for our decomps needs here. You know, to keep things clean.
Code:
mkdir Decomps
Good, let's move to this new folder by using:
Code:
cd Decomps
8) Now, we have to clone agbcc, and our desired decompilation project.
Code:
git clone https://github.com/pret/agbcc
git clone https://github.com/pret/pokeemerald
If you came across unexpected errors here, please refer to the FAQ Section of this post.
9) Let's build agbcc and install it in our decomp by using:
Code:
cd agbcc
./build.sh
./install.sh ../pokeemerald
10) And lastly, let's build a ROM.
Code:
cd ../pokeemerald
make -jN
Note2: You can use
nproc
to quickly check the amount of threads your CPU has.Also, keep in mind that every time you boot up WSL by using Win Key + R ->
wsl
, you'll start from C:\Users\USER, so you'll always start your work by doing:
Code:
cd Decomps
cd pokeemerald
WSL2:
Spoiler:
1) This bizarre adventure will start by opening an instance of the Windows Command Prompt or Windows PowerShell with Admin. rights, and typing in
wsl --install
.This command will handle basically every single part of the setup automatically.
It will enable WSL, it will install any prerequisites, it will enable WSL2 and it will even install a copy of Linux Ubuntu for us.
We simply need to wait until it's done, and then restart our PC when we're told that "Changes will not be effective until the system is rebooted."
For those who don't like or can't rely on this painless and automatic method, refer to the FAQ. I'll mention how to enable WSL2 manually there.
2) After we're back on Windows, we'll be greeted by a command line window telling us that WSL is resuming its installation of Ubuntu.
Once it's all done, we'll be asked to introduce a username (in lowercase letters) and a password.
Don't worry if you can't see the latter as you're typing it, it's a security measure.
After we introduce our credentials, we're going to be thrown directly into the root folder of our installation of Ubuntu.
Unlike in WSL1, on WSL2 we'll work exclusively on the filesystem of our Linux Ubuntu installation.
Check the list of pros and cons at the beginning of this post to learn why.
On WSL2 we will never want to do any operations inside the Windows filesystem, thus, we'll always work on Linux Ubuntu's home folder.
You can come back to this folder whenever you want by simply typing
cd
as is, without specifying any arguments.If we want or need to open this folder directlyc, the quickest way is to type in
cd
followed by explorer.exe .
and hit Enter.The latter will open an instance of Windows Explorer in the folder that our WSL terminal is currently looking at.
Fun fact: this trick also works on the command prompt, on PowerShell, on Cygwin and also on MSys2.
Now that we know the basics about moving around on our Linux Ubuntu's filesystem, let us proceed.
3) The very first thing we'll want to do after installing a distro of Linux, is to update its list of packages.
To do this, we'll use the following merged command:
Code:
sudo apt update -y && sudo apt upgrade -y
Once we hit Enter, we will see that Ubuntu will retrieve different lists of packages from multiple sources. This is done so it can find the latest versions of each package and library you need.
When that process is completed, Ubuntu will then update all the packages obtaining the latest files from said sources.
Keep in mind that this process may take a long time. There's nothing to be done about it. Endure it.
Thanks to the
-y
argument, the process should happen completely on its own without any intervention of your own. Just let it run until it's all done.Is it done yet? Good. Let's move on.
4) Now we are ready to install the packages that the decomps need in order to be built.
To install them, we will use:
Code:
sudo apt install build-essential git libpng-dev
Alternatively, if for whatever reason the command above gave you an error, try:
Code:
sudo apt-get install build-essential git libpng-dev
We'll be asked to confirm the installation with "y". We do so, press Enter and wait.
At this point, there's 2 options we can take in order to proceed.
The first one is to install devkitpro-pacman and through it, devkitARM, to get its own distribution of GCC which is used by both, older and newer versions of Pokeemerald, and perhaps Pokefirered.
The second is to install the package
binutils-arm-none-eabi
in the exact same manner we installed the other prerequisite packages above.What's the difference? Devkitpro allows you to run copies of Pokeemerald made both, before and after June 2021, while
binutils-arm-none-eabi
does not.Also keep in mind that devkitPro's developers do not offer support for certain operating systems after X amount of time.
If you came across unexpected errors here, please refer to the FAQ Section of this post.
Choose whichever option you prefer.
devkitPro:
Spoiler:
5) The next thing we'll do is to install devkiPro Pacman.
In order to do this we'll use the following commands:
What these commands do is:
-Download the script called "install-devkitpro-pacman" in whatever folder WSL2 is currently looking at.
- Give root permissions to execute it.
- Execute it.
Next we'll install the GBA Development package of devkitPro by using:
After we input this command, devkitPro Pacman will let us choose specific packages within the gba-dev package to download.
We'll just press Enter to tell it that we want all of them, and then we'll be asked if we want to proceed with the installation, to which we'll say "y" and then press Enter again.
6) Close WSL and open it again so devkitPro will make some variables that it needs for its correct functioning.
You can double check if they were made successfully by typing
If they return the following paths:
Congratulations, now you're ready to build the decomps.
In order to do this we'll use the following commands:
sudo apt install wget
wget https://apt.devkitpro.org/install-devkitpro-pacman
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
What these commands do is:
-Download the script called "install-devkitpro-pacman" in whatever folder WSL2 is currently looking at.
- Give root permissions to execute it.
- Execute it.
Next we'll install the GBA Development package of devkitPro by using:
Code:
sudo dkp-pacman -S gba-dev
After we input this command, devkitPro Pacman will let us choose specific packages within the gba-dev package to download.
We'll just press Enter to tell it that we want all of them, and then we'll be asked if we want to proceed with the installation, to which we'll say "y" and then press Enter again.
6) Close WSL and open it again so devkitPro will make some variables that it needs for its correct functioning.
You can double check if they were made successfully by typing
echo $DEVKITPRO
and/or echo $DEVKITARM
.If they return the following paths:
/opt/devkitpro
and /opt/devkitpro/devkitARM
respectively, then we're done here.Congratulations, now you're ready to build the decomps.
binutils:
Spoiler:
5)
Code:
sudo apt install binutils-arm-none-eabi
Alternatively, if for whatever reason the command above gave you an error, try:
Code:
sudo apt-get install binutils-arm-none-eabi
6) Close WSL and open it again as previous told, Win Key + R ->
wsl
7) Alright, so, we're currently in the root folder of the filesystem of our Linux Ubuntu installation, opened inside of WSL2.
We can either work here directly, or make a folder using the
mkdir
command to work in and move to it using the cd name_of_the_folder
command. It's up to you.Personally, I do my work in my root folder directly. That is, again, the folder that we're taken to when we type
cd
as is.8) Now, we have to clone agbcc, and our desired decompilation project.
Code:
git clone https://github.com/pret/agbcc
git clone https://github.com/pret/pokeemerald
If you came across unexpected errors here, please refer to the FAQ Section of this post.
9) Let's build agbcc and install it in our decomp by using:
Code:
cd agbcc
./build.sh
./install.sh ../pokeemerald
10) And lastly, let's build a ROM.
Code:
cd ../pokeemerald
make -jN
Note2: You can use
nproc
to quickly check the amount of threads your CPU has.(Not Really) Frequently Asked Questions (FAQ):
Spoiler:
1) You said we could install Ubuntu through a .appx package instead of using the Windows Store. Can you please elaborate?
.appx files are packages that act as compressed folders and installers at the same time.
You can download Ubuntu in the form of a .appx package, double click it, and then follow its installation process to get it installed on your computer.
Note: The most commonly suggested distro to stick with is Ubuntu. Make sure to grab the latest version available, which at the time of writing is the v22.04
But, thanks to the fact that they're still compressed folders at their core, we can also (at least in this case) just uncompress the package using WinRAR or 7Zip and use its contents as is.
After decompressing the package, you'll notice it contains a couple of files, a folder with metadata and some .appx packages.
The one you'll want is "Ubuntu_2204.1.7.0_x64.appx". Just put its files in a folder of your choice that you know you won't mess around with, and then execute the Ubuntu.exe file.
As a matter of fact, this is the way in which I install distributions for WSL myself.
Originally found by Subzero Eclipse and later confirmed by a mantainer of devkitPro Pacman's repository, devkitPro cuts support short for certain operating systems without warnings.
Basically, if you got this error you're using a version of Linux Ubuntu that devkitPro-pacman does not support.
What can you do?
You can either uninstall your current version and install a new one, or you can update your version from within your current installation.
I had Ubuntu 20.04, and for unrelated reasons, I had to update to the latest LTS version of Ubuntu myself.
How did I do it? By using the following command:
Code:
sudo do-release-upgrade
This didn't happen to me, but sometimes, there's a chance you'll also need to remove the
snapd
package.That's done by typing in
sudo apt purge snapd
followed by a sudo apt update -y && sudo apt upgrade -y
, in order for sudo do-release-upgrade
to work properly.Type the following commands:
Code:
cd
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata
wsl --install
didn't work, can you tell me how to enable WSL2 manually?You basically have to follow this article written by Microsoft.
In simple terms:
First, you need to enable WSL1 as I already explain in this very tutorial.
Secondly, you need to enable the "Virtual Machine Platform" which is a feature located inside Windows Features' window which I also explain how to access there.
Thirdly, you need to install the WSL Kernel, which can be downloaded from here
Fourthly, you need to open a command prompt and type in
wsl --set-default-version 2
, so any and all Linux distros you install will default to WSL2.And that's it. Go back to the WSL2 tutorial, install Ubuntu normally, and continue from Step 2.
As far as I can think? No, not really.
Porymap and VSCode both work fine on copies of the decomps that are put in the Linux filesystem, so you're pretty much set.
If you need to browse the Linux filesystem, for example to open your project's folder on Porymap, Windows establishes a shared network between Windows and WSL.
If I have a Pokeemerald folder in my Linux Ubuntu filesystem's root folder. I can access it from Porymap by typing a path like
\\wsl$\Ubuntu\home\your_linux_username\pokemerald
.It's the same path that you can see if you open your project's folder on Windows Explorer via
explorer.exe .
.In case of need, I'm keeping an archived copy of this post as a GitHub Gist. Click here to check it.
I'm going to update it whenever I make changes to this post.
And that's pretty much it.
Last edited: