Development Environment Setup
Home -> Developer Guide -> Microsoft Windows Platform Guide -> Windows Development Environment Setup ->
This document was last updated on February 24, 2021.
There are two options for developing Cobol Check on Microsoft Windows:
- Native Microsoft Windows environment
- Windows Subsystem for Linux (WSL)
This document is about setting up the development environment under "native" Microsoft Windows. If you want to use WSL, then you can refer to the Unix and Linux Platform Guide for guidance. If you install Ubuntu under WSL, the instructions will be the same as for other Ubuntu installations.
These instructions assume you are using Microsoft Windows 10.
You need the following tools to help with development of Cobol Check:
- Git client - to access the project repository on Github.
- Java JDK - to compile and run Cobol Check code.
- Gradle - to run builds.
- Cobol compiler - to compile and run the test programs Cobol Check produces.
- IDE or text editor - to modify source code. Cobol Check is written in Java, not Cobol, so you need a tool that is suitable for working with Java.
Note: If your IDE or text editor includes Git support, there is no need to install a Git client separately.
If you are comfortable working on the command line, then all you need is git. It comes with command-line support. You can get this from the Git for Windows project at https://git-scm.com/download/win.
Many Git clients are available for Microsoft Windows. There are basically two ways to go: You can use an IDE extension or plug-in that provides SCM support, or you can install a separate program to interact with Git. With the latter option, you can use a command-line tool or a GUI-based one.
We have no particular preferences or recommendations for a Git client. Regarding SCM support in IDEs, all the mainstream IDEs and smart editors that are practical for working in Java offer plug-ins or extensions for Git. Regarding standalone Git clients, one GUI client that has very good reviews as of this writing is SmartGit from Syntevo. If you prefer a command-line client, you can download the basic one from git-scm.com.
Note: Whatever Git client you choose, please be sure to use the setting to "checkout Windows-style, commit Unix-style line endings".
After completing the installation, view the release notes and make any configuration changes necessary for your environment.
Cobol Check is written to run on Java 1.8 JREs because that is the level supported on z/OS. JDKs for 1.8 may or may not be available, as it is a pretty old release. If you work with a newer release, be sure to set your IDE or editor for 1.8 compatibility.
You have two choices: The official Oracle JDK or OpenJDK. We have no preference or specific recommendation.
The Cobol Check project is set up to use Gradle as the build tool.
If you clone the Cobol Check repository and import the project into IntelliJ IDEA or the Eclipse IDE, the tool will install Gradle for you. If you are using another editor, you may need to install Gradle separately:
Note: For now, use Gradle 6.8 or 6.7. There are some dependencies in the project that won't work with Gradle 7.
Although Cobol Check is written in Java, you will need a Cobol compiler to work with it, as it generates Cobol source code containing test code that it produces by parsing test suites. Commercial Cobol compilers and IDEs are available, and their number is growing; we will not attempt to keep up with those developments on this page. If you have access to such tools, they will be fine for the purpose of contributing to Cobol Check.
Arnold Trembley prepares Windows installers for GnuCOBOL. You can find various packagings of GnuCOBOL on https://www.arnoldtrembley.com/GnuCOBOL.htm. This method has worked well for team members who have installed a development stack on Windows.
The file you download is not a standard Windows installer. It's a self-extracting zip file disguised as a 7-Zip file. It does not create a subdirectory before extraction. It extracts the individual files directly into whatever directory you extract it into.
Here is a suggested procedure:
- Create a home directory for GnuCOBOL, such as \users\you\gnucobol.
- Rename the downloaded file from *.7z to *.exe.
- Move the file into the gnucobol home directory you created in step 1.
- Launch the *.exe and it will extract itself.
- Edit the Environment Variables for your Windows system.
- Edit the Path variable and add the gnucobol directory to it.
This method of installing GnuCOBOL depends on environment variables set by the scripts distributed from Arnold's site. Assuming you have added the installation directory to the Path, you can set the variables in your command line session by running:
set_env.cmd Until you do this, the system will not find the GnuCOBOL executable.
If you prefer to configure your own installation of GnuCOBOL, downloads and installation instructions are available from the GnuCOBOL home page.
Many products are available that can support Java development. The primary development setup for Cobol Check uses JetBrains IntelliJ IDEA. If you prefer a different stack for working with Java, there are no blockers preventing you from using another IDE or editor.
Go to the JetBrains site and follow links to "Developer Tools" and "IntelliJ IDEA". Choose the Community Edition or a paid version, as you prefer. The download link will download an executable installer which you can run as per usual.
Go to the Eclipse installer page and follow the instructions to download the installer. When you run the installer, it will prompt you for a particular version of Eclipse, tailored for different kinds of development. For Cobol Check development, you need the "Eclipse IDE for Java Developers". However, if you already use Eclipse and have one or more other versions installed, you can use whatever version you have.
Go to the VSCode site and choose the download for Windows. This downloads a Windows installer. Run the installer.
Start VSCode and go to the Extension Marketplace. Install the following:
If you will be configuring your environment both as to develop Cobol Check and also to do general Cobol development for mainframes, then follow the guidelines in the User Guide for setting up Cobol Check on Windows. If you are configuring this environment strictly for Cobol Check development, then you don't need to install all the extensions you would install to support Cobol development for mainframes. If you install both, you will see a warning when you start VSCode that redundant extensions are installed. You can dismiss that error message, as there is no harm.
Go to the Vim downloads page and download the "self-installing executable" for MS-Windows. Run the installer. Then you can configure Vim along the lines documented here: Install NeoVim and Plugins (Unix and Linux).
Cobol Check is internationalized. Windows comes with Unicode support, but not with support for various fonts and other features specific to particular languages. You may need to install language packs for the languages referenced in the Cobol Check test suite.
Otherwise, some test cases will fail because Windows cannot map some of the Unicode characters to the default Windows code page.
On Windows, open the Language Settings dialog. Choose "Add" to add a language pack.
Start typing the English name of the language you want to add, and the system will autocomplete the field and present the language in the list below the selection field.
Press "Install" and wait for the system to install the language pack.
Repeat this procedure for each language pack you need to install.
Even after installing language packs, Java might not pick up the correct encoding. If you get an error complaining that characters can't be mapped to windows-1252, try setting the following environment variable:
set JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF8"