Debugger for GnuCOBOL

Debug COBOL code from VS Code or VSCodium.

An extension to debug or execute GnuCOBOL code. Install from VS Code Marketplace or Open VSX-Registry.

Features

Setting breakpoints
Continue, Stop, Restart, Step Over, Step Into, Step Out
Variables pane, including Copy Value, Copy as Expression and Add to Watch
Watch pane with expressions
Code coverage
No mainframe required
GnuCOBOL Docker

Screenshot

Requirements

A COBOL-syntax extension i.e. bitlang.gnucobol (recommended, note: the previously recommended bitlang.cobol was split and now is intended to target MicroFocus products only), or - if you target a mainframe dialect: broadcommfd.cobol-language-support, rechinformatica.rech-editor-cobol or ibm.zopeneditor installed.
Otherwise, the breakpoints will be unavailable.

Now you may choose between local and container execution environment. Or try both of them :)

Local

GnuCOBOL cobc 2.2+ installed.
GNU Debugger gdb 6.0+ installed.

Container

GnuCOBOL Docker container up and running. The image includes GnuCOBOL, GNU Debugger and all required dependencies needed to debug or execute your code. See an example below.

Usage

When your launch.json config is set up, you can debug or execute your COBOL program. If you debug a Compilation Group (main- and sub- programs), you need to list sub-programs inside group property. Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "COBOL debugger",
            "type": "gdb",
            "request": "launch",
            "cobcargs": ["-free", "-x"],
            "group": ["subsample.cbl", "subsubsample.cbl"]
        }
    ]
}

Pick COBOL debugger from the dropdown on the Debug pane in VS Code. Press the Play button or F5 to debug or Ctrl+F5 to execute.

The debugger uses C sourcecode generated by the compiler upon each debugging session. If the sourcemap isn't accurate or you see any other issues, please make a bug-report.

Code coverage

You can estimate an execution flow of your COBOL program.

Coverage

Set coverage property to true in your launch.json and start debugging session. Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "COBOL debugger",
            "type": "gdb",
            "request": "launch",
            "cobcargs": ["-free", "-x"],
            "coverage": true
        }
    ]
}

The extension decodes the code-coverage files in gcov format generated by the compiler.

Docker

You may debug or execute your COBOL program inside GnuCOBOL Docker container. Start the container and share your working directory by Ctrl+Shift+P and command GnuCOBOL Docker: start, or in the terminal:

docker run -d -i --name gnucobol -w ${workspaceRoot} -v ${workspaceRoot}:${workspaceRoot} olegkunitsyn/gnucobol:3.1-dev
docker exec -i gnucobol cobc -V
docker exec -i gnucobol gdb -v

Add docker property to your launch.json and start debugging session. Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "COBOL debugger",
            "type": "gdb",
            "request": "launch",
            "cobcargs": ["-free", "-x"],
            "docker": "olegkunitsyn/gnucobol:3.1-dev"
        }
    ]
}

Stop the container by Ctrl+Shift+P and command GnuCOBOL Docker: stop, or in the terminal:

docker rm --force gnucobol

Attaching to a running process

You may debug your COBOL program attaching to a running process. In order to achieve that, you have two options:

Local Process

Add pid property to your launch.json and start debugging session (you can use a input variable to help like the sample below). Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "COBOL debugger attach",
            "type": "gdb",
            "request": "attach",
            "cobcargs": ["-free", "-x"],
            "pid": "${input:pid}"
        }
    ],
    "inputs": [
        {
            "id": "pid",
            "type": "promptString",
            "description": "PID to attach"
        }
    ]
}

Remote Debugger (GDBServer)

Add remoteDebugger property to your launch.json. Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "COBOL debugger attach",
            "type": "gdb",
            "request": "attach",
            "cobcargs": ["-free", "-x"],
            "remoteDebugger": "localhost:5555"
        }
    ]
}

Displays application output in a separate window

Add gdbtty property to your launch.json. Here’s an example:

{
            "name": "COBOL debugger",
            "type": "gdb",
            "request": "launch",
            "cobcargs": [
                "-free",
                "-x"
            ],
            "coverage": false,
            "gdbtty": true
}

GdbTTY

Linux Requirements: xterm

How to install xterm on Ubuntu:

sudo apt-get install xterm

On Linux you can see the output of the application in Vs Code itself. Add gdbtty property with vscode value to your launch.json. Here is an example:

{
            "name": "COBOL debugger",
            "type": "gdb",
            "request": "launch",
            "cobcargs": [
                "-free",
                "-x"
            ],
            "coverage": false,
            "gdbtty": "vscode"
}