Get started with SuperBOL Studio

This guide takes about 15 minutes. You will install the tools, create a small project, compile and run a program, configure an existing project, and start a debugging session.

Keyboard shortcuts are given for Windows and Linux; on macOS, use Cmd instead of Ctrl.

Prerequisites

VS Code, or VSCodium or another editor using Open VSX.
GnuCOBOL, to compile, run and debug your programs.
GDB, only for debugging.

Linux

VS Code: download the .deb or .rpm package from code.visualstudio.com, or:

sudo snap install code --classic

GnuCOBOL and GDB, from the packages of your distribution:

# Debian, Ubuntu
sudo apt install gnucobol gdb
# Fedora
sudo dnf install gnucobol gdb
# Arch Linux (GnuCOBOL from the AUR, e.g. with yay)
yay -S gnucobol
sudo pacman -S gdb
# NixOS (temporary shell)
nix-shell -p gnucobol gdb

On NixOS, to install them permanently, add gnucobol and gdb to environment.systemPackages in configuration.nix.

Windows

VS Code: download it from code.visualstudio.com, or:

winget install Microsoft.VisualStudioCode

GnuCOBOL and GDB: our all-in-one installer contains GnuCOBOL, a C compiler and GDB. Choose GnuCOBOL 3.2 (stable) or GnuCOBOL 4.0-alpha.

macOS

VS Code: download it from code.visualstudio.com, or with Homebrew:

brew install --cask visual-studio-code

GnuCOBOL:

brew install gnucobol

Then check in a terminal that everything is installed:

cobc --version
gdb --version

Install the extension

Online

If your computer has Internet access, either:

In VS Code: open the Extensions view (Ctrl+Shift+X), search for SuperBOL and click Install.
From the web: extension page on the Visual Studio Marketplace or on Open VSX.
From the command line, which always installs the latest version:
```
code --install-extension OCamlPro.SuperBOL
```

Offline, with a VSIX file

If you have the .vsix file of the extension, either:

In VS Code: open the Extensions view (Ctrl+Shift+X), click the ... menu at the top of the view, then Install from VSIX… and select the file.

From the command line:

code --install-extension superbol-<version>.vsix

Check the installation

In the Extensions view (Ctrl+Shift+X), check that SuperBOL Studio is installed and enabled.

Create your first project

Create an empty folder on your computer and open it in VS Code with File > Open Folder....
Create a file hello.cob.
Check in the status bar, at the bottom right, that the language of the file is COBOL.

Type the following program. It is written in fixed format, the historical format: division names start at column 8 and statements at column 12.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. HELLO.
       PROCEDURE DIVISION.
           DISPLAY "Hello"
           STOP RUN.

As you type, SuperBOL Studio completes keywords and names. Hover over a name to see its definition, or Ctrl+click it to jump to it.

Compile and run

Press Ctrl+Shift+B and choose SuperBOL: build module. A module hello.so (hello.dll on Windows) appears at the root of the project.
Press Ctrl+F5 (Run > Run Without Debugging) to run the program. It displays Hello.

You can also compile and run from the integrated terminal (Ctrl+Shift+M, then the Terminal tab):

cobc -x hello.cob    # produces an executable
./hello              # hello on Windows

Compilation errors are listed in the Problems panel (Ctrl+Shift+M): click an error to jump to the faulty line.

Configure your project

For an existing project, SuperBOL Studio needs to know how the code is written: where the copybooks are, which source format and which COBOL dialect are used.

Open the settings of the extension: Extensions view, gear icon of SuperBOL Studio, then Settings. Choose the Workspace tab so that the settings only apply to the current project. They are saved in .vscode/settings.json, for example:

{
    "superbol.cobol.dialect": "mf",
    "superbol.cobol.sourceFormat": "fixed",
    "superbol.cobol.copybooks": [
        { "dir": "cpy" }
    ],
    "superbol.forceSyntaxDiagnostics": true
}

Setting	Meaning	`cobc` equivalent
`superbol.cobol.dialect`	Dialect name (`mf`, `ibm`, …) or path to a `.conf` file	`-std=mf` or `--conf=file.conf`
`superbol.cobol.sourceFormat`	Source format (`fixed`, `free`, …)	`-fformat=fixed`
`superbol.cobol.copybooks`	Directories where copybooks are searched	`-I cpy`

By default, syntax errors are only reported for the COBOL 85 dialect. Enable superbol.forceSyntaxDiagnostics (Force Syntax Diagnostics) to see them for other dialects.

Debug

Debugging requires GDB (check with gdb --version) and a program built in debug mode, with the task SuperBOL: build module (debug) (Ctrl+Shift+B).

Set a breakpoint: click in the margin, to the left of a line number, or press F9 on the current line.
Press F5. The program stops on the breakpoint.

Debugging session in SuperBOL Studio: current line highlighted, Variables,
Watch and Call Stack views on the left

Action	Shortcut
Set or remove a breakpoint	`F9`
Continue to the next breakpoint, or to the end of the program	`F5`
Step over: run the line, including a whole `PERFORM` or `CALL`	`F10`
Step into: on a `PERFORM` or `CALL`, stop at its first line	`F11`
Stop the debugging session	`Shift+F5`

The Variables view shows the program’s data; hovering over a variable in the source also shows its value.

Troubleshooting

cobc is not found

The PATH does not contain GnuCOBOL. On Windows, close all terminals and VS Code after installing, then reopen them.

A copybook is not found

Add its directory to superbol.cobol.copybooks (and to -I for cobc).

There are errors everywhere in a file that compiles

The dialect or the source format does not match the code: check superbol.cobol.dialect and superbol.cobol.sourceFormat.

No syntax errors are shown

Enable superbol.forceSyntaxDiagnostics.

The debugger does not stop on breakpoints

The program was not built in debug mode.

If your problem is not listed, cobc --info displays the configuration of GnuCOBOL (C compiler, search paths, libraries): include it when you ask for help.

Next steps

The user manual describes all the features and settings of SuperBOL Studio. To report a bug or suggest an improvement, open an issue on GitHub.

User Manual See the Github project