Checker Framework logo

Checker Framework Eclipse Plugin: Pluggable type-checking for Java

Warning: The Checker Framework Eclipse Plugin is no longer supported and is out of date. Follow the Eclipse instructions in the Checker Framework manual.

Introduction

The Checker Framework is a pluggable type-checking system for Java: It warns you, at compile time, about errors in your programs, beyond those that Java's built-in type-checker does. This document tells you how to get started using the Checker Framework in Eclipse. However, the Checker Framework Eclipse Plugin is no longer supported and is out of date. Therefore, you are highly recommended to follow the Eclipse instructions in the Checker Framework manual.

Installation

Requirements

This plugin has been tested on Oxygen.1a Release (4.7.2) using Java 8. Older versions running on a Java 8 VM can be used with the plugin. However, the Checker Framework Eclipse Plugin is no longer supported and is out of date. Therefore, you are highly recommended to follow the Eclipse instructions in the Checker Framework manual.

Instructions

  1. Open Eclipse and select from menus: Help ‑> Install New Software...
  2. Click Add.
  3. Enter the following:
    Name: Checker Framework
    Location: https://checkerframework.org/eclipse
    Click OK.
  4. Appearing under name should be "Pluggable Type-Checking", check the box next to it.
  5. Click Next.
  6. A summary of the plugins to be installed will be displayed. Under Name should appear "Checker Framework Feature" followed by the version of the plugin being installed. Click Next again.
  7. Accept the license agreement and click Finish.
  8. The plugin will begin installing. The plugin is NOT digitally signed. Install it anyway.
  9. Click "Restart Now".
Note: You may want to add checker-qual.jar to your classpath for each Eclipse project you wish to check. It provides the annotations used by the Checker Framework for its built-in type checkers.
To add the checker-qual.jar to your Eclipse project, download the jar from the above link. Then right click the project you wish to check and select Properties -> Java Build Path -> Libraries -> Add External Jars. Select checker-qual.jar from the directory in which it's saved.

Using the Plugin

Running a Built-In Checker

Here is how to run one or more built-in type checkers from the Checker Framework:

  1. Right-click a project, package, or source file.
  2. Open the "Checker Framework" sub-menu.
  3. Open the "Run Built-In Checker" sub-menu.
  4. Select the checker you would like top run (e.g. NullnessChecker).
Select the Nullness Checker

A progress dialog will inform you as the plugin performs these steps: removing old markers, running the type-checker(s), and updating the problem list and markers.
You can select the "Problems" window to see all the type-checking errors.
In the editor, a warning marker will appears to the left of each line that has a type-checking error. You can hover over the warning marker to view the given error. The errors are also output to the console formatted as they appear when running the Checker Framework from the command line, but most users do not view the console.

You may clear all Checker Framework error markers by right-clicking on the project and selecting: (Checker Framework ‑> Clear Checker Markers).

Warning! When using the Subtyping Checker, you must provide the -Aquals argument or an error will be reported. Follow the instructions in the Additional Compiler Params section to add the -Aquals argument.

Running a Custom Checker

The Checker Framework also allows you to write a custom checker that enforces rules of your own.
To run a custom checker that you have written, do the following:

  1. Open the Eclipse Preferences page (usually Window‑>Preferences or Eclipse‑>Preferences depending on your platform).
  2. Select the "Checker Framework" preferences page.
  3. In the "Checkers" section there will be a table of built-in checkers. Press the "Add" button located below the table.
  4. A dialog should pop up. In the text field at the top of the dialog, type the class name of your checker without the package name (e.g., NullnessChecker, NOT org.checkerframework.checker.nullness.NullnessChecker)
  5. One or more classes should appear in a list below the text-field. Select your checker.
  6. Press "OK".
  7. The dialog will close and your custom checker should now appear in the "Checkers" table. Press "OK" again.
Checkers preferences table

Your custom checker will now appear in the menu "Run Custom Checker" when you right-click a project, package, or file and open the "Checker Framework" sub-menu. You can run your custom checker in a manner similar to that described in "Running Built-In Checkers".

Running Multiple Checkers

If you wish to run several checkers at once follow the instructions below:

  1. Open the Eclipse Preferences page (usually Window‑>Preferences or Eclipse‑>Preferences depending on your platform).
  2. Select the "Checker Framework" preferences page.
  3. In the "Checkers" section there will be a table of built-in checkers. Place a check-mark next to each of the checkers (built-in or custom) you would like to run.
  4. Press "OK".
  5. Right-click on the project, package, or file you would like to check.
  6. Open the "Checker Framework" sub-menu and select "Run Selected Checkers"
Selected checkers

Other Preferences

Previous sections discussed running a custom checker and running multiple checkers. This section covers the other options found on the plugin's preferences page.

Opening the Preferences Page
To open the preferences page for the Eclipse plugin you must first open Eclipse's preferences (usually Window‑>Preferences or Eclipse‑>Preferences depending on your platform). Then select "Checker Framework" from the list of preferences.

Filtering error messages
You can provide a regular expression under "Regex for warning/error filter" to filter error messages. Any error messages that match the given regular expression will not be output in the problem view and will not show any error markers.

Using a specific version of Java
The Eclipse plugin will start a new Java process in order to run the Checker Framework compiler. You may select which version of Java will run the Checker Framework via the text-field labeled "Java Home Directory" or press the "Browse" button to select Java home via a dialog. Otherwise, the version used to run Eclipse will also be used to run the Checker Framework compiler.

Processor/build options
The Checker Framework supports command-line options to its compiler (usually prefaced by -A). One way to use these options is enabling the various options under the label "Processor/build options". If you are using the Checker Framework on a project for which other developers are not, you may be specifically interested in its backward compatibility features, such as annotations in comments and implicit import statement. If you check the box next to the text "Use implicit imports for annotation classes" then, for built-in checkers, all of the appropriate annotations will be imported implicitly.

Other preferences

Additional compiler parameters
The Checker Framework compiler has many options, including all of the standard javac options. You may wish to pass a javac option to the Checker Framework compiler or a Checker Framework option not explicitly listed in the "Processor/Build Options" section. To add custom options, press the "Add" button found in the "Additional compiler parameters" section. In the provided text box, add one or more options as they would appear on your command line. Each option, or group of options, added in this manner will appear on a line in the options table above the "Add" button. The options provided by a line in this table may be activated and deactivated via the check box to the left of its definition. Any line that has a checkmark to its left will be added to the command line when the Checker Framework is run.

Warning! The text found in the "Additional compiler parameters" text-field will first be split on white space and then added (without further manipulation) to the command line that runs the Checker Framework compiler. Please make sure any options added here are well-formed javac options or Checker Framework options. If they are malformed you can check the "Errors" window for any error messages or exceptions thrown by the compiler/plugin.

Troubleshooting and Support

To get support for either the Checker Framework or this plugin please first consult the Checker Framework Manual, specifically the chapter "Troubleshooting and getting help" . If you find a bug, please report it at https://github.com/typetools/checker-framework/issues (first, check whether there is an existing bug report for that issue). You can also get help via the discussion group checker-framework-discuss.

Source Code

To install and use the Checker Plugin, you do not need to access or compile the source code. However, if you would like to read or modify the source code, it is publicly available. The code for the Eclipse plugin can be found within the Checker Framework version control repository (https://github.com/typetools/checker-framework/ in the checker-framework/eclipse directory. To obtain your own copy of the source code, execute the following command:

git clone https://github.com/typetools/checker-framework.git