Visual Studio Code extension for COBOL.
Getting started
Installation
You can install SuperBOL Studio OSS either directly from within VS
Code, or via a VSIX file.
Installation within VS Code
First, click on the "Extensions" icon in the activity bar on the
left-hand side, or press
Ctrl+Shift+X. Then, type "superbol"
into the search bar to find it, and press its Install button.
You can find further instructions for installing extensions directly
within VS Code on this
page.
Installation via a VSIX file
First, download a VSIX file from the
Marketplace
or Open VSX.
To install the extension from its VSIX file, open VS Code and go to
the the "Extensions" view. In the sidebar, click on the three dots
(⋅⋅⋅) on the top right-hand side (just above search), select
Install from VSIX…. Pick the VSIX file you just downloaded to
install it.
Editing an existing project
To start using the extension on an existing project, open its folder
in VS Code (File > Add Folder to Workspace…). The extension will
start automatically whenever the folder contains files with usual
COBOL filename extensions (.cob, .cbl, .cpy, .cbx).
Then, open the settings (File > Preferences > Settings, or
Ctrl+,), and start typing "superbol…". You will
be presented with a screen that resembles:
From here, you can notably configure:
The COBOL dialect used in the project "superbol.cobol.dialect" (see
here
for a documentation on every available dialect).
In SuperBOL, the default dialect corresponds to GnuCOBOL's default, that supports
many features from dialects such as COBOL2014, IBM, Micro Focus (mf), or GCOS for instance;
The default reference source-format "superbol.cobol.source-format" (see
here
for a documentation on the supported source formats).
When auto is selected, which is the default, SuperBOL (and GnuCOBOL) will
automagically try to guess whether the source is in free or
fixed format. Other source formats need to be configured
explicitly.
The path to copybooks "superbol.cobol.copybooks".
To configure this setting, you will need to select Edit in settings.json. This is
a list, where each entry describes an element of the search path where your
copybooks will be looked for. Each entry must contain a directory name dir,
and may feature an optional file-relative flag. When absent or set to
false, the latter field indicates that the directory name is
either absolute, or relative to the root of the project's directory.
When file-relative is true, the element of the search path is
considered relative to the directory where each main source program
is located.
The copybook extensions "superbol.cobol.copyexts".
To configure this setting, you will need to select Edit in settings.json. This is
a list, where each entry describes a file extension if the copybook name cannot
be found as-is (for example COPY "mycpy.lib").
In SuperBOL, the default option corresponds to GnuCOBOL's default, which
is "cpy", "cbl", and "cob" (searched in upper-case first, and then in
lower-case).
Syntax diagnostics
[!NOTE]
Syntax checks performed by SuperBOL Studio currently cover the
COBOL85 dialect, and some constructions of more recent dialects
supported by GnuCOBOL. Reporting of such diagnostics is currently
disabled for dialects other than COBOL85 to avoid misleading
developers with false diagnostics about syntax errors.
Reporting can be re-enabled for every dialect by setting the Force Syntax Diagnostics flag in SuperBOL configuration settings.
IntelliSense (auto-completion)
When editing a program, you can press Ctrl+Space
to obtain suggestions on valid keywords, user-defined words (data item
or paragraph names), and even complete COBOL sentences. Select an
option with the arrow keys, and press Enter to insert the
selected suggestion.
[!NOTE]
(Temporary limitation)
Suggestions of user-defined words may not comprise symbols that are
defined in the communication, report, or screen section of the data
division. Although user-defined words that occur in configured
copybooks are also suggested,
preprocessor-related variables or phrases are not.
Navigation features
Outline & Breadcrumbs
SuperBOL provides an outline view of your program once you open it,
that you can use to navigate to specific sections or symbols (data
items, paragraphs, etc). The same information is also shown in the
"breadcrumbs"
bar, that is usually located above the text edition area.
Go to Symbol
Symbols shown in Outline and Breadcrumbs views can also be searched
and jumped to by pressing
Ctrl+Shift+O.
Go to Definition
When you want to locate the definition of a data item name in your
source code, position your cursor on its name, right click, and
select Go to Definition (or press F12).
[!NOTE]
(Temporary limitation)
At the moment, definitions that belong to communication, report, or
screen sections of the data division are ignored by the extension.
They will be covered by the first stable release.
Peek Definition
To only have a peek at where such a data item defined, you can
position the cursor on its name, right click, and select Peek > Peek Definition (or press
Ctrl+Shift+F10). You will then be
presented with a view of the location of the corresponding definition,
including if it lies in a copybook.
Go to References
If you want to obtain a list of all references to a named data item,
right click and select Go to References (or press
Shift+F12). You will then view the location of
every reference to this item.
[!NOTE]
(Temporary limitation)
In addition to limitations mentioned in Go to
Definition, references that occur in
EXEC/END-EXEC blocks are also not taken into account yet.
The extension shows inline reference information above definitons of
data items and elements of the procedure division.
The same limitations as for Go to Definition
apply.
[!TIP]
This feature can be turned on or off by tuning the
"editor.codeLens" configuration setting (you can type
Ctrl+, and then codelens to change this
setting).
Hover to Show Copybooks
Ever wondered what was behind a COPY directive? Just position your
cursor over such a statement, and you will be presented with the
contents of the copybook.
To ensure this works correctly, check your "superbol.cobol.copybooks"
and "superbol.cobol.copyexts" settings.
Hover to Show Source Text Replacements
What's more? You can see the source text that results from
replacement by a REPLACE directive in the same way.
Editing
Rename Data Items, Sections, and Paragraphs
You can rename any data item by pressing F2 while your
cursor is positioned on one of its references. The extension will
warn you if a reference to the renamed item appears in a copybook (in
which case the renaming of every reference is not performed).
Sections and paragraphs of the procedure division can also be renamed
in the same way.
The same limitations as for Go to References
apply to this feature.
Exploring the Control-flow
Navigating a graphical representation of a COBOL program's
control-flow proves invaluable when it comes to decipher its overall
logic. To do this, open the command palette (or type
Ctrl+Shift+P), and select SuperBOL: Show Control-flow (you can also right click and select Show Control-flow in the menu). You are then presented with a list of
portions of program to consider (either the entire program, or
individiual sections): select one element to see the corresponding
CFG.
Various settings are provided to tune the rendering of CFGs.
CFG as an arc diagram
A rendering of CFGs as arc diagrams is also available. In this
representation, named sections and paragraphs are laid out vertically,
and arcs show the direction of control-flow between them.
Debugging
In order to debug a COBOL program, you first need to run a build
task with appropriate debug options. Once this is done, you can
launch the compiled program in a debugging session.
[!NOTE]
We recommend that a version of
GnuCOBOL that is at
least as recent as version 3.2 be available on the system running VS
Code. Debug and coverage features respectively assume that
gdb and
gcov are installed.
On Windows systems, users may employ dedicated installers that are
available here.
Linux users may rely on their favorite package manager and install
gnucobol.
Running a Build Task for Debugging
After having opened the program to debug, select Terminal > Run Build Task… (Ctrl+Shift+B), and
then SuperBOL: build (debug).
Launching the Compiled Program for Debugging
If needed, you can place a breakpoint on statements (or paragraph
titles in the procedure division) by clicking on the red dot that
appears when you hover the cursor on the left margin (or with
F9). Click on the red dot or press F9 again to
remove a breakpoint. Then, to launch the program in debug mode,
select Run > Start Debugging (F5). This will run your
program until a first breakpoint if reached, or to completion.
Once stopped on a breakpoint, you can investigate the values of data
items from the program using the VARIABLES panel on the left-hand
side.
Press F10 to step to the next statement, or F5
again to continue until the next breakpoint, or termination of the
program.
Customizing Build Tasks
To customize a build task, you can select Terminal > Configure Default Build Task…, and then SuperBOL: build or
SuperBOL: build (debug) (the latter being the task that is run
whenever you start a debugging session, e.g with F5).
Save the tasks.json as shown. Definitions for this task notably
include a for-debug flag, that instructs the compiler to insert
debug annotations into generated executable files (this effectively
passes flags -ftraceall and -g to cobc). The extra-args
setting can be edited to pass additional arguments to cobc.
Coverage
GnuCOBOL can instrument your programs so they can generate coverage
information at runtime. To enable this feature, you can set the
for-coverage setting to true in the Superbol: build (debug) task
in your tasks.json file (see Customizing Build
Tasks). This flag instructs the extension
to pass the --coverage flag to the cobc compiler.
Generated coverage files are in gcov
format; they are
portable, and you can use them as you would any other coverage file
generated for programs written using other programming languages.
Coverage data can be shown after the execution of a program that was
compiled to generate this information terminates. SuperBOL will
display coverage on a line-by-line basis, by highlighting the lines of
your source code using colors that represent their coverage status.
To enable coverage highlighting, you can open the command palette (or
type Ctrl+Shift+P), and select
SuperBOL: Show Coverage. You can also hide the highlighting with
the command SuperBOL: Hide Coverage, and update it after
re-executing your program with SuperBOL: Update Coverage.
Miscellaneous
Collaborating with other developers
At this point, the settings for your project are stored and managed by
VS Code. However, you may plan to collaborate with developers that do
not use this editor. For instance, they might want to use our mode
for GNU/Emacs, which is located here. Then, we advise you
to let SuperBOL Studio store the configuration in a superbol.toml
file that will be located at the root of the project.
You can make the extension write your current project configuration
into a superbol.toml by entering the command palette (View > Command Palette…, or press
Ctrl+Shift+P), and then selecting the
command SuperBOL: Write Project Configuration.
This will save a superbol.toml file at the root of each currently
opened project directory. Such a file will not store any
user-specific settings, so you can now safely put them under source
control. Extensions dedicated to the edition of TOML files, such as
tamasfe.even-better-toml,
provide the same level of assistance as when you edit
.vscode/settings.json.
[!TIP]
Install the
OCamlPro.SuperBOL-studio-pack
extension to get SuperBOL Studio OSS and tamasfe.even-better-toml
altogether.
Further documentation
You can check further the documentation on using the extension on
this page.
Mode for GNU/Emacs
You can find here a mode that allows you to use the
SuperBOL LSP server with GNU/Emacs.
Using the SuperBOL LSP server with other editors
This
page
documents how to use our LSP server functionnality with other editors.
Building from sources
If you build from a clone of the git repository, make sure to update submodules:
git submodule update --init --recursive
You first need to install a few external dependencies to build the LSP
server and the VSCode extension from sources.
First, you need to install and initialize
opam;
Then you need a recent version[^drom-version] of our build tool
drom. The
easiest way to have it running is via the following command:
opam pin add https://github.com/OCamlPro/drom.git
[^drom-version]: Current version is 0.9.2~dev3 (commit 63a5770).
Install node.js (version >=5.2.0) if it
is not already installed.
You can then install all remaining dependencies, and compile the
LSP server along with the VS Code extension:
make build-deps vsix-release
Resources
