Building a project using Apache Ant

Setting up Apache Ant

Before you use Apache Ant you need to perform the following set up:

  • For Windows, you need to download and install Apache Ant version 1.10.12 or later:
    1. Visit the Apache Ant Project Welcome page, and in the left-hand pane, click Binary Distributions.
    2. Click apache-ant-1.10.12-bin.zip to download.
    3. Extract the content of the zip file to a new folder.

Once you have Apache Ant installed, you need to configure your environment:

  1. Set the ANT_HOME environment variable to the root directory of the Apache Ant distribution:

    Windows: 

    SET ANT_HOME=<ant_path>

    UNIX: 

    EXPORT ANT_HOME=<ant_path>
  2. Add the Ant binary directory to the PATH environment variable:

    Windows: 

    SET PATH=%PATH%;<ant_path>\bin

    UNIX: 

    EXPORT PATH=$PATH:<ant_path>/bin

Building using Apache Ant

Visual COBOL uses an Apache Ant script, .cobolBuild, to build COBOL projects. This script is automatically generated from the .cobolProj project file.

Existing external build scripts such as makefiles, MSBuild, shell scripts and others can build COBOL applications using .cobolBuild as an Ant build file.

If you use an Ant file from a project developed on a remote machine using the Visual COBOL Development Hub, the application is built on the machine running Ant.

This is how you use .cobolBuild to perform a full build of a project:
From a Windows command prompt:
Tip: If the path specified by -lib contains spaces, enclose it in quotation marks. 
ant -lib "%ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin\mfant.jar" -f .cobolBuild
From a UNIX command prompt: 
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild

You can compile your source code faster on multi-CPU machines if you use parallel compilation. To do this, you must add the mf.buildThreadCount=nn parameter. Where nn specifies the number of CPU threads to use:

From a Windows command prompt: 
ant -lib "%ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin\mfant.jar" -f .cobolBuild -Dmf.buildThreadCount=2
From a UNIX command prompt: 
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild -Dmf.buildThreadCount=2
Restriction: Multi-processor compilation of the sources in a project is only supported for native COBOL. It is not recommended to use with native Object-Oriented COBOL applications.
To perform an incremental build:
From a Windows command prompt: 
ant -lib "%ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin\mfant.jar" -f .cobolBuild -Dmf.forceCompile=false
From a UNIX command prompt: 
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild -Dmf.forceCompile=false
Note: You can avoid having to specify the -lib option by adding the mfant.jar to your CLASSPATH.

For UNIX: 

export CLASSPATH=$CLASSPATH:$COBDIR/lib/mfant.jar

For Windows: 

SET CLASSPATH=%CLASSPATH%;%ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin\mfant.jar
You can combine the mf.buildThreadCount and mf.forceCompile parameters to perform a faster incremental build.
Note: When compiling to multiple executables from the command line, you must specify the -logger parameter to enable the correct log to be output to the console. The parameter also ensures that the exit code from the build is set correctly to indicate success or failure of the build: 
-logger com.microfocus.ant.CommandLineLogger
Alternatively, you can specify the -logger option as an environment variable as follows:

For Windows: 

set ANT_ARGS=-logger com.microfocus.ant.CommandLineLogger

For UNIX: 

export ANT_ARGS=-logger com.microfocus.ant.CommandLineLogger

You can build specific files, instead of the entire project, using the -DfilesList parameter:

From a Windows command prompt: 
ant -lib "%ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin\mfant.jar" -f .cobolBuild -DfilesList="<list-of-files>" <build-config-name>.FileCompile
From a UNIX command prompt: 
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild -DfilesList="<list-of-files>" <build-config-name>.FileCompile

where <list-of-files> is a comma delimited list of program names (including their path relative to the project directory, if applicable), and <build-config-name> is the name of the active build configuration of the project that is set in Project Properties > Micro Focus > Build Configurations. (Note: in cases where the active build configuration name contains spaces, <build-config-name> is the build configuration name with spaces replaced with underscores.)

From the Eclipse IDE:
  1. Click Window > Preferences > Run/Debug > Launching and clear the Build (if required) before launching option, if you do not want to trigger an Eclipse build before each Ant build.
  2. In COBOL Explorer, right-click the .cobolBuild file and click Run As > Ant Build.

You can set your own shell scripts as pre- or post-build events and they execute as part of the .cobolBuild Ant script before or after compiling.

To set pre- or post-build events:

  1. Right-click your project in the COBOL Explorer view and click Properties.
  2. Expand Micro Focus > Build Configurations and click Events for the desired configuration.
  3. Type the code of the script either in the Pre-build event command line or in the Post-build event command line field.
  4. Click Apply and Close.
Note:

If you reference variables in the Events field, you must prefix any linked resource path variables with ${pathVar. and terminate the variable with }. For example, code PROJECT_LOC as ${pathVar.PROJECT_LOC}.

Linked resources path variables are defined in the project's properties as follows:

  1. Right-click your project in COBOL Explorer, then click Properties > Resource > Linked Resources.
  2. See the variables listed on the Path Variables tab.
Parent topic: Compiling COBOL Applications