Conversion Environment Setup¶
- Conversion Environment Setup
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.
These are the requirements that are specific to using FWD to convert ABL code into Java.
Please see the Conversion System Requirements for details on the hardware requirements.
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.
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.
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.
|Make sure the
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
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.
The Oracle JDK 1.8 is a well tested option for Windows. The JDK can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html.
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.
Because of a bug in how the
There two possible approaches to avoid this depending on the current system configuration:
1. System with no
2. System with
mklink /D SomePathWithNoSpaces "The target path\to JDK with\spaces inside"
an example (having
mklink /D jdk180 "Program Files\Java\jdk1.8.0_121"
The quotation in link creation command is mandatory for
As alternative solution to avoid that, use the legacy 8.3 filenames for tokens that contain spaces. In a default Java installation, they are
The above listed environment variables must be defined system wide so that they are available to all users. On Windows 7, you can access
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).
|Install it using
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).
|Install it using
||Windows does not have the command line
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.
|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
cd ~/projects/hotel/ ln -s ../p2j/ p2j
|Since Windows Vista, symlinks (soft links) are available using the
cd c:\projects\hotel\ mklink /D p2j ..\p2j
If you encounter
In Windows XP this does not work so it requires copying the full
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.
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.
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.
|Convert and execute one of the sample conversion projects to test that the installation is working.||Hotel ChUI Demo Application or Hotel GUI Demo Application (both contain the code, project configuration and instructions on how to convert and run them)
|Use one of the sample conversion projects as a template to create a conversion project for another application.||ChUI application or GUI application.
|Copy a working conversion project to the new conversion system.||Backup and Restore of a Conversion Project chapter, FWD Conversion Handbook
|Create a new conversion project from scratch.||FWD Conversion Handbook
© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.