Docs Developer Site
Enonic Gradle plugins
arrow-down
Developer Docs Enonic Gradle Plugins Stable

XP Gradle Plugins

Contents

These plugins simplify development of libraries and applications for Enonic XP.

For Enonic XP 7.x, use version 3.6.2. For Enonic XP 8.x, use version 4.0.0 or later.

Enonic XP Settings Plugin

This plugin creates a version catalog with Enonic XP dependencies.

Installation

Apply the plugin in your settings.gradle file:

plugins {
  id 'com.enonic.xp.settings' version '4.0.0'
}

Usage

Define xpVersion in gradle.properties:

xpVersion = 8.0.0

The plugin creates a xplibs version catalog with Enonic XP dependencies.

Example usage in build.gradle:

dependencies {
    // Java API dependencies
    implementation xplibs.api.core
    implementation xplibs.api.portal

    // JavaScript Library dependencies
    include xplibs.content
    include xplibs.portal
    include xplibs.context
}

Enonic XP Base Plugin

This plugin simplifies development of libraries and applications for Enonic XP.

This plugin is automatically applied by the Enonic XP App Plugin.

Installation

To install this plugin, just add the following to your build.gradle file:

plugins {
  id 'com.enonic.xp.base'
}

When the Java plugin is applied, the base plugin sets the Java toolchain to version 25 (as a convention default).

Configuration

The base plugin creates the xp {} extension:

xp {
    version = "8.0.0" // in case you need to override `xpVersion` from `gradle.properties`
    homeDir = file("/path/to/xp/home")  // in case you need to override XP home directory
}
Property Default Description

version

xpVersion from gradle.properties

XP version

homeDir

xpHome gradle property, xp.home system property, XP_HOME env variable, or ${buildDir}/xp/home

XP home directory

Usage

Plugin defines a shorthand notation for Enonic repository that contains Enonic XP libraries and API artifacts.

To declare Enonic repository add this to your build.gradle file:

repositories {
  xp.enonicRepo()           // https://repo.enonic.com/public
}

In cases when SNAPSHOT versions of artifacts are needed, it is possible to specify the dev repository that contains both SNAPSHOT and release versions:

repositories {
  xp.enonicRepo('dev') // https://repo.enonic.com/dev
}

Enonic XP App Plugin

This plugin allows building application jar files for Enonic XP.

This plugin automatically applies Enonic XP Base Plugin as well.

Installation

To install this plugin, just add the following to your build.gradle file:

plugins {
  id 'com.enonic.xp.app'
}

Usage

Configuration

Here is the list of supported configuration properties:

app {
    // Application name - unique application key.
    // Default is the `appName` gradle property, or "${project.group}.${project.name}".
    name = "name.of.my.app"

    // Minimum supported XP version for the application. Default is `xp.version`.
    // Also supports version ranges in interval notation (e.g. "[8.0,9)").
    systemVersion = "[8.0,9)"

    // By default, the plugin is using these source paths to simplify development in XP `dev` mode: ["${projectDir}/src/main/resources","${buildDir}/resources/main" ].
    // This property allows overriding these default paths, for example if you want to include sources from other modules.
    devSourcePaths = []

    // Set to `true` to allow applications with development source paths to be published.
    allowDevSourcePathsPublishing = false

    // Set to `true` to restore Gradle archive naming behaviour.
    keepArchiveFileName = false

    // When enabled, registers a `dev` task that runs the `deploy` task in continuous mode (`--continuous`) for development.
    // Set to `false` to disable the default `dev` task, e.g. when defining a custom one.
    createDefaultDevTask = true

    // The task name that the `dev` task runs in continuous mode.
    continuousTaskName = "deploy"
}

Plugin defines two dependency configurations include and webjar

dependencies {
    include xplibs.content
    webjar "org.webjars:momentjs:2.29.1"
}

include dependencies get "private packaged" inside the resulting jar file using Bnd Gradle Plugin. You can find more information about packaging in Bnd Tool documentation.

webjar dependencies content (META-INF/resources/webjars ) is placed into /assets folder inside the resulting jar file. You can find more information about WebJars on https://www.webjars.org/

Usually xpVersion property is defined in gradle.properties 
xpVersion=8.0.0

Building application

Plugin uses built-in Gradle java plugin to build applications.

./gradlew build

By default, starting from version 3.0.0, the plugin generates the jar without version in the file name. You can control it with app.keepArchiveFileName setting.

Deploying application

Plugin defines a deploy gradle task. This task copies the application jar file into "deploy" folder under XP home directory.

./gradlew deploy

There are several ways to specify XP home directory:

  • By specifying xpHome property

./gradlew deploy -PxpHome=/opt/xp

  • By specifying xp.home system property, for instance in gradle.properties

xp.home=/opt/xp

  • By defining Environment variable

export XP_HOME=/opt/xp
SET XP_HOME=C:\xp

Publishing application

Development source paths (X-Source-Paths) are added to the application manifest only when it is built with the -Penv=dev property (the dev task enables this automatically).

By default, the plugin prevents applications that contain development source paths from being published to a Maven repository. Build the application without the -Penv=dev property to publish it:

./gradlew clean publish

You can override this protection with the app.allowDevSourcePathsPublishing setting.

Contents

Contents