{"id":48792709,"url":"https://github.com/typetools/checker-framework-gradle-plugin","last_synced_at":"2026-04-13T21:08:05.899Z","repository":{"id":328038245,"uuid":"1114041767","full_name":"typetools/checker-framework-gradle-plugin","owner":"typetools","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-23T18:13:22.000Z","size":140,"stargazers_count":1,"open_issues_count":5,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T16:28:20.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T20:19:34.000Z","updated_at":"2026-03-23T18:13:25.000Z","dependencies_parsed_at":"2025-12-11T10:04:53.780Z","dependency_job_id":null,"html_url":"https://github.com/typetools/checker-framework-gradle-plugin","commit_stats":null,"previous_names":["smillst/checker-framework-gradle-plugin","typetools/checker-framework-gradle-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/typetools/checker-framework-gradle-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typetools%2Fchecker-framework-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typetools%2Fchecker-framework-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typetools%2Fchecker-framework-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typetools%2Fchecker-framework-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typetools","download_url":"https://codeload.github.com/typetools/checker-framework-gradle-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typetools%2Fchecker-framework-gradle-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770875,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-13T21:08:05.182Z","updated_at":"2026-04-13T21:08:05.889Z","avatar_url":"https://github.com/typetools.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Checker Framework Gradle Plugin\n\nThis plugin configures `JavaCompile` tasks to use the [Checker\nFramework](https://checkerframework.org) for pluggable type-checking.\n\n## Apply the plugin\n\nAdd the following to your `build.gradle` file:\n\n```groovy\nplugins {\n  // Checker Framework pluggable type-checking\n  id(\"org.checkerframework\").version(\"1.0.2\")\n}\n```\n\nIf you are upgrading from plugin version 0.x to 1.x, see the [migration\nguide](#migrating-from-0x-to-1x).\n\nThe plugin supports Gradle versions 7.3 and above, which requires Java 17 and\nabove.  Although you must compile your project using at least Java 17, the\ncompiled classfiles can be compatible with, and can run on, any version of Java.\n\n## Configuration\n\n### The Checker Framework version\n\nYou must specify which\n[version](https://github.com/typetools/checker-framework/releases) of the\nChecker Framework to use.\n\n* The Gradle developers recommend to modify two files.  Add this to `build.gradle`:\n\n  ```groovy\n  checkerFramework {\n    version = libs.checker.framework.get().version\n  }\n  ```\n\n  and add this to `gradle/libs.versions.toml`:\n\n  ```toml\n  [libraries]\n  checker-framework = \"org.checkerframework:checker:3.53.1\"\n  ```\n\n* Alternately, you can edit just one file.  Add this to `build.gradle`:\n\n  ```groovy\n  checkerFramework {\n    version = \"3.53.1\"\n  }\n  ```\n\nThe special value **\"local\"** means to use a locally-built version of the\nChecker Framework, found at environment variable `$CHECKERFRAMEWORK`.\n\nThe command-line argument **`-PcfVersion=...`** (where \"...\" is a version number\nor \"local\") overrides settings in gradle buildfiles.\n\n#### Checker Framework jar files\n\nAlternately, you can directly specify which checker and checker-qual jars to\nuse. You must also set the Checker Framework version to the special value\n**`\"dependencies\"`**.  Put the following in your `build.gradle` file:\n\n```groovy\ncheckerFramework {\n  version = \"dependencies\"\n}\n\next {\n    versions = [\n        eisopVersion: \"3.42.0-eisop1\",\n    ]\n}\n\ndependencies {\n    checkerQual(\"io.github.eisop:checker-qual:${versions.eisopVersion}\")\n    checkerFramework(\"io.github.eisop:checker:${versions.eisopVersion}\")\n}\n```\n\n### Which checkers to run\n\nYou must specify which checkers to run using `checkerFramework.checkers` property.\n\nFor example, using Groovy syntax in a `build.gradle` file:\n\n```groovy\ncheckerFramework {\n  checkers = [\n    \"org.checkerframework.checker.nullness.NullnessChecker\",\n    \"org.checkerframework.checker.units.UnitsChecker\"\n  ]\n}\n```\n\nThe same example, using Kotlin syntax in a `build.gradle.kts` file:\n\n```kotlin\n// In Kotlin, you need to import CheckerFrameworkExtension explicitly:\nimport org.checkerframework.plugin.gradle.CheckerFrameworkExtension\n\nconfigure\u003cCheckerFrameworkExtension\u003e {\n    checkers = listOf(\n        \"org.checkerframework.checker.nullness.NullnessChecker\",\n        \"org.checkerframework.checker.units.UnitsChecker\"\n    )\n}\n```\n\nFor a list of checkers, see the [Checker Framework Manual](https://checkerframework.org/manual/#introduction).\n\n#### Checker dependencies\n\nIf a checker you are running has any dependencies, use a `checkerFramework` dependency:\n\n```groovy\ndependencies {\n    checkerFramework(\"...\")\n}\n```\n\nFor example, if you are using the\n[Subtyping Checker](https://checkerframework.org/manual/#subtyping-checker) with\ncustom type qualifiers, you should add a `checkerFramework` dependency referring\nto the definitions of the custom qualifiers.\n\n### Providing additional options to the compiler\n\nYou can set the `checkerFramework.extraJavacArgs` property to pass\nadditional options to the compiler when running a pluggable type-checker.\n\nFor example, to treat all warnings as errors and to use a stub file:\n\n```groovy\ncheckerFramework {\n  extraJavacArgs = [\n    \"-Werror\",\n    \"-Astubs=/path/to/my/stub/file.astub\"\n  ]\n}\n```\n\n## Disabling the Checker Framework\n\nYou can completely disable the Checker Framework (e.g., when testing something\nunrelated) either in your build file or from the command line.\n\nIn your build file:\n\n```groovy\ncheckerFramework {\n  skipCheckerFramework = true\n}\n```\n\nFrom the command line, add `-PskipCheckerFramework` to your gradle invocation. You can also pass \n`-PskipCheckerFramework=false` to enable the Checker Framework even if the configuration has \n`skipCheckerFramework = true`.\n\n### Disabling the Checker Framework for tests\n\nBy default, the plugin applies the selected checkers to all `JavaCompile` targets,\nincluding test targets such as `testCompileJava`.\n\nHere is how to prevent checkers from being applied to test targets:\n\n```groovy\ncheckerFramework {\n  excludeTests = true\n}\n```\n\nA \"test target\" is one that contains \"test\" or \"Test\" as a word.\nWords are determined using camelCase; underscores (`_`) also delimit words.\n\n### Disabling the Checker Framework for a specific compile task\n\nYou can disable the Checker Framework for specific tasks.\nThis can be useful for skipping the Checker Framework on generated code:\n\n```groovy\ntasks.withType(JavaCompile).configureEach {\n  // Don't run the checker on generated code.\n  if (name.equals(\"compileMainGeneratedDataTemplateJava\")\n      || name.equals(\"compileMainGeneratedRestJava\")) {\n    options.checkerFrameworkCompile.enabled = false\n  }\n}\n```\n\nThe only configuration available on a per-task basis is `enabled`.\n\n## Multi-project builds\n\nIn a project with subprojects, you should apply the plugin to each Java\nsubproject (and to the top-level project, in the unlikely case that it is a Java\nproject).  Here are two approaches.\n\n### Approach 1\n\nAll Checker Framework configuration (the `checkerFramework` block and any\n`dependencies`) remains in the top-level `build.gradle` file.  Put it in a\n`subprojects` block (or an `allprojects` block in the unlikely case that the\ntop-level project is a Java project).  For example, in Groovy syntax:\n\n```groovy\nplugins {\n  id(\"org.checkerframework\").version(\"1.0.0\")\n}\n\nsubprojects { subproject -\u003e\n  apply plugin: \"org.checkerframework\"\n\n  checkerFramework {\n    checkers = [\"org.checkerframework.checker.index.IndexChecker\"]\n    version = \"3.53.0\"\n  }\n}\n```\n\n### Approach 2\n\nApply the plugin in the `build.gradle` in each subproject as if it\nwere a stand-alone project. You must do this if you require different configuration\nfor different subprojects (for instance, if you want to run different checkers).\n\n## Modules\n\nThe Checker Framework inserts inferred annotations into bytecode even if none\nappear in source code, so you must make them known to the compiler even if you\nwrite no annotations in your code.  When running the plugin on a Java project\nthat uses modules, you need to add annotations to the module path.\n\nAdd following to your `module-info.java`:\n\n```java\nrequires org.checkerframework.checker.qual;\n```\n\nThe addition of `requires` is typically enough.\n\nIf it does not fix your compilation issues, you can additionally add the `checker-qual.jar`\nartifact (which only contains annotations) to the module path:\n\n```groovy\ncheckerFramework {\n  configurations.compileOnly.setCanBeResolved(true)\n  extraJavacArgs = [\n    \"--module-path\", configurations.checkerQual.asPath\n  ]\n}\n```\n\n## Lombok compatibility\n\nThis plugin automatically interacts with\nthe [Lombok Gradle Plugin](https://plugins.gradle.org/plugin/io.freefair.lombok)\nto delombok your source code before it is passed to the Checker Framework\nfor type-checking. This plugin does not support any other use of Lombok.\n\nFor the Checker Framework to work properly on delombok'd source code,\nyou must include the following key in your project's `lombok.config` file:\n\n```config\nlombok.addLombokGeneratedAnnotation = true\n```\n\nBy default, Lombok suppresses all warnings in the code it generates. If you\nwant to typecheck the code that Lombok generates, set the `addSuppressWarnings`\nto false:\n\n```config\nlombok.addSuppressWarnings = false\n```\n\nNote that doing so will cause *all* tools (including Javac itself) to begin issuing\nwarnings in the code that Lombok generates.\n\n## Using a locally-built plugin\n\nTo use a locally-modified version of this plugin:\n\n1. Publish the plugin to your local Maven repository:\n\n   ```sh\n   ./gradlew publishToMavenLocal\n   ```\n\n2. Add the following to the `settings.gradle` file in\n   the Gradle project that you want to use the plugin:\n\n   ```groovy\n   pluginManagement {\n       repositories {\n           mavenLocal()\n           gradlePluginPortal()\n       }\n   }\n   ```\n\n## Migrating from 0.x to 1.x\n\nIf your project uses version 0.x of the Checker Framework Gradle Plugin,\nyou need to make some changes in order to use version 1.x.\n\n1. You must specify [a version number](#the-checker-framework-version).\n\n2. You no longer need to add a `checkerFramework` dependency or add\n   `checker-qual` to the `compileOnly` or `testCompileOnly` configurations.\n   Remove code like the following:\n\n   ```groovy\n   dependencies {\n     compileOnly(\"org.checkerframework:checker-qual:${checkerFrameworkVersion}\")\n     testCompileOnly(\"org.checkerframework:checker-qual:${checkerFrameworkVersion}\")\n     checkerFramework(\"org.checkerframework:checker:${checkerFrameworkVersion}\")\n   }\n   ```\n\n3. These options have been removed:\n   * **`suppressLombokWarnings`**: Use [Lombok options](#lombok-compatibility)\n     to configure interaction with Lombok.\n\n   * **`skipVersionCheck`**: There is no longer a version check that might cause\n     \"zip file too large\" error.  Remove the `-PskipVersionCheck` command-line\n     argument and remove Gradle code like\n\n     ```groovy\n     checkerFramework {\n       skipVersionCheck = true\n     }\n     ```\n\n   * **`cfLocal`**: Set the version to `\"local\"` to use a locally-built version\n     of the Checker Framework.  Change command-line argument `-PcfLocal` to\n     `-PcfVersion=local`.  (Note: The `cfLocal` functionality was not an\n     official part of the plugin, but a number of projects use it.)\n\n4. If you want to use a non-standard Checker Framework jar file (such as that of\n    eisop) see [Checker Framework jar files](#checker-framework-jar-files).\n\n## Troubleshooting\n\n### ClassCastException for a javac class\n\nIf you encounter a crash with a `ClassCastException` referencing some internal\nJavac class, disable incremental compilation in your build using the following\ncode in your `checkerFramework` configuration block:\n\n```groovy\n  checkerFramework {\n    incrementalize = false\n  }\n```\n\nBackground:  By default, the plugin assumes that all checkers are [\"isolating\nincremental annotation\nprocessors\"](https://docs.gradle.org/current/userguide/java_plugin.html#sec:incremental_annotation_processing).\nThis assumption speeds up builds by enabling incremental compilation.  Gradle's\ndocumentation warns that incremental compilation with the Checker Framework\nplugin (or any other plugin that uses internal Javac APIs) may crash, because\nGradle wraps some of those APIs.\n\n### Incompatibility with Error Prone 2.3.4 and earlier\n\nTo use both [Error Prone](https://errorprone.info/) and the Checker Framework,\nyou need to use Error Prone version 2.4.0 (released in May 2020) or later.\n\n\u003c!--\nLocalWords:  JavaCompile gradle checkerframework checkerFramework toml lombok\nLocalWords:  PcfVersion buildfiles qual eisopVersion eisop1 checkerQual config\nLocalWords:  kotlin CheckerFrameworkExtension listOf extraJavacArgs Multi eisop\nLocalWords:  Werror Astubs testCompileJava excludeTests camelCase classfiles\nLocalWords:  withType configureEach compileMainGeneratedDataTemplateJava\nLocalWords:  compileMainGeneratedRestJava subprojects allprojects mavenLocal\nLocalWords:  delombok addLombokGeneratedAnnotation addSuppressWarnings cfLocal\nLocalWords:  publishToMavenLocal pluginManagement gradlePluginPortal\nLocalWords:  compileOnly testCompileOnly checkerFrameworkVersion PcfLocal\nLocalWords:  skipCheckerFramework PskipCheckerFramework skipVersionCheck\nLocalWords:  suppressLombokWarnings PskipVersionCheck\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypetools%2Fchecker-framework-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypetools%2Fchecker-framework-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypetools%2Fchecker-framework-gradle-plugin/lists"}