Target Platform Gradle Plugin

The Target Platform Gradle plugin helps with building multiple projects against a declared API target platform. Java dependencies can be managed with Maven BOMs and OSGi modules can be resolved against an OSGi distribution.

The plugin has been successfully tested with Gradle 4.10.2.

Usage

To use the plugin, include it in your build script:

buildscript {
	dependencies {
		classpath group: "com.liferay", name: "com.liferay.gradle.plugins.target.platform", version: "1.1.13"
	}

	repositories {
		maven {
			url "https://repository-cdn.liferay.com/nexus/content/groups/public"
		}
	}
}

There are two Target Platform Gradle plugins you can apply to your project:

  • The Target Platform Plugin helps to configure your projects to build against an established set of platform artifacts, including Java and OSGi dependencies.

    	apply plugin: "com.liferay.target.platform"
    
  • The Target Platform IDE Plugin is a superset of the Target Platform Plugin (it applies the above plugin) and also adds IDE integration for searching and debugging source code in the target platform artifacts.

    	apply plugin: "com.liferay.target.platform.ide"
    

Since the plugin automatically resolves target platform configurations as dependencies, you must configure a repository that hosts these artifacts. The Liferay CDN repository hosts them all:

repositories {
	maven {
		url "https://repository-cdn.liferay.com/nexus/content/groups/public"
	}
}

Target Platform Plugin

The plugin applies the Spring Dependency Management Plugin and then adds several specific configurations to configure the BOMs that are imported to manage Java dependencies and the various artifacts used in resolving OSGi dependencies. Also, a new resolve task is added to resolve all OSGi requirements against a declared distribution artifact.

The plugin adds a series of configurations to your project:

NameDescription
targetPlatformBOMsConfigures all the BOMs to import as managed dependencies.
targetPlatformBundlesConfigures all the bundles in addition to the distro to resolve against.
targetPlatformDistroConfigures the distro JAR file to use as base for resolving against.
targetPlatformRequirementsConfigures the list of JAR files to use as run requirements for resolving.

The plugin adds a task resolve of type ResolveTask to your project that performs an OSGi resolve operation using the targetPlatformRequirements configuration as the basis of the requirements. The targetPlatformBundles configuration is used as a repository for the resolver to resolve requirements. Lastly, the targetPlatformDistro configuration is used to provide the distro artifact for the resolve process. The distro is the artifact that provides all the OSGi capabilities of the target platform. All of these parameters are used to create a bndrun file that can be used as input into the Bndrun resolve operation.

Target Platform IDE Plugin

The plugin applies the Target Platform and the eclipse plugins to your project, and also adds a special targetPlatformIDE configuration, which is used to configure both the eclipse model and idea plugin model in Gradle to add all target platform artifacts to the classpath so they are visible to both Eclipse and IntelliJ’s Java Model Search (for looking up sources to classes).

Project Extension

The Target Platform plugin exposes the following properties through the extension named targetPlatform:

Property NameTypeDefault ValueDescription
ignoreResolveFailuresbooleantrueWhether to ignore resolve failures found when executing tasks of type ResolveTask.
subprojectsSet<Project>project.subprojectsThe subprojects to configure with target platform support, including dependency management and the resolve task.

The same extension exposes the following methods:

MethodDescription
TargetPlatformExtension applyToConfiguration(Iterable<?> configurationNames)Adds additional configurations to configure the BOMs that are imported to manage Java dependencies and the various artifacts used in resolving OSGi dependencies.
TargetPlatformExtension applyToConfiguration(Object... configurationNames)Adds additional configurations to configure the BOMs that are imported to manage Java dependencies and the various artifacts used in resolving OSGi dependencies.
TargetPlatformExtension onlyIf(Closure<Boolean> onlyIfClosure)Includes a subproject in the target platform configuration if the given closure returns true. The closure is evaluated at the end of the subproject configuration phase and is passed a single parameter: the subproject. If the closure returns false, the subproject is not included in the target platform configuration
TargetPlatformExtension onlyIf(Spec<Project> onlyIfSpec)Includes a subproject in the target platform configuration if the given spec is satisfied. The spec is evaluated at the end of the subproject configuration phase. If the spec is not satisfied, the subproject is not included in the target platform configuration.
TargetPlatformExtension resolveOnlyIf(Closure<Boolean> resolveOnlyIfClosure)Includes a subproject in the resolving process (including both the requirements and bundles configuration) if the given closure returns true. The closure is evaluated at the end of the subproject configuration phase and is passed a single parameter: the subproject. If the closure returns false, the subproject is the resolution process.
TargetPlatformExtension resolveOnlyIf(Spec<Project> resolveOnlyIfSpec)Includes a subproject in the resolving platform configuration if the given spec is satisfied. The spec is evaluated at the end of the subproject configuration phase. If the spec is not satisfied, the subproject is not included in the target platform configuration.
TargetPlatformExtension subprojects(Iterable<Project> subprojects)Includes additional projects to be configured with Target Platform support.
TargetPlatformExtension subprojects(Project... subprojects)Includes additional projects to be configured with Target Platform support.

