Skip to main content

Configuration

The Gradle plugin, the apiWatchdog extension, and the compiler options of library-api-watchdog.

Apply the Gradle plugin​

The plugin and the annotations library are in the Space EAP repository. The Gradle plugin also depends on the runtime libraries of the compiler plugin dev kit. They are in the dev kit EAP repository. Add both repositories to the plugin and dependency repositories:

settings.gradle.kts
pluginManagement {
repositories {
maven("https://packages.jetbrains.team/maven/p/kt-lib/eap")
maven("https://packages.jetbrains.team/maven/p/compiler-plugin-dev-kit/eap")
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositories {
maven("https://packages.jetbrains.team/maven/p/kt-lib/eap")
maven("https://packages.jetbrains.team/maven/p/compiler-plugin-dev-kit/eap")
mavenCentral()
}
}

A convention plugin build (buildSrc or an included build) that depends on the Gradle plugin needs both repositories in its own settings.

Apply the plugin:

build.gradle.kts
plugins {
kotlin("library.api-watchdog") version "0.2.0"
}

The checks run only in a module with explicit API mode on. Turn it on:

build.gradle.kts
kotlin {
explicitApi()
}

explicitApiWarning() and the -Xexplicit-api compiler flag also count. Without explicit API mode the plugin doesn't register any checks. explicitApi() reaches the main compilations, the metadata compilations, and the Android variants. A custom compilation such as testFixtures doesn't have checks without the -Xexplicit-api flag.

What applying does​

Applying the plugin:

  • Registers the compiler plugin for every compilation except test compilations.
  • Adds the org.jetbrains.kotlinx:kotlin-library-api-watchdog-plugin-annotations dependency, the library with the @Intentionally* exemption annotations.
  • Warns when explicit API mode is off.
  • Warns when binary compatibility validation is off, with a setup snippet. Binary compatibility validation suggestion gives the details.

The apiWatchdog extension​

The sample lists every property. A severity or a switch shows its default value:

build.gradle.kts
apiWatchdog {
enabled = true
internalApiAnnotations.add("com.example.dependency.InternalDependencyApi")
ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS, whenAnnotatedWith = listOf("com.example.GeneratedValueMembers"))
html = true
htmlFile = layout.buildDirectory.file("reports/api-watchdog/report.html")
sarif = true
sarifFile = layout.buildDirectory.file("reports/api-watchdog/report.sarif")
}
openApiWithoutSubclassOptIn = WatchdogSeverity.ERROR
subclassOptInWithoutMarkers = WatchdogSeverity.ERROR
exhaustivePublicApi = WatchdogSeverity.ERROR
undocumentedPublicApi = WatchdogSeverity.WARNING
functionTypeAliasPublicApi = WatchdogSeverity.ERROR
dataClassPublicApi = WatchdogSeverity.ERROR
statefulClassWithoutEquals = WatchdogSeverity.ERROR
statefulClassWithoutHashCode = WatchdogSeverity.ERROR
statefulClassWithoutToString = WatchdogSeverity.ERROR
mutableCollectionPublicApi = WatchdogSeverity.ERROR
pairOrTriplePublicApi = WatchdogSeverity.ERROR
booleanParameterPublicApi = WatchdogSeverity.ERROR
nullableBooleanPublicApi = WatchdogSeverity.ERROR
requiredParameterAfterOptional = WatchdogSeverity.ERROR
inconsistentParameterOrderInOverloads = WatchdogSeverity.ERROR
inlineFunctionWithLogic = WatchdogSeverity.ERROR
dslMarkerNoopTarget = WatchdogSeverity.ERROR
dslMarkerWithoutExplicitTargets = WatchdogSeverity.ERROR
dslMarkerNoopTypePosition = WatchdogSeverity.ERROR
enabled = true
mangledJvmNamePublicApi = WatchdogSeverity.ERROR
kotlinOnlyApiWithoutJvmSynthetic = WatchdogSeverity.ERROR
companionApiWithoutJvmStatic = WatchdogSeverity.ERROR
companionPropertyWithoutStaticAccess = WatchdogSeverity.ERROR
topLevelApiWithoutJvmName = WatchdogSeverity.ERROR
defaultParametersWithoutJvmOverloads = WatchdogSeverity.ERROR
}
}

