This tutorial helps you use the bootstrap command to create a new project for a COBOLcode base.

Overview

In this tutorial you will create a new Semmle project to allow you to analyze the cobol-unit-test code base. cobol-unit-test is an open-source tool for testing individual paragraphs in COBOL programs without requiring a connection to a z/OS system. It is written in COBOL.

The tutorial covers basic use of the odasa bootstrap tool to retrieve source files, start code analysis and export a snapshot of the project.

Create a new project with odasa bootstrap

The quickest way to create a new Semmle analysis project is to use the odasa bootstrap command. The bootstrap tool steps you through the process and generates configuration files that you can reuse later. The process described here gives the steps required to analyze a particular COBOL project built using cobol-unit-test. Other projects will require different responses to some of the bootstrap prompts.

The bootstrap tool's on-screen instructions indicate what you should enter at each step. However, the first time you run it, you may find it useful to refer to the following procedure for some additional information.

Open a command console.

Change to the directory where Semmle Core is installed – for example, /opt/odasa.

The tool guides you through the rest of the process. The remainder of the steps provided below give some additional guidance that you may find useful the first time you run the bootstrap tool.

For additional on-screen information, enter ? at any of the prompts.

Project name

Output from the bootstrap command

*** ODASA Bootstrap ***
(c) Semmle ltd.
Welcome to the ODASA bootstrap utility, which is designed to help you get started by generating a basic configuration file for a new project.
You will be prompted for a series of choices, which will determine the configuration that will be generated. Any time you are prompted for input, you can just enter '?' to see a more detailed explanation of the possible inputs.
Please enter the project name: >

Enter: cobol-unit-test

Project language

Output from the bootstrap command

What is the project language?
- Java [j]: The project is implemented using Java.
- C/C++ [c]: The project is implemented using C or C++.
- C# [C]: The project is implemented using C#.
- COBOL [b]: The project is implemented using COBOL.
- Python [p]: The project is implemented using Python.
- JavaScript/Typescript [J]: The project is implemented using JavaScript and/or TypeScript.
[j|c|C|p|J|?] >

The cobol-unit-test project is written in COBOL.Enter: b

Project source

Output from the bootstrap command

How should ODASA obtain the project source?
- Subversion [s]: The source is in Subversion.
- git [g]: The source is in git.
- Mercurial [m]: The source is in Mercurial.
- Detached [d]: The build should be done in a detached source directory.
[s|g|m|d|?] >

The cobol-unit-test project uses Git as the version control system for its source code.Enter: g

Providing the bootstrap tool with the URL of the repository makes it possible to automatically download the latest version of the software each time an analysis is triggered.

Branch

Output from the bootstrap command

Git branch or ref: [default: <empty>] >

Press Enter without specifying a branch name.

The bootstrap tool will default to cloning the code from the "master" branch for the project.

What to extract

Output from the bootstrap command

Files or directories to extract: [default: .] >

Enter: src/main/cobol

This causes the source code for the main program of the cobol-unit-test code base to be extracted, rather than including any test code or utilities.

Creating a snapshot

You have now supplied all the information needed for the project file that is used each time a snapshot is generated. You can now go ahead and create a snapshot.

Output from the bootstrap command

Do you want to automatically add a snapshot to the project?
- Yes [y]: Add the latest snapshot to the project.
- No [n]: Do not add the latest snapshot to the project.
[y|n|?] >

Enter: y

This tells the bootstrap tool that you want to clone the current cobol-unit-test source files from GitHub and generate files needed to build a Semmle snapshot. This command will be run at the end of the bootstrap process.

Running a set of analyses

Output from the bootstrap command

Do you want to run a set of analyses against the snapshot?
- Yes [y]: Run an analysis suite on the snapshot.
- No [n]: Do not analyze the snapshot at this time.
[y|n|?] >

Enter: y

This tells the bootstrap tool that you want to run a set of queries to analyze the snapshot. This command will be run at the end of the bootstrap process.

Specifying an analysis suite

Output from the bootstrap command

Which analysis suite should be applied? Leave blank for a default set. [default: <empty>] >

Now you can view the analysis results in a SARIF viewer, or import the snapshot database into your IDE and run additional analyses.

If you see parsing errors output to the command line during analysis, it may indicate that your project has a format configuration error or uses mixed source formats. Your analysis will not fail as a result of these errors, but you should check your source format settings to ensure that you are using the correct configuration. For more information on changing the source format, see Configuring COBOL analysis.

Problem solving

If error messages are reported, you can investigate the problem by reviewing the log files:

...\projects\cobol-unit-test\log.log

...\projects\cobol-unit-test\revision--<date>-<time>\log\build.log

...\projects\cobol-unit-test\revision--<date>-<time>\log\import.log

...\projects\cobol-unit-test\revision--<date>-<time>\log\analysis.log

Before rerunning the bootstrap process, enable prototyping mode. This will help with any further troubleshooting you need to do.

What next?

Spend some time investigating the analysis of the cobol-unit-test code base. This will help you familiarize yourself with the standard rules available for COBOL analysis.

Query the snapshot in your IDE

If you install a QL plugin or extension, you can easily write custom queries to analyze snapshots and view the results directly in your IDE.