Tasks

ResolveTask

The purpose of this task is to resolve an OSGi module (or all OSGi modules of subprojects) against the available targetPlatformBundles and targetPlatformDistro configurations. By default, the targetPlatformBundles are all the artifacts created by all the subprojects. The targetPlatformDistro must be set explicitly to a valid distribution artifact. When the task is performed, a bndrun file is generated using the specified targetPlatformDistro as the -distro instruction; the -runrequirements are a set of osgi.identity requirements for the targetPlatformRequirements configuration. If the resolve operation is able to find a valid set of -runbundles that match the -runrequirements, then the task passes successfully (the resolution is valid). If a set of run bundles can’t be found, the resolution has failed and the failed requirements are listed as output of the task.

Task Properties

Property NameTypeDefault ValueDescription
bndrunFileFilenullIf this property is specified, it is used as the bndrun file to input into the resolver.
bundlesFileCollectionFileCollectionAll JAR files of subprojects with jar taskThe input to bndrun resolve operation.
distroFileCollectionFileCollectionnullThe distro parameter for the generated bndrun file.
ignoreFailuresbooleanfalseWhether the resolve task should ignore failing the build for resolution errors.
offlinebooleannullWhether to run the bndrun resolve operation in offline mode.
requirementsFileCollectionFileCollection

For the root project: All the output JAR files of the subprojects.

For subprojects: The output JAR file of the subproject.

For each resolve operation, the requirements must be specified in the bndrun file; each of the JARs in this collection generate an osgi.identify requirement in the bndrun file.

Additional Configuration

There are additional configurations that you can use to configure the target platform.

Target Platform BOMs Dependency

The plugin creates a configuration called targetPlatformBOMs with no defaults. You can use this dependency to set which BOMs to import to configure your target platform.

dependencies {
	targetPlatformBOMs group: "com.liferay", name: "com.liferay.ce.portal.bom", version: "7.1.0"
	targetPlatformBOMs group: "com.liferay", name: "com.liferay.ce.portal.compile.only", version: "7.1.0"
}

Target Platform Bundles Dependency

The plugin creates a configuration called targetPlatformBundles. It is configured with default dependencies to all resolvable bundles in a multi-project build (e.g., all projects in multi-project build that have a jar task). This can be used to specify additional bundles that should be added to the set of bundles given to resolve task to resolve against when checking for OSGi requirements.

dependencies {
	targetPlatformBundles group: "com.google.guava", name: "guava", version: "23.0"
}

Target Platform Distro Dependency

The plugin creates a configuration called targetPlatformDistro. It is has no default so you must specify which artifact you want to use as the distribution to resolve against.

dependencies {
	targetPlatformDistro group: "com.liferay", name: "com.liferay.ce.portal.distro", version: "7.1.0"
}

If you have created your own custom distro JAR that is available locally, you can use the files method to add it to the configuration.

dependencies {
	targetPlatformDistro files("custom-distro.jar")
}

Target Platform Requirements Dependency

The plugin creates a configuration called targetPlatformRequirements. It is configured with default dependencies to all resolvable bundles in a multi-project build (e.g., all projects in multi-project build that have a jar task). This is can be used to specify additional bundles that should be added to the set of bundles given to the resolve task to set as osgi.identity requirements.

dependencies {
	targetPlatformRequirements group: "com.liferay", name: "com.liferay.other.bundle", version: "1.0"
}
« Soy Gradle PluginTheme Builder Gradle Plugin »
Was this article helpful?
0 out of 0 found this helpful