FWD Installation¶

• FWD Installation
  • Introduction
  • System Requirements
    • Hardware
    • Operating System
    • Network Requirements
  • Choosing the Appropriate JVM
  • Installation of Prerequisites
    • Install the Java Virtual Machine
    • Install Apache Ant
    • Install unzip
  • Create a Project Directory
  • Install FWD Source Code
  • Satisfying 3rd Party Software Dependencies
  • Build FWD

Introduction¶

This chapter describes how to install dependencies and build FWD from source code for the purpose of creating a minimal installation that can be used for Code Analytics. This is a subset of a more complete process for Building FWD From Source, which would be suitable for systems that are also used as a Development System or for Conversion. If the system will only be used for Code Analytics, then the process documented here will be sufficient.

FWD is implemented almost completely in Java. This means that the primary dependencies of the Code Analytics environment are a Java Development Kit (JDK), Gradle and the Apache ANT build automation tools.

This Java code does use a range of open source Java modules (packaged as jar files). The corresponding jar files must be present on the system in order to successfully compile the FWD Java code. These dependencies will be automatically downloaded during the build.

Java programs are normally platform neutral. When applications or tools are written in pure Java, it is possible for such code to be run on any operating system or hardware platform that supports the corresponding required level of J2SE (Java 2 Standard Edition).

While the vast majority of the FWD code is written in pure Java, there is a small amount of platform-specific “native” code which is required for FWD at runtime. The Code Analytics does not need any of the platform-specific native code.

The process documented here is designed to build FWD on the system on which you will run FWD (for Code Analytics). Although it is possible to copy the build results from another system, this approach is beyond the scope of this chapter.

This chapter will provide detailed instructions for how to setup this environment. It will also explain how to run the build process once all dependencies are satisfied.

System Requirements¶

These are the requirements that are specific to building FWD.

Hardware¶

Please see the Code Analytics System Requirements for details on the FWD Build hardware requirements.

Operating System¶

The Java code for Code Analytics 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 for Code Analytics. 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¶

By default, the FWD build is written to download its dependencies (3rd party Java libraries) when needed. These will be cached locally and reused. The download is done by Gradle and it typically happens at the following times:

• The first time that FWD is built.
• Whenever the cache is cleared/deleted.
• When a new FWD version requires an updated version or a new dependency.

For this download to occur, Internet access is required. Once downloaded and cached, no further Internet access is needed for building FWD.

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 FWD, 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.

Installation of Prerequisites¶

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.

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

export CLASSPATH=.

mklink /D SomePathWithNoSpaces "The target path\to JDK with\spaces inside" 

mklink /D jdk180 "Program Files\Java\jdk1.8.0_121" 

JAVA_HOME=C:\PROGRA~1\Java\jdk1.8.0_121

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 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).

Create a Project Directory¶

The Code Analytics tools will typically not be running directly on a source code check out of the application. The tools require a certain amount of configuration and scripting that is specific to the FWD technology. It is the equivalent of the setup of everything needed to run a COMPILE of all source code using OpenEdge. The Code Analytics tools must be able to parse all the code and schemata, which is a big part of what an OpenEdge compile is doing.

A separate project directory is created, which will eventually contain the following:

• Configuration files for running Code Analytics.
• Scripts to automate the running of the parsing and analytics tools.
• FWD Code Analytics tools.
• 4GL application source code and schemata.

The location in which all of this will reside is called the "project directory". It can be named anything that is meaningful, most commonly it will be named for the application being processed. For the purposes of this guide, the project directory will be named app_name. Create the directory like this:

mkdir ~/app_name

mkdir c:\app_name

Install FWD Source Code¶

The Code Analytics tools are available starting with FWD v3.1.

The FWD project code is available as a ZIP format archive file in the downloads section of this site. This archive should include all of the source code and supporting files needed to build the FWD project on a given system.

The archive filename is normally in the form fwd_<branch_name>_revision_<revno>_<date>.zip. For this example, assume that the fwd_trunk_revision_11145_20170324.zip is in your home directory. Given this assumption, installation is as simple as the following commands to extract the zip file:

cd ~/app_name
unzip ~/fwd_trunk_revision_11145_20170324.zip

c:
cd c:\app_name
jar xf c:\PathToBundle\fwd_trunk_revision_11145_20170324.zip

A directory ~/app_name/p2j (Linux) or c:\app_name\p2j (Windows) will be created with the source tree of the FWD project. For the remainder of the chapter, the environment variable $FWD (Linux) or %FWD% (Windows) will be a reference to that directory. 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.

This can be "saved" into the environment to simplify subsequent commands:

export FWD=~/app_name/p2j

Satisfying 3rd Party Software Dependencies¶

FWD project depends on a handful of 3rd party software dependencies, for the complete list see the page Software Dependencies. The Java dependencies don't have to be fetched manually, the standard FWD build process takes care of retrieving them automatically.

It is possible to use local versions of jar files on which FWD depends. The build script fetches dependencies from multiple artifact repositories. The first repository it checks is the local project directory local-repo. In order to give the build a local dependency, create the directory $FWD/local-repo (Linux) or %FWD%\local-repo (Windows) and then copy the dependencies in. The expected file structure is /$groupId[0]/../$groupId[n]/$artifactId/$version/$artifactId-$version-$classifier.$extension. So for the artifact com.goldencode:fwd-hibernate-core:4.1.8 the Linux file structure would be $FWD/local-repo/com/goldencode/fwd-hibernate-core/4.1.8/fwd-hibernate-core-4.1.8.jar.

Build FWD¶

FWD automates the build process with the help of Gradle and Ant. The original build environment for FWD was implemented as an Ant build.xml and many of the available tasks are still implemented in that form. The overall build process is now implemented in Gradle, and Gradle will invoke Ant as needed to execute tasks that have not yet been migrated to the Gradle build script. In addition to other build tasks, Gradle handles dependency resolution and downloading of all the Java dependencies.

The project uses the Gradle wrapper, which is an executable script that is included in the source tree itself. This script will download and cache the correct version of Gradle on first usage (or whenever needed). This is why it is not necessary to install gradle manually.

There are multiple build targets that are usable on systems which have a more complete set of build dependencies installed. For example, the most common way to build FWD is to use the all target, but that will attempt to build native code that cannot be built on the minimum installation that is documented here. Instead, it is very important to use the jar target so that only the Java portions of FWD are built.

cd $FWD
./gradlew clean jar

cd %FWD%
gradlew.bat clean jar

This will fetch all the Java dependencies, delete any previously built FWD classes, use javac to compile all the Java source code and create the FWD jar files.

All of the FWD Code Analytics are stored in a file called p2j.jar. That file in turn is dependent upon other jar files, which have been specified in the p2j.jar file's manifest. This means that as long as the p2j.jar can be found in the Java CLASSPATH and those other jar files exist in the same directory, the tools will work properly.

The p2j.jar can be found in the $FWD/build/lib/ directory, along with each of the dependent jar files which are shipped with the FWD project. It is best to use those versions since they are tested and are known to work.

When running FWD commands manually, it will be necessary to use the -classpath $FWD/build/lib/p2j.jar:. parameter on the java command line. If the FWD commands are being run using scripts or Apache Ant then they are already configured to properly set the classpath using this directory.

If you encounter issues running the build, see Troubleshooting.

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.

Next: Gathering Inputs