Debugging Pascal in VS Code

Free Pascal in Visual Studio Code

This article is about setting up things so that you can code, compile and debug Free Pascal from Visual Studio Code.

This can be useful if you’re doing non-GUI work and you don’t want to rely on the full-blown Lazarus IDE. It also allows Windows users to write and test Linux programs using the WSL, which is what I did to test this setup. Note that similar steps can be used to configure VS Code for Pascal on a Mac if that’s your poison. At the very least, this is one more tool at your disposal when working with a legacy codebase.

Special credit goes to Mr Bee from the Pascal Indonesia group, whose article was the basis for mine.

Install Free Pascal

On Windows, you can download and install Free Pascal directly from the website. Note that there is no native Windows 64-bit compiler for the latest version— you’ll need the native 32-bit compiler as well as the 64-bit cross-compiler. The source can be downloaded from a separate link.

In my case, I installed Free Pascal with Lazarus by running apt-get install lazaruson my Ubuntu WSL. This put the source code under /usr/share/fpcsrc/3.0.4 and my lazbuild file under /usr/bin. To install a newer version of Free Pascal, I later followed the steps on the wiki and downloaded the laz and src .deb files made available by Lazarus (these I installed directly using apt install).

This is a bit of an aside, but if you want to run Ubuntu the way I did, this Microsoft article does a pretty good job of explaining the steps for activating the WSL. I used the Manual Installation Steps because I didn’t want to join the Windows Insiders Program.

PowerShell is used to install WSL
PowerShell is used to install WSL

Once the WSL is enabled, you can install a Linux subsystem e.g. Ubuntu from the Microsoft Store. You can verify which WSL distros are installed by running wsl.exe -l -v in PowerShell.

If you install the Remote - WSL extension for VS Code, you can launch the editor straight from your Linux console by typing:

code .

The first time you do this, the VS Code Server will be installed. After that, it will launch VS Code in the context of your Linux subsystem.

Install VS Code extensions

This VS Code extension brings Object Pascal support to VS Code, including code completion, outlining, etc.

If you intend to use this with the Remote - WSL extension, remember to install the extension in the WSL as well, e.g. by clicking the “Install in WSL: Ubuntu” link.

Click “Install in WSL: Ubuntu”

Once the extension is installed, go to File → Preferences → Settings and find the “OmniPascal configuration” section under “Extensions”. For the Free Pascal Source Path, enter the path to a folder that contains the Free Pascal source, e.g.

/usr/share/fpcsrc/3.0.4

You can also set the Lazbuild Path for building Lazarus projects (*.lpi files). Note that this extension allows you to specify the currently active project in the status bar:

OmniPascal in the VS Code status bar

This VS Code extension allows for native debugging. It supports both the GNU Debugger (GDB) and LLDB. For this article, I’ll be using GDB.

Unlike the other extensions I’ve listed, this one is not specific to Pascal and not strictly required. However, it helps by making it easier to distinguish Pascal files from other file types and includes a contribution from Mr Bee himself.

Below is an example of the extension in action:

VSCode Great Icons in action

Configure tasks

In order to do things like run a syntax check, build or clean with VS Code there are a number of tasks to configure. I didn’t have any tasks configured, so I created a new tasks.json file by going to Terminal → Configure Tasks… and choosing “Create tasks.json file from Template” (which created tasks.json in the .vscode folder).

Hint: Consider using user tasks; otherwise, you will have to manually copy these custom tasks into the .vscode folder of each of your Pascal projects.

Get the full task config by following the link

Writing these tasks requires an understanding of how to use the Free Pascal compiler. I used the tasks from Mr Bee on GitHub but trimmed them down extensively (e.g. removing overrides to various global settings, and getting rid of the Jedi Code Formatter stuff). I also had to change the parameters for generating debug info to support GDB. See this wiki page for more information.

The gist file was a little long to embed in the article, so you can find my version of the tasks in GitHub here. Obviously, these can be further tailored in the future, but they should be enough to get you started.

It’s recommended that you run the task fpc: Create Build Folders once before running any of the other build tasks, as this creates directories for the various build artefacts. If these directories don’t exist, the other tasks will fail.

Setup debugging

The debugger is configured in your project’s launch.json file.

You can add one by choosing Run → Add Configuration…, which creates the file launch.json in your .vscode folder. Because you installed the Native Debug extension earlier, you can choose “GDB” from the list, and a default configuration will be created.

Choosing GDB for the launch configuration

Modify the target setting to point to the debug path from your tasks.json file. You can also tell VS Code to run the default build task first, which I have set up to do a debug build. For example:

launch.json for debugging with GDB

Once you’ve built your executable, you should be able to launch it with the normal VS Code run commands:

Start Debugging in VS Code

You can now set breakpoints and debug your Free Pascal project in VS Code.

If you are not able to set breakpoints, it’s possible you have to enable the allowBreakpointsAnywhere setting in VS Code.

Allow setting breakpoints in any file

If your breakpoints aren’t being hit, check that your binaries were generated with debug information included. If you used my task fpc: Build Debug from the gist, you should be OK for GDB.

Used for this article

  • Free Pascal 3.0.4
  • Lazarus 2.0.6
  • Native Debug 0.25.0
  • OmniPascal 0.18.0
  • Ubuntu 20.04.1 LTS (WSL)
  • Visual Studio Code 1.53.2

Software developer walking the edge between legacy systems and modern technology. I also make music: https://soundcloud.com/stephanbester