Skip to content

Development environment

This section explains how to install and configure the software needed to develop and run NPL code.

Package manager

You might want to install Homebrew - The Missing Package Manager for macOS (or Linux). It is a package manager similar to apt-get, yum, or rpm, and on macOS you will definitely need it.

Just copy the shell command from the homepage, paste it into a terminal window, and it will be installed on your machine.

JDK

You can install Java through your operating system package manager or by downloading it from the OpenJDK website. The NOUMENA Platform requires at least Java 17.

Working with multiple Java versions

A convenient way to manage multiple Java versions is sdkman. To install it, open a terminal and type

curl -s "https://get.sdkman.io" | bash
source "~/.sdkman/bin/sdkman-init.sh"

A list of the available Java versions can be obtained with

sdk list java

To install a particular Java version, use the Identifier of the last column, e.g.

sdk install java 17.0.5-tem

If you for some reason need to use other versions of Java on your system, you can use sdkman to install them and switch between them on the fly.

Apache Maven

Maven is needed to work with NPL. There is a maven plugin that handles NPL compilation, runs unit tests at build-time, generates kotlin stubs, and generates UML diagrams.

Installation

Install maven with your package manager, e.g.

brew install maven

on macOS, or

sudo apt install maven

on Linux.

Using the Noumena Digital package repository

After installing Maven, access to Noumena Digital's Maven package repository must be configured in ~/.m2/settings.xml (the user's Maven settings).

Noumena provides a script which can be used to generate an appropriately configured ~/.m2/settings.xml. It can be invoked as follows:

bash <(curl -s https://documentation.noumenadigital.com/mavenscript.sh)

Two variables need to be provided for the script: GitHub username and GitHub token.

The latter can be generated here. Please make sure that the token has an expiration date and that only relevant scope permissions are selected.

This script will make a backup of your old settings.xml file.

Maven troubleshooting checklist

If you're experiencing Maven-related issues, please double-check the following items:

  • Do you have a ~/.m2/settings.xml file that contains both your Github username and access token (should look something like ghp_CEVM0QKwj5gV8t6FIhdzIZ79onHPzOHNt9WH)?
  • When the pom.xml file in your project refers to packages provided by Noumena Digital, are the specified versions actually available in the corresponding GitHub package repository?
  • Does the pom.xml refer to any snapshot versions (0.0.1-SNAPSHOT)? If it does, you should probably replace those snapshot versions with actual versions, as we don't distribute snapshot versions.

Docker

Docker is an application containerisation framework, which is used to build containers to install and migrate NPL. We use docker-compose to run the whole stack locally.

Installation

Go to https://docs.docker.com/get-started/ and follow the installation instructions there.

After installation, you should adjust Docker's resource usage:

  1. From the Docker menu in the top status bar (the whale icon) select Preferences... or click on the gears icon in the Docker Desktop window.
  2. Select Resources → Advanced and set CPUs to 6 and Memory to 5GB. Some projects may need as much as 8GB. Swap can stay at 1GB.

These values are the suggested settings for a 2018 MacBook Pro with 16GB Memory, but your mileage may vary.

Docker Machine

If you need to access remote Docker environments, docker-machine is a useful tool for doing so. You can install it with your package manager, on macOS use

brew install docker-machine

IntelliJ IDEA

We recommend using JetBrains' IntelliJ IDEA.

Combined with our NPL-Dev plugin, this environment supports the programmer in various useful ways, such as syntax checking and highlighting, automatic compilation, a test runner, an NPL debugger, and other features.

The NPL-Dev plugin is supported on the newest version of IntelliJ IDEA.

Installing IntelliJ IDEA

The recommended way to install IntelliJ IDEA is via the JetBrains Toolbox App because it can perform automatic updates.

  1. Go to https://account.jetbrains.com/ and create an account.
  2. Go to https://www.jetbrains.com/toolbox/app/ and download the JetBrains Toolbox App.
  3. Login via the dialog using your account, and click Install for the IntelliJ IDEA Community Edition.

Once installed, IntelliJ IDEA can be started from the JetBrains Toolbox App.

Choosing the right JDK version

Some IntelliJ versions ship with Java 1.8, while the NPL-Dev plugin requires Java 17 or newer for all features to work.

If your copy of IDEA already is using Java 17 or newer, you can skip ahead to Installing the NPL-Dev plugin.

Configuring IDEA

  1. Go to File -> Project Structure | SDKs, press +, then JDK and locate JAVA_HOME for your Java installation.
  2. Save the configuration.

Installing the NPL-Dev plugin

Follow these instructions.

The NPL compiler can now be activated through the Build menu of IDEA.