mozilla-mobile / gradle-apilint

Gradle Plugin that tracks the API of an Android library and helps maintain backward compatibility.

API Lint Gradle Plugin

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

Tasks

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.

Usage

build.gradle

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).

Dependencies

The apilint plugin adds the following dependencies.

Task Name	Depends on
check	apiLintVariantName

Changelog

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:

build.gradle

apiLint.changelogFileName = 'CHANGELOG.md'

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

CHANGELOG.md

[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.

Configuration

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

build.gradle

apiLint {
    packageFilter = '.'
    apiOutputFileName = 'api.txt'
    currentApiRelativeFilePath = 'api.txt'
    jsonResultFileName = 'apilint-result.json'
    skipClassesRegex = []
    changelogFileName = null
    lintFilters = null
    allowedPackages = null
    deprecationAnnotation = null
    libraryVersion = 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, ...

allowedPackages List of packages that are allowed in the API. If this list is set, apilint will check that every type mentioned in the API belongs to any of the packages listed. Adding a package implicitly allows all sub-packages too, so allowing package a.b will allow a.b.c too.

deprecationAnnotation Additional annotation that should be present when a method is marked with @Deprecated. This annotation is expected to have a String id and a int version parameter, like so:

public @interface DeprecationSchedule {
    String id();
    int version();
}

where version indicates when the deprecated method is expected to be removed.

libraryVersion Integer that represents the current library version, used by deprecationAnnotation to determine if a deprecated member should be removed.

License

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/