Skip to content

Latest commit

 

History

History
276 lines (205 loc) · 9.43 KB

development.md

File metadata and controls

276 lines (205 loc) · 9.43 KB

Development

This document contains information for developers who want to contribute to the the project.

How to compile the code

The project uses gradle and a gradle wrapper is included. That means that you can simply execute ./gradlew (on Mac/Linux) or gradlew.bat (on Windows) to run it.

There are a few parameters that can be used in order to customize gradle execution tasks, it follows the list and a brief explanation when the names are not exhaustive:

  • org.gradle.jvmargs
  • FlightRecorderOptions - Used if you want to profile with JFR
  • kotlinVersion
  • serializationVersion - Kotlin serialization apis version
  • jvmVersion
  • reloadVersion - Allows to customize reload version used by jariko

Default values of these parameters are in gradle.properties file.

For example if you want to execute all tests with a specific reload version you can type:

./gradlew -PreloadVersion=yourVersion test

The project contains an ANTLR grammar from which a parser in Java is generated. To generate it run:

./gradlew generateGrammarSource

The code can then be compiled with:

./gradlew build

IDEA 2020

Importing project from github should be enough.

IDEA 2019

After cloning the project, run

./gradlew idea

Then run the tests:

./gradlew test

You are now ready to import the gradle project into IDEA. We suggest to flag the "Automatically import this project on changes in build script files" option in gradle settings.

Here is a short video on how to setup a Linux workstation to develop this project with IDEA 2019

IDEA 2018

Then import in IDEA 2018 using these options:

Idea import project options

It's very important not to check "Create separate module per source set"!!!

Here is a short video on how to setup a Linux workstation to develop this project with IDEA 2018

Running tests

All tests (except for performance tests) can be executed by running:

./gradlew check

To run performance tests (i.e. tests tagged with the annotation @Category(PerformanceTest::class)) run:

./gradlew testPerformance

You can collect data about failed performance tests in a .csv file using:

./gradlew testPerformance -DexportCsvFile="/some/file.csv"

To run all tests:

./gradlew testAll

If you want to force the execution of all checks:

./gradlew check -rerun-tasks

(Side note: if you get this error running tests

com.esotericsoftware.kryo.KryoException: Buffer underflow

try to clean the .gradle directory)

Dependency from develop-SNAPSHOT

This snapshot is published in sonatype, if you want to work with this version you can:

Tests regarding db native access

Jariko uses the reload library.
Since reload needs a configuration that provides, per file or files group, the jdbc settings, you can pass these information through system property jrkReloadConfig.
The value of this property is the path of a json file, and the payload is like this:

{
   "connectionConfigs": [
       {
           "fileName": "*",
           "url": "jdbc:as400://servername/MY_LIB",
           "user": "MY_USER",
           "password": "MY_PASSWORD",
           "driver": "com.ibm.as400.access.AS400JDBCDriver"
       }
   ]
}

This configuration says to reload that all files are:

  • located on as400 server servername: jdbc:as400://servername
  • in library: MY_USER
  • and the user used for the jdbc connection will be: MY_USER

Profiling

You can create a jfr file (java flight recorder) at the end of RPG program interpretation, jfr file path will be showed in console.
This feature allows to evaluate bottlenecks, and improve jariko performance.
Usage:

./gradlew profileRpgProgram -PrpgProgram=path_to_rpg_program

Enabling experimental features

Try new features by implementing a new instance of IFeaturesFactory

Jariko features are modeled by a factory that implements: com.smeup.rpgparser.interpreter.IFeaturesFactory

You can select a factory through system property: -Djariko.featuresFactory=<factory.id>.
Where <factory.id> could be:

  • default
  • experimental
  • Factory class implementation

Configuration for default and experimental factory is in: META-INF/com.smeup.jariko/features.properties

Try new features with feature flags

You can try new features also through the feature flags.
When you run jariko you will see in console something like this:

------------------------------------------------------------------------------------
Creating features factory: com.smeup.rpgparser.interpreter.StandardFeaturesFactory
------------------------------------------------------------------------------------
Feature flags status:
 - jariko.features.UnlimitedStringTypeFlag: off
 - jariko.features.ChainCacheFlag: on
 - jariko.features.ZAddLegacyFlag: off
------------------------------------------------------------------------------------

This it means that jariko is using the default IFeaturesFactory implementation (creating features factory...), but more relevant is the following part of the console message where it is displayed a list of available feature flags and their status.
What you see it means that currently jariko provides two features flag named:

  • jariko.features.UnlimitedStringTypeFlag and its status is off;
  • jariko.features.ChainCacheFlag and its status is on;
  • jariko.features.ZAddLegacyFlag and its status is off.

how to switch on a feature flag at runtime
Before to call jariko as library it is necessary to set the system property like this:

System.setProperty(featureFlagName, "on");

and for example if you want to try jariko.features.UnlimitedStringTypeFlag you can do:

System.setProperty("jariko.features.UnlimitedStringTypeFlag", "on");

A more fine-grained control is possible by using the provided callback by implementing featureFlagIsOn like below:

private val turnOnChainCacheFlagConfig = Configuration().apply {
    jarikoCallback.featureFlagIsOn = { featureFlag: FeatureFlag -> featureFlag == FeatureFlag.ChainCacheFlag }
}
val systemInterface = JavaSystemInterface(turnOnChainCacheFlagConfig)
...

available feature flags and description

feature flag description default
jariko.features.UnlimitedStringTypeFlag when on you ask jariko to force the use of UnlimitedStringType for all rpg alphanumeric types off
jariko.features.ChainCacheFlag when on you ask jariko to use cache in the chain operations on
jariko.features.ZAddLegacyFlag when on you ask jariko to use legacy behaviour for Z-ADD. See the section below for more information. off

Z-ADD Legacy

On AS400 there is a truncation for the entire and decimal part based of source and target declarations. For example:

    D SRC             S              6  0 INZ(241122)
    C                   Z-ADD     SRC           RES               4 0

produces this result: 1122.

   D SRC             S              6  3 INZ(123.456)
   C                   Z-ADD     SRC           RES               4 2

produces this result: 23.45. So, the comma isolates the truncation between entire and decimal part.

Creating a jar with all dependencies to run some examples

You can create a jar that includes all the dependencies:

./gradlew fatJar

This will produce the file

rpgJavaInterpreter-core/build/libs/rpgJavaInterpreter-core-all.jar

So you can run an RPGLE file from the command line this way (after moving to the directory that contains this jar):

java -jar rpgJavaInterpreter-core-all.jar path/to/my/RPGLE [parameters]

Program Search Directories

In order to pass a list of directories containing your sources, you can use the -psd option (Program Search Directories) with a comma separated list of directories:

java -jar rpgJavaInterpreter-core-all.jar -psd /dir/one,/dir/two MYRPG [parameters]

In this short video you can see how to run the examples

See also this animation:

Running interpreter from the command line

If you omit the program name, you will be able to call programs in a simple shell.

The default JVM target for the project is 1.8, but if you want to do some experiments with different JVM targets, you can try to run the gradle build task setting the jvmVersion property. For example:

./gradlew -PjvmVersion=1.6 fatJar

(Hint: the project is not fully compatible with JVM 1.6 :-)

Autoformatting

It can be performed using the task ktlintFormat.

You can check formatting rules using:

gradlew ktlintCheck

We suggest to set the "Kotlin style guide" as the code style for this project: Code style settings