# FWD Installation¶

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

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

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.

## 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:

Linux Windows
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:

Linux Windows
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: Linux Windows export FWD=~/app_name/p2j  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. Go to the Control Panel/System/Advanced System Settings/Environment Variables and add system environment variable with name FWD and value c:\app_name\p2j. This will set it persistently for all future command prompts. You can create and assign the environment variable for the current command prompt using set FWD=c:\app_name\p2j. This will be valid within current session only. ## 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. Linux Windows Use the gradlew script to build: cd$FWD

Use gradlew.bat to build:

cd %FWD%


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.