ci.gradle

The Liberty Gradle plugin supports install and operational control of Liberty runtime and servers. Use it to manage your application on Liberty for integration test and to create Liberty server packages.

• Build
• Usage
• Plugin Configuration
• Tasks
• Extensions

Build

Clone this repository and then, with a JRE on the path, execute the following command in the root directory.

$ ./gradlew build

This will download Gradle, build the plugin, and install it in to the build\libs directory. It is also possible to install the plugin in to your local Maven repository using ./gradlew install.

To build the plugin and run the integration tests execute the following commands in the root directory. The runtime and runtimeVersion parameters are used to select the Liberty runtime that will be used to run the tests. The wlpLicense parameter is only needed for Liberty packaged as a JAR file.

$ ./gradlew install check -Druntime=<wlp|ol> -DruntimeVersion=<runtime_version> -DwlpLicense=<liberty_license_code>

Usage

Gradle Support

The Liberty Gradle Plugin supports running with Gradle 7.6+ and Gradle 8.x as of release 3.7. When using a Gradle wrapper, ensure the wrapper version matches the version of Gradle being used.

Java Support

The Liberty Gradle Plugin is tested with Long-Term-Support (LTS) releases of Java. The plugin, as of release 3.8, supports Java 8, 11, 17 and 21. Versions 3.5 to 3.7.x support Java 8, 11 and 17. Prior to version 3.5, the plugin is supported on Java 8 and 11.

Note: To use the Liberty Gradle Plugin with Java 21, a minimum of Gradle 8.4 is required. Since Gradle does not officially support Java 21 yet, there may be unknown issues. All of our automated tests are passing with Gradle 8.4 though.

Adding the plugin to the build script

Within your Gradle build script, you need to set up the classpath to include the Liberty Gradle plugin. You also need to define the Maven Central repository to find the plugin and its dependencies.

If you are using a snapshot version of the plugin make sure to define the Sonatype Nexus Snapshots repository in addition to the Maven Central repository.

Your build script should look like this:

buildscript {
    repositories {
        mavenCentral()
        maven {
            name = 'Sonatype Nexus Snapshots'
            url = 'https://oss.sonatype.org/content/repositories/snapshots/'
        }
    }
    dependencies {
        classpath 'io.openliberty.tools:liberty-gradle-plugin:3.7'
    }
}

To use the Liberty Gradle Plugin, include the following code in your build script:

apply plugin: 'liberty'

Alternatively, you can apply the plugin through the plugins block. You'll need to add the plugin's runtime dependencies to the buildscript classpath when using this method.

buildscript {
    repositories {
        mavenCentral()
        mavenLocal()
    }
    dependencies {
        classpath ('io.openliberty.tools:liberty-ant-tasks:1.9.13')
        classpath ('io.openliberty.tools:ci.common:1.8.28')
    }
}

plugins {
    id "io.openliberty.tools.gradle.Liberty" version "3.7"
}

Plugin Configuration

Liberty Installation Configuration

The Liberty Gradle Plugin must first be configured with the Liberty server installation information. The installation information can be specified as:

• A Maven artifact
• An existing installation directory - reference the installDir property
• A Liberty server from a Liberty repository or other location

Installing from a Maven artifact is the default installation method. The default runtime artifact is the latest version of io.openliberty:openliberty-kernel.

Example using libertyRuntime property to install an Open Liberty beta runtime:

dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '23.0.0.2-beta'
}

Example using libertyRuntime property to install a specific Open Liberty runtime version:

dependencies {
    libertyRuntime group: 'io.openliberty', name: 'openliberty-kernel', version: '23.0.0.3'
}

In order to configure WebSphere Liberty for installation, specify the libertyRuntime with the com.ibm.websphere.appserver.runtime group and the specific name and version that is needed. For a full list of artifacts available, see the installLiberty task documentation.

Example using the libertyRuntime property to install a WebSphere Liberty runtime from a Maven artifact:

dependencies {
    libertyRuntime group: 'com.ibm.websphere.appserver.runtime', name: 'wlp-webProfile8', version: '22.0.0.12'
}

Additional Configuration

See the Liberty extension properties reference for the properties used to configure the Liberty plugin. See each task for additional configuration and examples.

Tasks

The Liberty plugin provides the following tasks for your project:

Task	Description
cleanDirs	Cleans the Liberty server logs, workarea, and applications folders.
compileJsp	Compiles the JSP files from the src/main/webapp directory into the build/classes directory.
deploy	Deploys one or more applications to a Liberty server.
generateFeatures	Scan the class files of an application and create a Liberty configuration file in the source configuration directory that contains the Liberty features the application requires.*
installFeature	Installs an additional feature to the Liberty runtime.
installLiberty	Installs the Liberty runtime from a repository.
libertyCreate	Creates a Liberty server.
libertyDebug	Runs the Liberty server in the console foreground after a debugger connects to the debug port (default: 7777).
libertyDev	Start a Liberty server in dev mode.*
libertyDevc	Start a Liberty server in dev mode in a container.*
libertyDump	Dumps diagnostic information from the Liberty server into an archive.
libertyJavaDump	Dumps diagnostic information from the Liberty server JVM.
libertyPackage	Packages a Liberty server.
libertyRun	Runs a Liberty server in the Gradle foreground process.
libertyStart	Starts the Liberty server in a background process.
libertyStatus	Checks to see if the Liberty server is running.
libertyStop	Stops the Liberty server.
prepareFeature	Prepares a user feature for installation to the Liberty runtime.
undeploy	Removes applications from the Liberty server.
uninstallFeature	Remove a feature from the Liberty runtime.

*The libertyDev, libertyDevc, and generateFeatures tasks have a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the license. Note: The libertyDev and libertyDevc tasks have this dependency only when auto-generation of features is turned on. By default, auto-generation of features is turned off.

Task ordering

The Liberty Gradle plugin defines a built-in task order to allow a user to call an end task without worrying about calling the necessary tasks in between. By having the plugin manage tasks and their order of execution we can easily avoid some simple human errors. For example, in order to have a majority of the tasks function, the principal task installLiberty must be called, which our plugin would do for you.

The most appealing benefit from defining a task order is the ability to allow the user to call an end task directly. For example, if the user calls libertyStart out of the box, Gradle will recognize that it must call installLiberty -> libertyCreate -> installFeature -> deploy to get a server with features and apps properly running.

Click on a task to view what it depends on.

Extensions

Extensions are tasks that improve the compatibility or user experience of third party libraries used with Liberty. The liberty-gradle-plugin provides the following extensions:

Extension	Description
configureArquillian	Integrates arquillian.xml configuration for the Liberty Managed and Remote Arquillian containers in the liberty-gradle-plugin. Automatically configures required arquillian.xml parameters for the Liberty Managed container.
Spring Boot Support	The Liberty Gradle Plugin supports thinning and installing Spring Boot applications onto the Liberty server.