Getting started with developing an NPL Contributor Library
New feature (added in 2024.1.4)
An NPL contributor library lets you package NPL constructs such as types and functions and share them with your NPL community. Referencing and declaring protocols is currently unsupported. Consider developing an NPL contributor library when several projects share similar NPL constructs.
Writing an NPL Contributor Library and general guidelines
The general components/layout of such a project are:
- the
src/main/npl/sample
andsrc/test/npl/sample
directories - the
src/main/resources/config.json
file - usage of the
maven-assembly-plugin
and its assembly filesrc/main/resources/assembly.xml
sample
should be replaced with an appropriate name for your project. All your NPL source files should be contained
under 1 main directory.
The config.json
for now only supports specifying a platform minimum version. This version is not checked while
developing and testing but is checked when running a final release version of engine
. SNAPSHOT and RC versions of
engine
will not check this platform minimum version. Such a config.json
should be structured as following:
{
"platform": {
"minimum_version": "2024.1.1"
}
}
The maven-assembly-plugin
is responsible for packaging the config.json
and your NPL source files into a single NPL
contrib zip file. Its configuration file src/main/resources/assembly.xml
contains parameters for assembling it. The
assembly.xml
should be configured as following:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
<id>zip</id>
<includeBaseDirectory>true</includeBaseDirectory>
<formats>
<format>zip</format>
</formats>
<fileSets>
<fileSet>
<directory>${project.basedir}/src/main/npl/sample</directory>
<outputDirectory>/sample</outputDirectory>
</fileSet>
</fileSets>
<files>
<file>
<source>${project.basedir}/src/main/resources/config.json</source>
<outputDirectory>/</outputDirectory>
</file>
</files>
</assembly>
Versioning
You are free to choose how to version your NPL contributor library source files and your produced zip file. However, we
recommend to version your NPL source files using a major version namespace & directories such as v1
and v2
. This
should make your life easier for patch & minor releases.
All versions of your NPL contributor library source files should be present in a single zip file for every release. Clients using your NPL contributor library defined NPL constructs must continue to use it once they use it in production, otherwise their environment will break.
Packaging
After executing mvn package
or mvn install
a zip file named npl-contrib-sample-0.0.1-SNAPSHOT.zip
will be
available. This zip
file can then be used as a dependency in any NPL project.
Deployment
You are free to choose where & how to publish your zip artifact as long as it supports Maven.
Integrating an NPL Contributor Library into an NPL project and in IntelliJ
To see a working example, git checkout our npl-starter
project and peruse its pom.xml
. If you can't, continue
reading.
To your NPL project pom.xml
:
-
Add the published, or locally installed SNAPSHOT, NPL contrib as a zip dependency
-
Add the
maven-dependency-plugin
before thenpl-maven-plugin
in theplugins
section and specify where to copy the zip dependency. TheoutputDirectory
should be the location where all your NPL contrib libraries are located for your NPL project. This is the same directory as your configurednplContribPath
of thenpl-maven-plugin
, which defaults to${project.basedir}/npl-contrib
. -
Add the
npl-contrib
goal of thenpl-maven-plugin
. It will create annpl-contrib.properties
file at the root of your project to make the all zip files innpl-contrib
discoverable for development using IntelliJ and thenpl-idea-plugin
. It is safe to add thisnpl-contrib.properties
to your.gitignore
.
<project>
<dependency>
<groupId>com.noumenadigital.platform</groupId>
<artifactId>npl-contrib-sample</artifactId>
<version>${platform.version}</version>
<type>zip</type>
</dependency>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-npl-contrib</id>
<goals>
<goal>copy-dependencies</goal>
</goals>
<!-- important step: the phase should be `generate-sources` -->
<phase>generate-sources</phase>
<configuration>
<!-- important step: `outputDirectory` should match `nplContribPath` of `npl-maven-plugin` -->
<outputDirectory>${project.basedir}/npl-contrib</outputDirectory>
<includeGroupIds>com.noumenadigital.platform</includeGroupIds>
<includeArtifactIds>npl-contrib-sample</includeArtifactIds>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.noumenadigital.platform</groupId>
<artifactId>npl-maven-plugin</artifactId>
<version>${platform.version}</version>
<executions>
<execution>
<goals>
<goal>npl-contrib</goal> <!-- important step: this goal must be included -->
<goal>npl-compile</goal>
<goal>npl-test-compile</goal>
<goal>npl-test</goal>
</goals>
</execution>
<configuration>
<!-- important step: should match the `outputDirectory` of the `copy-npl-contrib` execution of `maven-dependency-plugin` -->
<nplContribPath>${project.basedir}/npl-contrib</nplContribPath>
</configuration>
</executions>
</plugin>
</plugins>
</build>
</project>
Before the npl-contrib
files can be discoverable in IntelliJ, mvn generate-sources
or mvn compile
will need to be
executed. Alternatively, IntelliJ's Build
can be configured to execute mvn compile
before a Build
and before a
Rebuild
by using the Maven lifecycle configuration window pane in IntelliJ.