modules

Liferay Modules

This document explains how to use Liferay's build system and its recommended best practices.

Build System

Build with Java 8

The default value for source/target compatibility is still Java 7. This is to limit the use of new features only when necessary. In order to use Java 8 features, add these lines in your build.gradle file:

sourceCompatibility = "1.8"
targetCompatibility = "1.8"

Enable Java Compiler Warnings

In order to enable Java compiler warnings when building an OSGi module with Gradle, please set the -D[task name].lint system property (where [task name] is the name of the JavaCompile task to configure) to a comma-separated list of warnings. For example:

./gradlew compileJava -DcompileJava.lint=deprecation,unchecked
./gradlew compileTestJava -DcompileJava.lint=deprecation,unchecked
./gradlew compileTestIntegrationJava -DcompileJava.lint=deprecation,unchecked

Deploy Directory

The module's deploy directory is the deploy.destinationDir property (the destinationDir property of the deploy task). This property is set to liferay.deployDir (the deployDir property of the liferay extension object) by default.

The logic that chooses the default deploy directory is as follows:

• For OSGi modules:

  1. If the project directory contains a .lfrbuild-app-server-lib marker file, the module is deployed to ${app.server.portal.dir}/WEB-INF/lib.

  2. If the project directory contains a .lfrbuild-tool marker file, the module is deployed to ${liferay.home}/tools/${module.dir.name}.

  3. If the project directory contains a .lfrbuild-static marker file, the module is deployed to ${liferay home}/osgi/static.

  4. Otherwise, the module is deployed to ${liferay home}/osgi/portal.

• For themes:

  1. If the project directory is in the main Liferay repository, the theme is deployed to ${liferay home}/osgi/portal-war.

  2. If the required-for-startup property in the src/WEB-INF/liferay-plugin-package.properties file is true, the theme is deployed to ${liferay home}/osgi/war.

  3. Otherwise, the theme is deployed to ${liferay home}/deploy.

If possible, you should always use these marker files to specify the deploy directory of your modules. If none of these cases apply to you, then add something like this to your build.gradle:

liferay {
   deployDir = file("${liferayHome}/osgi/test")
}

To know what paths (e.g., liferayHome) are available, examine the getter methods in the LiferayExtension class.

It's fine to have both .lfrbuild-portal and one of these marker files in the same project; the .lfrbuild-portal file tells the build system to build the module with ant all and the other marker files choose the deploy directory.

Marker Files

Baseline

File Name	Description
.lfrbuild-packageinfo	Ignores specified baseline warnings: EXCESSIVE-VERSION-INCREASE, PACKAGE-ADDED-MISSING-PACKAGEINFO, PACKAGE-REMOVED, PACKAGE-REMOVED-UNNECESSARY-PACKAGEINFO, VERSION-INCREASE-REQUIRED, VERSION-INCREASE-SUGGESTED. Adding the suffix -RECURSIVE (i.e., EXCESSIVE-VERSION-INCREASE-RECURSIVE) will apply the ignored warning to the current directory and all child directories.

Build

File Name	Description
.lfrbuild-portal-deprecated	Marks the module as deprecated and skip deployment during the ant all execution. -test modules never have this file.
.lfrbuild-portal-pre	Builds the module during the ant compile execution in the tmp/lib-pre directory before building portal-kernel, portal-impl, etc.
.lfrbuild-portal-private	Deploys the module during the ant all execution in a private branch. -test modules never have this file.
.lfrbuild-portal-public	Deploys the module during the ant all execution in a public branch. -test modules never have this file.
.lfrbuild-portal-skip-deploy	Skip deploying the module during the ant all execution.
.lfrbuild-portal	Deploys the module during the ant all execution. -test modules never have this file.

Continuous Integration

File Name	Description
.lfrbuild-ci	Deploys the module during the ant all execution, but only if running in Jenkins.
.lfrbuild-ci-skip-test-integration-check	When on Jenkins, prevent the testIntegration task from failing if a project defined in the testIntegrationCompile configuration should not be deployed and has this marker file.
.lfrbuild-semantic-versioning	Enables the semantic versioning check of the module on CI. apps and core modules are already checked, so they don't need this marker file.

Deploy Directory

