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 (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 (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. 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.
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 some sections of the data division.
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).
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)
At the moment, definitions that belong to some sections of the
data division, and some references to data items, are ignored by the
extension. They will be covered by the first stable release.
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.
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.
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, as well as
extra-args, that can be edited to pass additional arguments to the
cobc compiler.
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 Section Customizing Build
Tasks).
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
