RiskScape developer guide
This assumes that you already have the source code for RiskScape on your machine.
This guide is intended for developers using a Linux-based operating system, such as Ubuntu.
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
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:
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.
Make sure the Java 8 OpenJDK is installed on your machine:
sudo apt-get update sudo apt-get install openjdk-8-jdk
Run the following command and set Java 8 as your default Java version.
sudo update-alternatives --config java
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
Building the code
To build RiskScape run the following command:
This will produce a
riskscape executable in the
Adding RiskScape to your PATH
Make a note of the full file path to your
riskscapeexecutable. For example, if your git repository is
~/code/riskscape, then your RiskScape executable will be
~/.bashrcfile in a text-editor. Add the following line to the
.bashrcfile, replacing the file path with the directory obtained in step 1:
Close and re-open your bash terminal, so that the
PATHchange takes effect.
Check that RiskScape is now visible on your
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
Built timestamp in the first line matches when you built RiskScape.
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.
To run all the unit tests, use the following command:
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
in order to be run locally.
For more details on the commands required to run all integration tests, refer to
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
Here are some tips if you use Eclipse as your IDE.
Project Set up on Eclipse
Gradle can build the Eclipse project files for you using the following command:
In Eclipse, click File -> Import, then select General -> Existing projects into Workspace and click Next.
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’
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``