The Checker Framework

Are you tired of null pointer exceptions, unintended side effects, SQL injections, concurrency errors, mistaken equality tests, and other run-time errors that appear during testing or in the field?

The Checker Framework enhances Java’s type system to make it more powerful and useful. This lets software developers detect and prevent errors in their Java programs. The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins.

Quick start: go directly to the Installation instructions and tutorial.

• Download: checkers.zip version 1.1.4, 8 Jul 2011 (includes source, platform-independent binary, tests, and documentation)
  Then, see the Installation instructions and tutorial.
• Documentation:
  • Checker Framework manual (PDF)
  • Checker Framework manual (HTML)
  • Installation instructions
  • Javadoc API documentation
  • Changelog
  • Practical pluggable types for Java (a paper presented at the ISSTA 2008 conference) describes the design of the Checker Framework, and case studies that found bugs in real programs and yielded new insights about type systems.
  • Building and using pluggable type-checkers (a paper presented at the ICSE 2011 conference) evaluates the ease of pluggable type-checking with the Checker Framework. The type checkers were easy to write, easy for novices to use, and effective in finding hundreds of errors in case studies of 2 million lines of code.
• Source code repository (at Google Code): http://code.google.com/p/checker-framework/
• Inference tools automatically add annotations to your code, making it even easier to start using the checkers. You must download these tools separately.
  • To infer the @Nullable type qualifier, use Daikon
  • To infer the @NonNull type qualifier, use the Julia Analyzer, Nit, or JastAdd
  • To infer the @ReadOnly type qualifier, use Javarifier
• Optional related tools:
  • The Annotation File Utilities extract annotations from, and write annotations to, .java and .class files. It also provides a representation (called an “annotation file”) for annotations that is outside the source code or the .class file. The tools support both Java 5 annotations, and the type annotations defined in JSR 308.
    • annotation-tools.zip (18 Aug 2009)
    • source code repository
    • Documentation is included in the zip archive and in the repository.
  • The Type annotations compiler is fully backward-compatible. You can use it in place of javac without any change in behavior, except that you will be permitted to place annotations in more locations (or in comments) and to use type-checking plug-ins that take advantage of those new locations. Most users don't need it, since a compiled version (without source code) is already included in the Checker Framework distribution.

Support and community

If you have a question, then first see whether your question is answered in one of the manuals listed under Documentation below. If none of those documents answers your question, then use one of the mailing lists.

Documentation

• Checker Framework manual (PDF, HTML)
• FAQ (Frequently Asked Questions with answers) for the Checker Framework

Mailing lists

The mailing lists are appropriate for discussing the Type Annotations (JSR 308) specification, any tool that processes type annotations (compiler, the Checker Framework, the Annotation File Utilities, etc.), and any other issue related to type annotations. We welcome questions, bug reports, suggestions, reports about case studies, and other contributions. Let us know how we can make type annotations even better!

• checker-framework-discuss: for general discussion about the Checker Framework for building pluggable type systems (view archives, view old archives)

You can also use the mailing lists to give help. Here are just a few examples:

• Respond to questions.
• Report problems (in the implementation or the documentation) or request features.
• Write code, then share your bug fixes, new features, compiler plug-ins, or other improvements.
• Make suggestions regarding the specification.

Another way to help is to tell your friends and colleagues about the usefulness and practicality of type annotations, or to report your successes to the mailing lists.

Bug reports

To submit a bug report, use the issue tracker:

• Checker Framework issue tracker (please read these instructions first)

Last updated: June 30, 2011