Skip to content
Gradle Plugin that tracks the API of an Android library and helps maintain backward compatibility.
Branch: master
Clone or download
Latest commit 3b284aa Apr 2, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
apidoc-plugin Add import support. Apr 4, 2019
apilint Add import support. Apr 4, 2019
buildSrc Use |master-SNAPSHOT| for the tip of master's version. Dec 18, 2018
gradle/wrapper Initial import. Nov 2, 2018
.arcconfig Create gradle plugin apilint. r=snorp,nalexander Nov 5, 2018
.gitignore Remove *.pyc files commited by mistake. Apr 2, 2019
.travis.yml
CODE_OF_CONDUCT.md Add Mozilla Code of Conduct file Apr 1, 2019
LICENSE Create gradle plugin apilint. r=snorp,nalexander Nov 5, 2018
README.md
build.gradle Create gradle plugin apilint. r=snorp,nalexander Nov 5, 2018
gradlew Create gradle plugin apilint. r=snorp,nalexander Nov 5, 2018
gradlew.bat Initial import. Nov 2, 2018
settings.gradle Closes #6: Rename apidoc -> apidoc-plugin Nov 9, 2018

README.md

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
}

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.

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/
You can’t perform that action at this time.