Tracks the API of an Android library and helps maintain backward compatibility.

The apilint plugin provies the following tasks.

apiLintVariantName Checks that the current API is backward compatible with the API specified in a file, by default located in //api.txt. This task also checks for various lints as specified in apilint.py.

apiUpdateFileVariantName Updates the API file from the local state of the project

apiChangelogCheckVariantName Only if apiLint.changelogFileName is set. Checks that the changelog file is updated every time the api.txt file changes.

buildscript {
    repositories {
        maven {
            url "https://plugins.gradle.org/m2/"
        }
    }
    dependencies {
        classpath 'org.mozilla.apilint:apilint:$apilintVersion'
    }
}

apply plugin: 'org.mozilla.apilint'
apiLint.packageFilter = 'org.your.package.api'

Make sure that the apply plugin line appears after the com.android.library plugin has been applied.

Then run

$ ./gradlew apiUpdateFileVariantName

This will create an API file that contains a description of your library's API, by default this file will be called api.txt.

After you make changes to your code, run:

$ ./gradlew apiLintVariantName

to check that the API of your library did not change. You can always run apiUpdateFileVariantName to update the API file (e.g. when adding new APIs).

The apilint plugin adds the following dependencies.

Optionally, apilint can track your API changelog file and fail the build if the changelog file has not been updated after an API change. To enable this feature, add the following:

apiLint.changelogFileName = 'CHANGELOG.md'

And then add the following line somewhere in your changelog file:

[api-version]: <api-txt-sha1>

where <api-txt-sha1> is the SHA1 of the current api file. You can obtain this value by running:

$ ./gradlew apiChangelogCheckVariantName

Now, whenever ./gradlew apiLintVariantName is invoked, it will check that the changelog file version matches the generated api file version.

The apilint plugin can be configured using the gradle extension apiLint. Default values are as follows

apiLint {
    packageFilter = '.'
    apiOutputFileName = 'api.txt'
    currentApiRelativeFilePath = 'api.txt'
    jsonResultFileName = 'apilint-result.json'
    skipClassesRegex = []
    changelogFileName = null
    lintFilters = null
}

packageFilter Filters packages that make up the api. By default all packages are included in the api.txt file.

apiOutputFileName Relative path to the api.txt file in the source folder.

currentApiRelativeFilePath Relative path of the generated api.txt file in the build folder.

jsonResultFileName Relative path to the JSON file name that contains the result of apilint.

skipClassesRegex Ignore classes which full path matches any regex contained in this array. E.g. BuildConfig$ will match any class named BuildConfig, ^org.mozilla will match any class in the package org.mozilla.

changelogFileName Relative path to the changelog file, optional. See also Changelog.

lintFilters List of lints that fail the build, by default all lints can fail the build. Filters will match any error code that starts with the string specified, e.g. GV will match GV1, GV2, ...

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/