Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
samples
src
.lfrbuild-semantic-versioning
CHANGELOG.markdown
README.markdown
bnd.bnd
build.gradle

README.markdown

Source Formatter Gradle Plugin

The Source Formatter Gradle plugin lets you format project files using the Liferay Source Formatter tool.

The plugin has been successfully tested with Gradle 3.5.1 up to 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.source.formatter", version: "2.3.295"
	}

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

apply plugin: "com.liferay.source.formatter"

Since the plugin automatically resolves the Liferay Source Formatter library as a dependency, you have to configure a repository that hosts the library and its transitive dependencies. The Liferay CDN repository hosts them all:

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

Tasks

The plugin adds two tasks to your project:

Name Depends On Type Description
checkSourceFormatting - FormatSourceTask Runs the Liferay Source Formatter to check for source formatting errors.
formatSource - FormatSourceTask Runs the Liferay Source Formatter to format the project files.

If desired, it is possible to check for source formatting errors while executing the check task by adding the following dependency:

check {
	dependsOn checkSourceFormatting
}

The same can be achieved by adding the following snippet to the build.gradle file in the root directory of a Liferay Workspace:

subprojects {
	afterEvaluate {
		if (plugins.hasPlugin("base") && plugins.hasPlugin("com.liferay.source.formatter")) {
			check.dependsOn checkSourceFormatting
		}
	}
}

The tasks checkSourceFormatting and formatSource are automatically skipped if another task with the same name is being executed in a parent project.

FormatSourceTask

Tasks of type FormatSourceTask extend JavaExec, so all its properties and methods, like args and maxHeapSize are available. They also have the following properties set by default:

Property Name Default Value
args Source Formatter command line arguments
classpath project.configurations.sourceFormatter
main "com.liferay.source.formatter.SourceFormatter"

Task Properties

Property Name Type Default Value Description
autoFix boolean false Whether to automatically fix source formatting errors. It sets the source.auto.fix argument.
baseDir File The Source Formatter base directory. It sets the source.base.dir argument. (Read-only)
baseDirName String "./" The name of the Source Formatter base directory, relative to the project directory.
fileExtensions List<String> [] The file extensions to format. If empty, all file extensions will be formatted. It sets the source.file.extensions argument.
files List<File> The list of files to format. It sets the source.files argument. (Read-only)
fileNames List<String> null The file names to format, relative to the project directory. If null, all files contained in baseDir will be formatted.
formatCurrentBranch boolean false Whether to format only the files contained in baseDir that are added or modified in the current Git branch. It sets the format.current.branch argument.
formatLatestAuthor boolean false Whether to format only the files contained in baseDir that are added or modified in the latest Git commits of the same author. It sets the format.latest.author argument.
formatLocalChanges boolean false Whether to format only the unstaged files contained in baseDir. It sets the format.local.changes argument.
gitWorkingBranchName String "master" The Git working branch name. It sets the git.working.branch.name argument.
includeSubrepositories boolean false Whether to format files that are in read-only subrepositories. It sets the include.subrepositories argument.
maxLineLength int 80 The maximum number of characters allowed in Java files. It sets the max.line.length argument.
printErrors boolean true Whether to print formatting errors on the Standard Output stream. It sets the source.print.errors argument.
processorThreadCount int 5 The number of threads used by Source Formatter. It sets the processor.thread.count argument.
showDebugInformation boolean false Whether to show debug information, if present. It sets the show.debug.information argument.
showDocumentation boolean false Whether to show the documentation for the source formatting issues, if present. It sets the show.documentation argument.
showStatusUpdates boolean false Whether to show status updates during source formatting, if present. It sets the show.status.updates argument.
throwException boolean false Whether to fail the build if formatting errors are found. It sets the source.throw.exception argument.

Additional Configuration

There are additional configurations that can help you use the Source Formatter.

Liferay Source Formatter Dependency

By default, the plugin creates a configuration called sourceFormatter and adds a dependency to the latest released version of Liferay Source Formatter. It is possible to override this setting and use a specific version of the tool by manually adding a dependency to the sourceFormatter configuration:

dependencies {
	sourceFormatter group: "com.liferay", name: "com.liferay.source.formatter", version: "1.0.767"
}

System Properties

It is possible to set the default values of the fileExtensions, fileNames, formatCurrentBranch, formatLatestAuthor, and formatLocalChanges properties for a FormatSourceTask task via system properties:

  • -D${task.name}.file.extensions=java,xml
  • -D${task.name}.file.names=README.markdown,src/main/resources/hello.txt
  • -D${task.name}.format.current.branch=true
  • -D${task.name}.format.latest.author=true
  • -D${task.name}.format.local.changes=true

For example, run the following Bash command to format only the unstaged files in the project:

./gradlew formatSource -DformatSource.format.local.changes=true