# Conversion Environment Setup¶

## Introduction¶

FWD is both a set of automated conversion tools as well as a runtime used to provide an environment and set of ABL-compatible services for the proper execution of a converted application.

This chapter describes how to create a "minimal" FWD conversion system. The conversion process is written in pure Java and does not have native dependencies. To run in this fashion requires the installation of a pre-built FWD project.

If you do not have a pre-built FWD distribution, then it is highly recommended that you follow the instructions in Building FWD From Source to setup the system as a build environment. A FWD build environment is a superset of the "minimal" conversion system, so it can be used to convert any application project. To use an existing FWD build for a conversion environment, see the Built from Source section. Then check out the Next Steps section of this document.

If you intend for the system to be used as a developer system, please use the Development Environment Setup instead of this chapter.

With these instructions a user can establish an installation in which they can:

• prepare a Progress ABL application project for conversion;
• run the analysis and reporting tools to inspect or otherwise process the 4GL source code;
• run the automated conversion tools to translate the ABL source into an equivalent Java application;
• build/compile the results of conversion such that the application is ready to execute;

The minimal conversion system is not suitable for running the converted application. If you need to execute the converted application, you must have a system on which the FWD runtime components are installed.

For complete information regarding the installation of runtime components of the FWD system, including for use as a production quality runtime installation, please see the Installation, Configuration and Administration Guide.

## System Requirements¶

These are the requirements that are specific to using FWD to convert ABL code into Java.

### Hardware¶

Please see the Conversion System Requirements for details on the hardware requirements.

### Operating System¶

The Java code for automated conversion is "pure Java" and is written to be platform neutral. Although the FWD project does contain some native (JNI) code written in C, the native code is not needed to run conversion. The key requirement for the operating system is that a compatible JDK version is available.

Please see Choosing the Appropriate JVM for details.

### Network Requirements¶

There are no conversion-specific networking requirements.

## Choosing the Appropriate JVM¶

The core requirement for the JVM is that it must be compatible with Java 8.

Each FWD component (conversion, application server, client, user-defined functions running at the database) can use a different JVM. These can run on the same system or different systems. They can even run on a different operating system platform. There is no dependency between JVMs of different components, since they are separate operating system processes.

The following JVM versions have been well tested:

• Oracle JDK 1.8 on Linux
• Oracle JDK 1.8 on Windows
• OpenJDK 1.8 on Linux
• OpenJDK 1.8 on Windows

The specific versions of Oracle JDK 1.8.0_101 and OpenJDK 1.8.0_111 have both been tested and have been found to work well. Generally, it is safe to use any later version of the Java 1.8 platform.

In order to build the converted application, you must have a JDK (Java Development Kit). It is not possible to use the JRE (Java Runtime Environment) since that is a Java distribution which lacks the necessary compiler and tools.

You could use the JRE to run the conversion tools, but then you would have to transfer all the generated Java source code to a different system for compilation. The rest of this chapter assumes that a JDK is in use.

It is possible to run the conversion using either a 32-bit JDK or a 64-bit JDK.

## Installation Process¶

We will assume that the operating system is already installed and up-to-date.

The Linux instructions included here are written (and tested) on Ubuntu 16.04. If the target Linux system is a different distribution, the equivalent commands must be run.

The Windows instructions can be used for any Windows version from Windows XP through Windows 10.

### Install the Java Virtual Machine¶

Please check previous paragraphs for details on how to choose the JDK to install.

Linux Windows
Make sure the bin/ directory of the JVM installation is added to PATH variable of the operating system so the application could be executed by using java command in a terminal window: the PATH for the user should be set to include the directory containing the command line executables (e.g. java or javac) of this installation. In Linux this would be the bin/ directory of the Java installation. In other words, this should be the default installation for any shell or command prompt from which the FWD technology will be built or used.

To install OpenJDK 1.8, following commands can be used:

sudo apt-get install openjdk-8-jdk openjdk-8-source
cd /usr/lib/jvm
sudo rm default-java
sudo ln -s java-8-openjdk-amd64 default-java


It is also recommended to set the user's CLASSPATH to current folder (“.”):
export CLASSPATH=.
Please note that this will only set the variable for the current terminal session. You will need to set this each time your start a new terminal session, if it is needed.

If you are planning to build FWD binaries on Windows make sure to install the accompanying JRE when installing the JDK, this is the default option of the JDK's installer.

Make sure JAVA_HOME system variable exists and points to the location of the installed JDK. The variable is needed by the FWD build scripts to locate the Java build files. If not defined explicitly it would point to the location of the public JRE installed together with the JDK (or any other JRE set as the default one), which is missing the build files, and the build would fail.

Add %JAVA_HOME%/jre/bin/server to the system PATH variable. This ensures that the FWD client spawner process, spawn.exe, locates jvm.dll correctly.

