Checker Plugin for Eclipse

What it is:

The Checker Plugin is an Eclipse plugin that will help you use pluggable type-checkers from the Checker Framework to type-check your programs. A pluggable type-checker is a bug-finding and verification tool. It can help you to detect and prevent a variety of errors including null pointer errors, incorrect uses of equality operations, and side effect errors (and other errors). This document describes how to use the Checker Plugin to run pluggable type-checking from within Eclipse. For details about pluggable type-checking itself, see the Checker Framework documentation.

Requirements:

This plugin has been tested on both Eclipse 3.7.2 and 4.2.1 using either Java 6 or 7.

Your Eclipse MUST be running on a Java 6 VM or newer. To see what Java VM is being used by eclipse, select from the menu HelpAbout Eclipse PlatformInstallation Details. Depending on your installation, the menu may be HelpAbout Eclipse SDKInstallation Details.


How to install:

  1. In Eclipse, select from the menu Help Install New Software...
  2. Click Add....
  3. Enter the following:
    • Name: Checker Framework
    • Location: http://types.cs.washington.edu/checker-framework/eclipse
    and click OK.
  4. Under Work with:, you should see "Checker Framework".
    Select that entry and look at the selection area below.
  5. In the selection area, you should see the "Checker Framework Feature" under the "Pluggable Type-Checking" category.
    (You may have to expand the tree to make the feature visible.)
    Select the checkbox next to it and click Next.
  6. Select the I accept the terms in the license agreement option and click Next.
  7. Then click Finish.
  8. The plugin is not digitally signed. Install it anyway.
  9. Click Yes to restart Eclipse.

How to use Checkers Feature:

Optionally, you may add checkers-quals.jar to your project's classpath. (After you do this, Eclipse may complain about unresolved classes referenced from a classfile. This does not affect the checking, but to make the warning go away, add javac.jar to the project's classpath.) This is not necessary but will keep Eclipse from complaining about missing annotation classes. Alternatively, you can use the Implicit Import feature.

To perform the checking, select the checker from the context menu of a Java project, for example Checker FrameworkRun Nullness Checker. The checker will run and warnings will be added to the Problems view. To remove the warning markers, run Checker FrameworkClear checker markers (or Shift+Ctrl+C). Note that markers are cleared per project.

Checker context menu

You can also run a checker on individual packages or files. To do this, just right-click on the package or file you want to typecheck and use the context menu as documented above.

If you want to run multiple checkers at once, you can do so using the Run selected checkers action (or Ctrl+Alt+C). This will run the checkers that are selected in the Checkers section in the preferences, which are accessible through WindowPreferences. These selections are also used for automatic build, which is described below.

Preferences

Most of the command-line options that can be supplied to the Checker Framework compiler are also supported by this plugin. To set the various options, go to WindowPreferences and select the Checker section. The options that correspond to command-line switches are marked as such.

For more information on the supported command-line options, see the Checker Framework Documentation.

To customize keyboard shortcuts for plugin commands, go to PreferencesGeneralKeys and search for "Checker Plugin". This should show all the plugin commands and allow shortcut rebinding.

Adding support for a new checker

The plugin comes with support for all checkers bundled in the Checker Framework.

To make the plugin support a new checker, use the Custom Checker preference page. By pressing the Search... button you can select from a searchable listing of classes in the workspace. The class or classes you select must be on the classpath of the project you are type-checking. The custom class that you select will be used if you select the Run Custom Checker action from the popup menu. Note that if the preference field is empty you will get a warning message that no checkers were configured.

If your checker supports extra command-line flags, you can pass these in the Additional compiler parameters field in the preferences, which will append the input to the compiler's arguments.

Development style and implicit imports

If you work in a team and not everyone uses the Checker Framework or if you use older versions of Java, you can use implicit imports to avoid creating an explicit dependency on checker-quals.jar. Just enable the setting in the preferences. After that, you can write annotations in comments. The annotation classes that will be imported will be those that correspond to checkers selected in the preferences. Note that if no checkers are set, the type-checker will not see any type annotations in comments.

Customizing the build environment

By default, the plugin uses your system-specified JRE (whatever System.getProperty("java.home") returns). However, if would like to use custom JDK libraries you should specify those on the Eclipse system library buildpath in the project properties. You also have the option of explicitly setting the java executable to use in the plugin preferences.

How to report problems:

Submit bug reports at http://code.google.com/p/checker-framework/issues/list

Troubleshooting tips

If you are having problems with the output from the plugin, you can check to see what the output on the built-in Eclipse console view, as opposed to the problems view that the Checker Plugin populates, indicates. The console will get the raw output from the compiler. Attaching the console output to a bug report can also help us figure out which component is reponsible for the bug.

If you are finding that the plugin emits different or additional warnings in its problems view that Eclipse does not that are unrelated to checkers, this is likely because the Eclipse compiler and Sun's javac compiler have different behaviors on certain kinds of errors. In this case, you can either try to fix the underlying cause for the warning or you can add a regular expression in the preferences (see the "Regex for warning/error filter" field) to filter the compiler output.

Where to get the source code:

To install and use the Checker Plugin you will not need to access or compile the source code. However, if you would like to make changes or browse the source code, it is publicly available. The repository for the code within the Checker Framework repository: http://code.google.com/p/checker-framework/. The repository is hosted using Mercurial. To check the source out, use the following command: hg clone https://code.google.com/p/checker-framework/