(Old) Setting up Visual Studio Code with the disassemblies!
Please note that, if you are on windows, I highly recommend using WSL. The below is a little outdated and I am writing a new tutorial.
Introduction
This is a tutorial on setting up Visual Studio Code for working with the disassemblies. Please keep in mind that this is simply my way of doing things, there are always going to be different ways of setting things up. I am writing this for Windows 10, but setting this up is possible on any OS that supports VS code and Devkitpro. This setup should technically work for any console Makefile project that is C/C++ but you will have to make adjustments where necessary. If you have any improvements or suggestions, please let me know.
While I recommend using Git with your project, I will not be covering it in this tutorial. Here is a useful reference that helped me get started with Git.
[spoiler title=”Download and Install DevkitPro/DevkitARM”]
The first thing you should do is download DevkitPro to install DevkitARM. It can be downloaded from here. The version shouldn’t matter, but I think I read somewhere that Pokeruby may have issues with earlier versions of DevkitARM.
Download and run the installer. I personally install everything but all you really need is “GBA Development” selected.
Running through the installer should be straight forward. Once the installation is done, you will just need to make sure it installed properly. The quickest way is to make sure the environment variables are set and that make can be called from a command prompt.
[/spoiler]
[spoiler title=”Download and Install Visual Studio Code”]
Visual Studio Code is a code editor, by Microsoft, that is open source, Multi-Platform, and supports everything we need for the disassemblies.
It can be downloaded here. The installation is straight forward so I won’t really cover it here. Should you run into any issues with the installation, there are plenty of places to reach out for help.
Once Visual Studio Code is installed, you can install extensions to improve it’s functionality. Please look at the following extensions, they can all be installed from within Visual Studio Code.
C/C++ for Visual Studio Code – Required
This extension adds C/C++ to Visual Studio Code. This is required for the disassemblies.
ARM – Optional
This extension adds syntax highlighting for ASM files. This extension isn’t required, but is very nice to have.
Native Debug – Optional
This extension adds GDB support to Visual Studio Code. This extension isn’t required, but is necessary if you want to use source level debugging.
GitLens — Git supercharged – Optional
This extension adds some nice git related features. This extension isn’t required, but if you are going to be using Git I highly recommend this extension. Please note that you will need Git to be installed for this extension.
[/spoiler]
[spoiler title=”Setting up a Disassembly”]
At this point download or clone the disassembly you want to use. If you are using Pokeruby or Pokeemerald, don’t forget to copy the required tools.
Once that is done, in Visual Studio Code go to “File – Open Folder…” and select the folder for your disassembly.
At this point the project should be loaded and you can start to make changes.
[/spoiler]
[spoiler title=”Building in Visual Studio Code”]
Visual Studio Code has something called tasks that can be used to run shell commands. We’ll have to set some up in order to build.
To get started click on “Terminal – Configure Tasks…”
Then click on “Create tasks.json file from template” when it shows up at the top.
Then click on others.
This will create a tasks.json file. Replace the default with the below and save.
{
"version": "2.0.0",
"tasks": [
{
"label": "Build Debug",
"type": "shell",
"promptOnClose": true,
"command": "make DINFO=1 -j8",
"group": {
"kind": "build",
"isDefault": true
},
"presentation": {
"reveal": "always",
"panel": "new"
},
"problemMatcher": [
"$gcc"
]
},
{
"label": "Build Release",
"type": "shell",
"promptOnClose": true,
"command": "make -j8",
"presentation": {
"reveal": "always",
"panel": "new"
},
"problemMatcher": [
"$gcc"
]
},
{
"label": "Clean",
"type": "shell",
"promptOnClose": true,
"command": "make clean -j8",
"presentation": {
"reveal": "always",
"panel": "new"
},
"problemMatcher": [
"$gcc"
]
}
]
}
These are some basic tasks that can be used to build your ROM. They should be taken as an example and you should customize then to fit your needs.
To run a task go to “Terminal – Run Task…” in the menu.
Then just click on the task you want to run.
You should see the terminal show up at the bottom. The ROM should be building.
[/spoiler]
[spoiler title=”Launching/Debugging from Visual Studio Code”]
You can launch emulators from Visual Studio and even do source level debugging with emulators that support GDB. For this tutorial I will be using mGBAas it supports the GDB feature. Download whatever emulator you plan on using to your computer, you will need to know the path to this emulator.
Go back to the tasks.json file and add the below. Please feel free to adjust the tasks as needed.
{
"label": "mGBA_run",
"type": "shell",
"command": "C:/devkitPro/emulators/mGBA/mGBA.exe",
"args": ["pokeemerald.gba"],
"group": "test",
"isBackground": true
},
{
"label": "mGBA_debug",
"type": "shell",
"command": "C:/devkitPro/emulators/mGBA/mGBA.exe",
"args": ["-g", "pokeemerald.gba"],
"group": "test",
"isBackground": true
}
As you may be able to tell, one of these is for running the game normally and the other is for debugging. At this point you should be able run the game using the “mGBA_run” config.
IMPORTANT NOTE
The “-g” argument is supposed to start mGBA with GDB started. While others have reported that they’ve gotten it to work, I have not. If you have the same experience, you will need to start GDB manually.
Next a launch configuration will be needed for source level debugging to work. This is because Visual Studio Code needs to connect to the emulator in order to debug code.
You may have noticed that a “.vscode” was created when the “tasks.json” file was created. In this folder create a file named “launch.json” and paste in the below code.
{
"version": "0.2.0",
"configurations": [
{
"type": "gdb",
"request": "attach",
"name": "Launch Debug",
"executable": "./pokeemerald.elf",
"target": ":2345",
"remote": true,
"cwd": "${workspaceRoot}",
"gdbpath": "C:/devkitPro/devkitARM/bin/arm-none-eabi-gdb.exe",
//"preLaunchTask": "mGBA_debug"
}
]
}
Please note that you will need to do a debug build for source level debugging to work. This is done by building with “DINFO=1” so that symbol information is generated.
Also note that “preLaunchTask” is commented out because for me I have to start GDB manually. If it works from the command line for you, then you can most likely use this feature.
Let’s set a break point to test the debugging. I’m going to set some in “tittle_screen.c” so that it breaks on the tittle screen.
Next you will need to launch your task for your debug emulator or start it manually. I will show you how to start it manually.
First I’ll launch my “mGBA_debug” task so that the emulator comes up. Go to “Tools – Start GDB server…” in the menu.
From there you should see the below window. Stop and start GDB at this window. You’ll know it’s working when the game pauses.
Next press “F5” in Visual Studio Code to start debugging. Play up until the break point you set. The game should pause and bring you to the related code in Visual Studio Code.
Some people have mentioned that the GDB debugging does not always work as expected, but it should work enough to do some basic debugging. In fact, I even had some issues while writing this tutorial and the above screen shot is from a couple of months ago where I originally got it to work.
[/spoiler]