File Name	Description
.lfrbuild-app-server-lib	Deploys the module to ${app.server.portal.dir}/WEB-INF/lib.
.lfrbuild-static	Deploys the module to ${liferay home}/osgi/static.
.lfrbuild-tool	Deploys the module to ${liferay.home}/tools/${module.dir.name}.

Faro

File Name	Description
.lfrbuild-faro-connector	Deploys the module to the Faro client portal directory.
.lfrbuild-faro-site	Deploys the module to the Faro site portal directory.

LCS

File Name	Description
.lfrbuild-spark-job	Configures the module as an Apache Spark job.
.lfrbuild-spring-boot	Configures the module as a Spring Boot application.

Release

File Name	Description
.lfrbuild-app-portal-build-ignore	Prevents the syncAppProperties task from updating the app.portal.build property in the app.properties file.
.lfrbuild-master-only	Marks a module that should not be forked and deleted for release branches. If a .lfrbuild-master-only file is added to a parent directory, the whole subtree should not be forked.
.lfrbuild-release-src	Includes the app's source code in the DXP release, when added to the root of an app.
.lfrbuild-releng-ignore	Ignores checking the module for stale artifacts. An artifact is stale when the module has code that is different from the latest published release. This module can never be published. If a .lfrbuild-releng-ignore file is added to a parent directory, the whole subtree is ignored.
.lfrbuild-releng-skip-source	Prevents the artifact's source code from being published.
.lfrbuild-releng-skip-update-file-versions	Prevents the updateFileVersions task from converting project dependencies into module dependencies. If a .lfrbuild-releng-skip-update-file-versions file is added to a parent directory, the whole subtree is skipped.

Themes

File Name	Description
.lfrbuild-missing-resources-importer	Prevents the theme from being published in case it doesn't contain the Resources Importer files. This is only added on the master branch.

Source Formatting

Gradle Files

The following source formatting rules should be followed for Gradle files.

• Always use double quotes, unless single quotes are necessary.

• Never define local variables with def; explicitly define the types, even for closure arguments.

• Dependencies:

  • There is usually no need to declare transitive: false for compileInclude or provided dependencies; this is the default behavior.
  • If a module only includes unit tests, add all dependencies to the testCompile configuration. If a module only includes integration tests, add all dependencies to the testIntegrationCompile configuration.
  • Always sort dependencies alphabetically.
  • Separate dependencies of different configurations with an empty line.

• Ordering inside Gradle files:

  1. Class imports, sorted and separated in groups (same logic used in Java).

  2. buildscript { ... } block.

  3. apply plugin logic, sorted alphabetically.

  4. ext { ... } block.

  5. Initialization logic.

  6. Task creation: task taskName(type: TaskType) or simply task taskName for default tasks. Don't declare the task dependencies here.

  7. Project property assignments (e.g., sourceCompatibility).

  8. Variables used globally by the whole script, like a URL or a relative path.

  9. Blocks { ... } to configure tasks, extension objects, etc.

• Inside a block { ... }:

  • If variables are needed, declare them inside the block at the beginning.
  • If setting a property, use the = assignment, even if Gradle doesn't complain when it's not used.
  • If multiple assignments are necessary (for example, multiple dependsOn or multiple excludes declarations), write them on separate lines.
  • Order assignments alphabetically, leaving an empty line after multiple calls to the same method (e.g., after multiple dependsOn declarations) or if the assignment has a closure.

Subrepositories

gradle.properties

The following settings are available to you in the gradle.properties file of a Liferay subrepository (e.g., com-liferay-poshi-runner).

Property Name	Mandatory	Description
com.liferay.source.formatter.version	No	The version of Source Formatter to use in the subrepository. If the property is not set, the latest version is used.
project.group	No	The group ID of the artifacts that are published from the subrepository. If this property is not set, the default value com.liferay is used.
project.path.prefix	Yes	The project path of the Gradle prefix. It must start with a ':' character and be equal to the relative path of the subrepository directory inside the main Liferay repository, with path components separated by ':' characters instead of slashes.
systemProp.repository.private.password	No	The password used to access the private Maven repository. If set, this property must be equal to the build.repository.private.password property value in build.properties.
systemProp.repository.private.url	No	The URL of the private Maven repository. If set, this property must be equal to the build.repository.private.url property value in build.properties.
systemProp.repository.private.username	No	The username used to access the private Maven repository. If set, this property must be equal to the build.repository.private.username property value in build.properties.