Disabling the watchdog​

enabled = false turns off every check in the project. The plugin still adds the annotations library:

build.gradle.kts
apiWatchdog {
enabled = false
}

Annotation ignore rules​

ignore skips a check on every declaration that carries one of the listed annotations:

build.gradle.kts
import org.jetbrains.kotlinx.library.api.watchdog.WatchdogChecks
apiWatchdog {
ignore(
WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS,
whenAnnotatedWith = listOf(
"com.example.GeneratedValueMembers",
"com.example.GeneratedEntityMembers",
),
)
}

Both arguments take one value or a list:

build.gradle.kts
apiWatchdog {
ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS, whenAnnotatedWith = "com.example.GeneratedValueMembers")
ignore(
listOf(WatchdogChecks.STATEFUL_CLASS_WITHOUT_HASH_CODE, WatchdogChecks.STATEFUL_CLASS_WITHOUT_TO_STRING),
whenAnnotatedWith = "com.example.GeneratedValueMembers",
)
}

ignore doesn't work for always-error checks. See Exemptions and internal API for more details about when to use a rule.

Internal API annotations​

internalApiAnnotations lists annotation classes by their fully qualified names. A listed annotation counts as an internal API annotation:

build.gradle.kts
apiWatchdog {
internalApiAnnotations.add("com.example.dependency.InternalDependencyApi")
}

See Internal API annotations for more details.

Exempt non-transitive dependencies​

A dependency declared on the apiWatchdogExemptNonTransitive configuration is exempt from Public types from non-transitive dependencies in the whole module:

build.gradle.kts
dependencies {
compileOnly(libs.kotlin.gradle.plugin)
apiWatchdogExemptNonTransitive(libs.kotlin.gradle.plugin)
}

To exempt a whole configuration, extend apiWatchdogExemptNonTransitive from it:

build.gradle.kts
configurations.apiWatchdogExemptNonTransitive {
extendsFrom(configurations.compileOnly.get())
}

See Exempting a dependency for more details.

Severities​

A severity property holds a WatchdogSeverity:

ValueEffect
ERRORFails the compilation. The default, except for undocumentedPublicApi.
WARNINGReports a compiler warning. The build succeeds. Default for undocumentedPublicApi.
NONETurns the check off.

Four checks don't have a severity property:

Property reference​

Each configurable check, its property, and its diagnostic name:

CheckPropertyDiagnostic
Boolean parameters in public APIbooleanParameterPublicApiBOOLEAN_PARAMETER_PUBLIC_API
Data classes in public APIdataClassPublicApiDATA_CLASS_PUBLIC_API
DSL markers on no-op type positionsdslMarkerNoopTypePositionDSL_MARKER_NOOP_TYPE_POSITION
DSL markers with no-op targetsdslMarkerNoopTargetDSL_MARKER_NOOP_TARGET
DSL markers without explicit targetsdslMarkerWithoutExplicitTargetsDSL_MARKER_WITHOUT_EXPLICIT_TARGETS
Exhaustive public APIexhaustivePublicApiEXHAUSTIVE_PUBLIC_API
Function type aliases in public APIfunctionTypeAliasPublicApiFUNCTION_TYPE_ALIAS_PUBLIC_API
Inconsistent parameter order in overloadsinconsistentParameterOrderInOverloadsINCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS
Inline functions with logicinlineFunctionWithLogicINLINE_FUNCTION_WITH_LOGIC
Mutable collections in public APImutableCollectionPublicApiMUTABLE_COLLECTION_PUBLIC_API
Nullable Booleans in public APInullableBooleanPublicApiNULLABLE_BOOLEAN_PUBLIC_API
Open API without subclass opt-inopenApiWithoutSubclassOptInOPEN_API_WITHOUT_SUBCLASS_OPT_IN
Pair and Triple in public APIpairOrTriplePublicApiPAIR_OR_TRIPLE_PUBLIC_API
Public types from non-transitive dependenciespublicTypesMustBeTransitiveDependenciesPUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY
Public types marked as internal APIpublicTypeWithInternalApiPUBLIC_TYPE_WITH_INTERNAL_API
Required parameters after optional onesrequiredParameterAfterOptionalREQUIRED_PARAMETER_AFTER_OPTIONAL
Stateful classes without equals, hashCode, and toStringstatefulClassWithoutEqualsSTATEFUL_CLASS_WITHOUT_EQUALS
Stateful classes without equals, hashCode, and toStringstatefulClassWithoutHashCodeSTATEFUL_CLASS_WITHOUT_HASH_CODE
Stateful classes without equals, hashCode, and toStringstatefulClassWithoutToStringSTATEFUL_CLASS_WITHOUT_TO_STRING
Subclass opt-in without markerssubclassOptInWithoutMarkersSUBCLASS_OPT_IN_WITHOUT_MARKERS
Undocumented public APIundocumentedPublicApiUNDOCUMENTED_PUBLIC_API

