Intro to Gradle Lint Plugin

1. Overview

In this article, we’ll explore the gradle-lint plugin.

First, we’ll see when to use it. Then, we’ll walk through the plugin configuration options. Next, we’ll use some of its predefined rules. Finally, we’ll generate lint reports.

2. What’s Gradle Lint Plugin?

The Gradle Lint plugin helps with linting Gradle configuration files. It enforces build script structure throughout our code base. The plugin can keep the Gradle Wrapper version up to date, prevent bad practices across build files, and remove unused dependencies.

Practically, we use predefined rules or write custom ones. Then, we configure the plugin to consider them as violations or ignore them. The linter runs at the end of most Gradle tasks.

By default, it doesn’t modify the code directly but shows warnings instead. That’s helpful because other Gradle tasks won’t fail due to the plugin. Additionally, those warnings won’t get lost since they are visible at the end of the logs.

Furthermore, gradle-lint provides a fixGradleLint command to auto-fix most lint violations.

Internally, the Gradle Lint Plugin exploits Groovy AST and Gradle Model to apply lint rules. This showcases that the plugin is tightly coupled to the Groovy AST. Because of that, the plugin doesn’t support Kotlin build scripts.

3. Setup

There are three ways to set up the Gradle Lint plugin: in the build.gradle, an initialization script, or a script plugin. Let’s explore each one of them.

3.1. Using build.gradle

Let’s add the gradle-lint plugin to our build.gradle:

plugins {
    id "nebula.lint" version "17.8.0"
}

The plugin should be applied to the root project when using a multi-module project. Since we’ll be using a multi-module project, let’s apply the plugin to the root project:

allprojects {
    apply plugin :"nebula.lint"
    gradleLint {
        rules = [] // we'll add rules here
    }
}

Later on, we’ll add lint rules inside the gradleLint.rules array.

3.2. Using Init Scripts

Apart from build.gradle, we can use init scripts to configure our plugin:

import com.netflix.nebula.lint.plugin.GradleLintPlugin

initscript {
    repositories { mavenCentral() }
    dependencies {
        classpath 'com.netflix.nebula:gradle-lint-plugin:17.8.0'
    }
}

allprojects {
    apply plugin: GradleLintPlugin
    gradleLint {
        rules=[]
    }
}

This lint.gradle script is identical to our setup earlier. To apply it, we’ll pass the –init-script flag to our tasks:

./gradlew build --init-script lint.gradle

An interesting use case is to pass a different init script depending on the environment where the tasks are running. A downside is that we’ll always have to pass the –init-script flag.

3.3. Using Script Plugins

Let’s apply a script plugin directly to our build.gradle:

plugins{
    id "nebula.lint" version "17.8.0"
}
apply from: "gradle-lint-intro.gradle"

The gradle-lint-intro.gradle content will be injected as if it were part of the build script:

allprojects {
    apply plugin: "nebula.lint"
    gradleLint {
        rules= []
    }
}

In this article, we’ll keep our gradle-lint configuration in the build.gradle script.

4. Configuration

Let’s review the different configuration options available in the grade-lint plugin.

4.1. Execution

The command to execute the Gradle Lint plugin is ./gradlew lintGradle. We can call it in isolation or during another task.

By default, the plugin automatically runs at the end of all tasks except these – help, tasks, dependencies, dependencyInsight, components, model, projects, wrapper, and properties:

./gradlew build

This build task ends by calling ./gradlew lintGradle. The linter shows violations as warnings.

Besides, we can prevent the linter from running in a specific task by applying the skipForTask method:

gradleLint {
    skipForTask('build')
}

Here, we prevent the plugin from running during the build task.

In case we want to disable the plugin for all tasks, we can use the alwaysRun flag:

gradleLint {
    alwaysRun = false
}

This is particularly useful when we want to separately call ./gradlew lintGradle at a specific point in time.

It’s important to note that calling the plugin in isolation marks the lint violations as errors, not warnings. 

4.2. Rules Definition

Gradle Lint plugin allows us to configure two groups of rules: violation rules (via rules and critcalRules options) and ignored rules (using excludedRules, ignore, and fixme properties). Let’s explore them.

First, the rules property takes an array of lint rules. When violations defined by the rules are met, the linter raises warnings. But if the Gradle Lint Plugin is running in isolation, those warnings make the build fail.

Next, let’s explore the criticalRules option. We add a rule to the gradleLint.criticalRules property when we want the rule violation to trigger a task failure. The plugin offers a specific criticalLintGradle task to only lint critical rules:

./gradlew criticalLintGradle -PgradleLint.criticalRules=undeclared-dependency

Here, the -PgradleLint.criticalRules option adds the undeclared-dependency rule to criticalRules. Then, the criticalLintGradle task only lints rules defined in criticalRules.

Continuing, the excludedRules option takes a list of rules to ignore. It comes in handy when we want to ignore a specific rule from a group rule:

gradleLint { 
    rules= ['all-dependency']
    excludedRules= ['undeclared-dependency']
 }

We’ve excluded the undeclared-dependency rule from our previous all-dependency group rule. A group rule allows us to apply a set of rules at once.

Finally, we can prevent the linter from scanning parts of our build files by wrapping them in the ignore property:

dependencies {
    testImplementation('junit:junit:4.13.1')
    gradleLint.ignore('dependency-parentheses') {
        implementation("software.amazon.awssdk:sts")
    }
}