Note:
Because of a bug in how the gcc C++ compiler processes paths (please see #3273 for further information), this value cannot contain spaces!

There two possible approaches to avoid this depending on the current system configuration:

1. System with no JDK yet installed. Install JDK into directory without spaces, like C:\jdk180 for example.
2. System with JDK already installed into something like "Program Files\path to JDK" containing spaces and there are the reasons to keep this configuration. in this case create symbolic link to JDK that has no spaces inside:
mklink /D SomePathWithNoSpaces "The target path\to JDK with\spaces inside"


an example (having C:\ as current directory):
mklink /D jdk180 "Program Files\Java\jdk1.8.0_121"


The quotation in link creation command is mandatory for mklink to properly resolve the original directory. After link has been created it must be used in JAVA_HOME and JRE_HOME environment variables instead of original path with spaces.

As alternative solution to avoid that, use the legacy 8.3 filenames for tokens that contain spaces. In a default Java installation, they are Program Files or Program Files (x86) must be replaced with PROGRA~1 and PROGRA~2 respectively, but they can differ if Windows was reinstalled. Use dir C:\ /X to see actual legacy name for each file/dir, in second to the last column. The value of this environment variable for default installation will look like this:
JAVA_HOME=C:\PROGRA~1\Java\jdk1.8.0_121


The above listed environment variables must be defined system wide so that they are available to all users. On Windows 7, you can access Environment Variables... in Control Panel/System and Security/System/Advanced System Settings, Advanced tab.

### Install Apache Ant¶

The FWD build process (and usually the execution of the various conversion project build tasks) uses Apache Ant (version 1.9 or later).

Linux Windows
Install it using sudo apt-get install ant. Download the ant binaries in the zip archive from official site: http://ant.apache.org/bindownload.cgi. Unpack it to the desired location, set the system variable ANT_HOME to point to the path where ant was unzipped, then include the %ANT_HOME%\bin in the Path.

Use the ant -version command to verify that ant is properly installed. It shows the version of ant.

### Install unzip¶

The commonly available unzip utility can be used to extract files from a ZIP archive. This may be needed to extract the source code from the FWD archive or from some of the other downloaded software (in the case of Windows).

Linux Windows
Install it using sudo apt-get install unzip. Windows does not have the command line unzip.exe tool. To unzip all archive files in ZIP format it is possible to use either Windows GUI zip extractor (zip support is already included in the Windows XP (and above) File Explorer) or if the JDK is already installed the command jar xf some_zipped_file.zip can be used as an equivalent to unzip.

### Install FWD¶

FWD must be present to run the conversion process. There are 2 possible ways to install FWD, built-from-source OR binaries-only.

#### Built From Source¶

Most systems used for conversion are setup as a build environment (see Building FWD From Source) or as a developer system (see Development Environment Setup). In either case, there is a locally built FWD project in place.

The standard conversion project configuration can use a local FWD installation directly. This would be done inside the top level of the conversion project.

Linux Windows
The most common approach is to use a symlink from the conversion project directory to the FWD directory. The following instructions assume that the FWD sources have been built in ~/projects/p2j/ and the conversion project being setup is in ~/projects/hotel/ (we are using the Hotel sample application as the example here).

cd ~/projects/hotel/
ln -s ../p2j/ p2j

Since Windows Vista, symlinks (soft links) are available using the mklink utility. The command is(it is required to run command line as Administrator to complete this task):
cd c:\projects\hotel\


If you encounter You do not have sufficient privilege to perform this operation. you may need to run mklink with elevated privileges (Right-click the Command Prompt shortcut and Run As Administrator). Make sure there aren't any explicit Deny permissions set for the Administrators group on the target directory.
In Windows XP this does not work so it requires copying the full c:\projects\p2j directory instead of making a link. Alternatively, the FWD install can be placed directly on the conversion project directory.

The result is a p2j/ directory in the top level conversion project directory. This is sufficient to support all other conversion processing which is usually automated via an Apache Ant build script.

The "p2j" is a historical name for "Progress 4GL to Java". References to that name are still present in the code. Those references will be removed and/or replaced with references to "fwd", but that work is not yet complete.

As an alternative, you can create the FWD sources directory as a p2j directory in the top level of the conversion project. In other words, instead of installing it elsewhere and using a symbolic link, you just install it directly in the conversion project and build FWD in place. There are advantages to using the symlink approach:

• Multiple conversion projects can share the same FWD build.
• The FWD build can be located in a place that is convenient for development or runtime purposes, but still used for conversion.
• It can be easier to swap out different FWD versions for the same conversion project.

#### Binaries Only¶

To copy only the "binary" files needed for conversion, there are 3 things that need to be manually copied from a pre-built FWD installation:

1. The FWD jar file.

This is named p2j.jar (for historical reasons). Copy it from build/lib/p2j.jar and place it in p2j/build/lib/ on the conversion system.

2. The 3rd party jar dependencies.

The jars on which FWD depends should be copied from dist/convert/*.jar and placed in p2j/build/lib/ on the conversion system.

3. The FWD Conversion Rule-Set XML Files

Once the 4GL source code is parsed into Abstract Syntax Trees, the rest of conversion process is executed in a Java-hosted language environment called TRPL (Tree Processing Language). The TRPL programs are called “rule-sets” and are encoded in XML files. These XML files must exist on the target system and the conversion project configuration will contain a reference to the location of these files. The files can be found in the FWD project under the p2j/rules/ directory path. Copy the entire set of sub-directories of p2j/rules/ to some location on the target system. Each subdirectory will have one or more XML rule-sets.

The entire subdirectory tree under p2j/rules/ should be placed in p2j/rules/ on the conversion system.

It is possible to locate the rules directory to a custom location. In that case, a the conversion project would need to be configured differently using the p2j_rules global configuration option.

## Next Steps¶

The instructions in this chapter are sufficient for getting a running FWD conversion environment. It is important to understand the tasks that may be necessary in addition to the steps documented here. The following tasks may be necessary to provide an environment that supports a specific application conversion project.