RiskScape developer guide

​ This assumes that you already have the source code for RiskScape on your machine.

Note

This guide is intended for developers using a Linux-based operating system, such as Ubuntu.

Prerequisites

Java 8

Note

Building RiskScape relies on Java 8 being set as your default JDK. If you cannot install Java 8, you can still use docker to build the RiskScape code - just use the ./bin/docker-gradle.sh installdist command to build RiskScape instead of ./gradlew installdist.

​ The following section will setup Java 8 on your system and is based on the instructions here.

First, start by checking with version you’re running:

java -version

If you are already using Java 8, then it should look something like this:

java -version
openjdk version "1.8.0_292"
OpenJDK Runtime Environment (build 1.8.0_292-8u292-b10-0ubuntu1~20.04-b10)
OpenJDK 64-Bit Server VM (build 25.292-b10, mixed mode)

If your default Java is a different version, follow these instructions to install the Java 8 JDK.

  1. Make sure the Java 8 OpenJDK is installed on your machine:

    sudo apt-get update
    sudo apt-get install openjdk-8-jdk
    
  2. Run the following command and set Java 8 as your default Java version.

    sudo update-alternatives --config java
    

Tip

To remove unnecessary older Java versions, refer to the instructions here.

GIS file viewer

While not strictly necessary for development, we recommend that you have a GIS application installed that will allow you to view shapefile and GeoTIFF files. For example, QGIS can be installed by running:

sudo apt-get install qgis

Installing RiskScape

Building the code

To build RiskScape run the following command:

./gradlew installdist

This will produce a riskscape executable in the engine/app/build/install/riskscape/bin/ sub-directory.

Adding RiskScape to your PATH

  1. Make a note of the full file path to your riskscape executable. For example, if your git repository is ~/code/riskscape, then your RiskScape executable will be ~/code/riskscape/engine/app/build/install/riskscape/bin/riskscape.

  2. Open your ~/.bashrc file in a text-editor. Add the following line to the .bashrc file, replacing the file path with the directory obtained in step 1:

    PATH=$PATH:~/code/riskscape/engine/app/build/install/riskscape/bin`
    
  3. Close and re-open your bash terminal, so that the PATH change takes effect.

  4. Check that RiskScape is now visible on your PATH by running riskscape --version. The output should be similar to the following:

Core Engine v0.10.0 Built Thu Nov 25 15:44:47 NZDT 2021

Plugins:
wizard 0.10.0 nz.org.riskscape.wizard.WizardPlugin
defaults 0.10.0 nz.org.riskscape.engine.defaults.Plugin
cpython 0.10.0 nz.org.riskscape.cpython.CPythonPlugin
postgis 0.10.0 nz.org.riskscape.postgis.Plugin
jython 0.10.0 nz.org.riskscape.jython.Plugin
wizard-cli 0.10.0 nz.org.riskscape.wizard.WizardCliPlugin

Linux 5.11.0-40-generic
Java 1.8.0_292 OpenJDK 64-Bit Server VM 25.292-b10

Tip

Check the Built timestamp in the first line matches when you built RiskScape.

Troubleshooting

If you get an error when you run RiskScape about the JAVA_HOME environmental variable being set incorrectly, then you will need to update it. This may happen if you already had a different JDK version installed. To update the JAVA_HOME variable, run the following command:

export JAVA_HOME=`dirname $(dirname $(readlink -f $(which javac)))

You will need to add this to your ~/.bashrc file so it always takes effect whenever you open a new terminal.

Note that the JAVA_HOME variable may not be set at all on many systems.

Tests

To run all the unit tests, use the following command:

./gradlew check

RiskScape also has integration tests. The newer integration tests extend EngineCommandIntegrationTest and can be run independently in your IDE. Whereas the older integration rely on producing a RiskScape docker image first (via ./bin/docker-build.sh) in order to be run locally.

For more details on the commands required to run all integration tests, refer to .gitlab-ci.yml.

IDE setup

Whatever IDE you choose to use for development, you should check you can run the RiskScape JUnit tests in it successfully, and can use the debugger. For a typical unit test, try running engine/core/src/test/java/nz/org/riskscape/engine/rl/MathsFunctionsTest.java.

Eclipse setup

Here are some tips if you use Eclipse as your IDE.

Installing Lombok

You will need to install Lombok. Download and follow their instructions on how to install it.

Project Set up on Eclipse

  1. Gradle can build the Eclipse project files for you using the following command:

    ./gradlew eclipse
    
  2. In Eclipse, click File -> Import, then select General -> Existing projects into Workspace and click Next.

  3. Under ‘Select root directory’ use your RiskScape git repository. Under ‘Options’ make sure the ‘Search for nested projects’ option is selected. Then under ‘Projects’ click ‘Select All’, and then click ‘Finish’

  4. You may need to build certain files to resolve the Eclipse errors. Try running:

    ./gradlew installDist check
    ./bin/mk-eclipse-dirs.sh
    

If the errors do not disappear, you may need to select your projects in the Project Explorer pane, right-click, and select ‘Refresh’.

If problems persist, you could also try selecting Project menu -> Clean.

Sometimes rebasing may introduce Eclipse errors as new projects or dependencies are added.
You can rebuild your Eclipse project files using the command: ``./gradlew cleanEclipse eclipse``