We’ve intentionally guarded aws-sts against the dependency-parenthesis rule. It won’t be listed when we run the linter:

warning   dependency-parentheses             parentheses are unnecessary for dependencies
gradle-lint-intro/build.gradle:11
testImplementation('junit:junit:4.13.1')

The dependency-parentheses warns against the unnecessary use of parentheses in the Gradle dependencies declaration.

Besides, we can swap the ignore for the fixme property if we want to temporarily ignore a rule:

gradleLint.fixme('2029-04-23', 'dependency-parentheses') {
    implementation('software.amazon.awssdk:sts')
}

Here, the aws-sts dependency will trigger an unused-dependency violation after April, the 23rd 2029.

It’s important to note that the ignore and fixme properties are only effective on resolved dependencies. They don’t work on wrapped declarations in a build file:

dependencies {
    gradleLint.ignore('unused-dependency') {
        implementation "software.amazon.awssdk:sts"
    }
}

We’ve intentionally guarded aws-sts against the unused dependency rule. We don’t use it directly in our code. But for some reason, it’s required by AWS WebIdentityTokenCredentialsProvider. Unfortunately, the linter won’t catch that because it doesn’t evaluate unresolved dependencies.

4.3. Overriding Configuration Properties

Gradle Lint allows us to override some configuration properties in the command line. We do this by using the -PgradleLint option followed by any valid file configuration option.

Let’s add the unused-dependency rule to our initial empty rules array:

gradleLint { 
    rules= ['unused-dependency'] 
}

Next, let’s prevent the linter from applying it by excluding it via the command line:

./gradlew lintGradle -PgradleLint.excludedRules=unused-dependency

This is the equivalent of setting excludedRules=[“unused-dependency”] in the configuration file.

We can use this pattern for all the other properties, especially when running in CI environments. Multiple values should be comma-separated.

5. Built-in Rules

The Gradle Lint plugin has several built-in lint rules. Let’s explore some of them.

5.1. Minimum Dependency Version Rule

First, let’s see the minimum-dependency-version rule. It shows violations for dependencies that have a strictly lower version than a predefined one:

gradleLint { 
    rules= ['minimum-dependency-version'] 
}

We’ll need to provide the comma-separated list of minimum dependency versions in the minVersions property. But, as of this writing, the GradleLintExtension doesn’t have the minVersions property. Therefore, let’s set it via the command line:

./gradlew lintGradle -PgradleLint.minVersions=junit:junit:5.0.0

Here, the linter warns against the use of junit versions lower than 5.0.0:

> Task :lintGradle FAILED

This project contains lint violations. A complete listing of the violations follows.
Because none were serious, the build's overall status was unaffected.

warning   minimum-dependency-version         junit:junit is below the minimum version of 5.0.0 (no auto-fix available). See https://github.com/nebula-plugins/gradle-lint-plugin/wiki/Minimum-Dependency-Version-Rule for more details

? 1 problem (0 errors, 1 warning)

To apply fixes automatically, run fixGradleLint, review, and commit the changes.

Running ./gradlew fixGradleLint effectively updates junit versions to 5.0.0.

5.2. Undeclared Dependency Rule

Next, we’ll learn about the undeclared-dependency rule. It ensures we have explicitly declared transitive dependencies that we directly use in our code:

gradleLint { 
    rules= ['undeclared-dependency'] 
}

Now, let’s execute the lintGradle task:

> Task :lintGradle FAILED

This project contains lint violations. A complete listing of the violations follows. 
Because none were serious, the build's overall status was unaffected.

warning   undeclared-dependency              one or more classes in org.hamcrest:hamcrest-core:1.3 are required by your code directly

warning   undeclared-dependency              one or more classes in org.apache.httpcomponents:httpcore:4.4.13 are required by your code directly

? 2 problems (0 errors, 2 warnings)

To apply fixes automatically, run fixGradleLint, review, and commit the changes.

We can see that we have two dependencies directly required by our code. The linter adds them after we run the fixlintGradle task:

> Task :fixLintGradle

This project contains lint violations. A complete listing of my attempt to fix them follows. Please review and commit the changes.

fixed          undeclared-dependency              one or more classes in org.hamcrest:hamcrest-core:1.3 are required by your code directly

fixed          undeclared-dependency              one or more classes in org.apache.httpcomponents:httpcore:4.4.13 are required by your code directly

Corrected 2 lint problems

Besides, as of this writing, it’s impossible to feed custom rules to the plugin. An alternative could be to fork the library and add custom rules directly.

Finally, we should be careful when using outdated rules. The archaic-wrapper rule was removed in 2018. Some sections of the documentation are yet to be updated.

6. Generating Reports

Now, let’s generate reports using the generateGradleLintReport task:

./gradlew generateGradleLintReport

By default, the report format is HTML. The plugin places all report files in the build/reports/gradleLint folder. Our HTML report will be named gradle-5.html, where gradle-5 is our root project name.

The other available options are xml and text:

gradleLint {
    reportFormat = 'text'
    reportOnlyFixableViolations = true
}

We’ve used the reportFormat property to directly output the report in plain text. Additionally, our report only contains fixable violations thanks to the activated reportOnlyFixableViolations flag.

7. Conclusion

In this article, we explored the gradle-lint plugin. First, we saw its utility. Then, we listed the different configuration options. Next, we used some predefined rules. Finally, we generated lint reports.