Java interop​

These properties are in the javaInterop { } block. The checks run only in JVM compilations. javaInterop.enabled (default true) is one switch for all six: false turns every one off, whatever its own severity.

See Java interop checks for more details.

CheckPropertyDiagnostic
Companion function without JvmStaticcompanionApiWithoutJvmStaticCOMPANION_API_WITHOUT_JVM_STATIC
Companion property without static accesscompanionPropertyWithoutStaticAccessCOMPANION_PROPERTY_WITHOUT_STATIC_ACCESS
Default parameters without JvmOverloadsdefaultParametersWithoutJvmOverloadsDEFAULT_PARAMETERS_WITHOUT_JVM_OVERLOADS
Kotlin-only API without JvmSynthetickotlinOnlyApiWithoutJvmSyntheticKOTLIN_ONLY_API_WITHOUT_JVM_SYNTHETIC
Mangled JVM names in public APImangledJvmNamePublicApiMANGLED_JVM_NAME_PUBLIC_API
Top-level API without JvmNametopLevelApiWithoutJvmNameTOP_LEVEL_API_WITHOUT_JVM_NAME

Report aggregation​

The report aggregation plugin combines the reports of the subprojects into one HTML and one SARIF file in the root project. Apply it to the root project and declare every subproject:

build.gradle.kts
plugins {
kotlin("library.api-watchdog-report-aggregation") version "0.2.0"
}
dependencies {
subprojects.forEach { apiWatchdogReports(project(it.path)) }
}
reports {
html = true
htmlFile = layout.buildDirectory.file("reports/api-watchdog/aggregate-report.html")
sarif = true
sarifFile = layout.buildDirectory.file("reports/api-watchdog/aggregate-report.sarif")
}
}

The snippet shows the defaults. See Report generation for more details about the formats, the subproject selection, and included builds.

Without Gradle​

A direct compiler call configures the plugin with -P options of this form:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:<option>=<value>
OptionValueGradle equivalent
diagnosticSeverity<NAME>:<severity>. Repeatable.The severity property.
ignoreWhenAnnotated<NAME>:<annotation class name>[:recursive]. Repeatable.ignore
internalApiAnnotation<annotation class name>. Repeatable.internalApiAnnotations
publicTypeWithInternalApitrue or false.publicTypeWithInternalApi
reportUndocumentedClassPropertiestrue or false.reportUndocumentedClassProperties

<NAME> is a diagnostic name from the Property reference, except the two checks that a Boolean property turns off: the option rejects them. <severity> is error, warning, or none. A diagnostic that no option names has its default severity. One value of each option:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=UNDOCUMENTED_PUBLIC_API:error
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:ignoreWhenAnnotated=STATEFUL_CLASS_WITHOUT_EQUALS:com.example.GeneratedValueMembers
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:internalApiAnnotation=com.example.dependency.InternalDependencyApi
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:publicTypeWithInternalApi=false
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:reportUndocumentedClassProperties=true

PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY needs the dependency model that only the Gradle plugin passes to the compiler, so it doesn't run without Gradle.

Next steps​