Debugging Fortran with GNU GDB in Visual Studio Code

Introduction

Debugging is a crucial part of software development. It helps us identify the source of errors and help us to read and understand people's code. However, debugging in VS Code might be a daunting task, especially for a beginner. At least, that's what I felt when first learning it. Worsely, there are no actual guidelines that are either readily available or helpful.

So, in this post, I'll share with you how to do debugging in VS Code with GNU GDB for programming in Fortran.

VS Code Debugger and GNU GDB

To be fair, VS Code does have great built-in debugging support for programming. It's just that Microsoft never really put Fortran into consideration. Its developments are mostly directed to newer and more popular programming languages like JavaScript, TypeScript, PHP, and many others. Fortunately, the debug system for Fortran is very similar to those in C/C++. Thus, we can use the extensions for C/C++ to help us with debugging Fortran codes.

The debugger we will use is GDB, the GBU Project debugger. It is a very powerful debugger that supports multiple programming languages including C/C++, Rust, Assembly, and of course Fortran. As it is part of The GNU Project, GDB is open-source and can be installed directly together with other GNU tools. In Windows, installation of GDB can be done using the MinGW installer.

Setting Up

Before we start, we need several extensions. You can install these extensions in the extensions menu (Ctrl+Shift+X)

• C/C++
• Fortran Breakpoint Support

The debugger in VS Code is managed through a file called launch.json. This file must be placed in the .vscode folder alongside other VS Code JSON configuration files such as tasks.json. So, the first step, we need to make a file system as the following.

${workspaceFolder}
├── .vscode
│   ├── launch.json     # For debugging <---- create this file
│   ├── settings.json   # For configuring workspace settings
│   └── tasks.json      # For defining tasks
├── bin
│   └── output
├── includes
│   ├── *.mod
│   └── *.f90 
└── src
    └── main.f90

Inside the launch file, we need to define several configurations which you can see below. 3 attributes are mandatory for every launch configuration.

• name acts like the debug process identifier and should be read-friendly because it will show us in the Debug launch configuration dropdown.
• type defines the debugger used for this launch configuration. We will use cppdbg for this attribute.
• request specify the type of request for this launch configuration. As per VS Code version 1.81, only launch and attach are supported and we will choose launch which is typical for compiled programs like Fortran.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/bin/output",
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "externalConsole": false,
            "MIMode": "gdb",
            "preLaunchTask": "compile"
        }
    ]
}

Other attributes are optional and debugger specific.

• program specifies the path to the executable
• stopAtEntry asks the debugger to pause at the first command of the program. This is useful when we are trying to figure out where is the entry point of the project that we want to inspect.
• MIMode indicates the behavior of the debugger. The value is either gdb or lldb. The difference being GDB is a debugger that is part of the GNU project and was created to work along the GNU compiler. Meanwhile, LLDB is a debugger that is part of the LLVM project and was created to work along the LLVM compiler such as Clang and OpenMP.
• cwd is the current working directory
• The preLaunchTask defines a task that the computer needs to do before doing the debug. It is a good practice to make sure all the codes have been compiled correctly. Thus, the task compile here simply asks make to check all the dependencies and make sure the program is ready to be debugged.

Aside from these attributes, you can check other attributes on this page

Debugging

To run VS Code debugger, we need to go to the Run and Debug page. This can be accessed on the menu column which defaults at the left side. The shortcut to access this menu is Ctrl+Shift+D

Then, you can put a breakpoint at the line you want to inspect by marking it with a red dot on the left of the line number similar to the picture below

If you set up the configuration file correctly, the top part of the menu should look like this. And finally, we are ready to debug by pressing the green button on the left of the launch name.

You should now be in the debug mode as shown in the picture below. Notice the command button. From the left, the commands are as the following.

• continue: continue until the next breakpoint or end of the program
• step over: go to the next line in the program
• step into: get into the function and go through its definitions.
• step out: get out from a function and go to the next command.

Conclusion

The GDB debugger is a powerful tool that can be used for debugging Fortran code. Its integration to VS Code, however, needs some tool from the C/C++ extensions which might complicate things if we don't know how to do it.

Reference

• Visual Studio Code documentation
• GDB The GNU Project Debugger
• LLVM Project