Getting Started

APT in Eclipse

A Java annotation processor is a compiler plug-in that can gather information about source code as it is being compiled, generate additional Java types or other resource files, and post warnings and errors. Eclipse 3.2 provided support for annotation processors using the Java 5 Mirror APIs, and Eclipse 3.3 added support for processors using the Java 6 annotation processing APIs.

Both Java 5 and Java 6 annotation processors can be called during a build. Errors and warnings produced by the processors will be reported in the Problems view, and build artifacts will be created just as if you were running Sun's apt tool (for Java 5) or javac compiler (for Java 6) from the command line.

Java 5 processors can also be executed as you are typing in the editor. This permits processors to report errors during editing, which may be helpful. This feature can be enabled or disabled via the annotation processor properties dialog. In addition to reporting errors, Java 5 processors can also generate files as you are typing in the editor. This feature is only enabled if the processor includes "enableTypeGenerationInEditor" in the set of strings it returns from its implementation of AnnotationProcessorFactory.supportedOptions(). This string is defined in the class org.eclipse.jdt.apt.core.AptPreferenceConstants.

Eclipse does not support executing Java 6 processors while typing in the editor; you must save and build in order for Java 6 processors to report errors or generate files.

For more detailed information about how the APT plugins work and how to write annotation processors of your own, you can view the JDT-APT project web site.

Batch Compilation

The Eclipse Java compiler is available outside of the Eclipse IDE by using the batch mode compiler, via ecj.jar or the Java 6 javax.tools.JavaCompiler interface. Java 5 annotation processors are not available in this way, but Java 6 annotation processors are fully supported.

Turning on Annotation Processing

You must have your project's compiler configured to use Java 5.0 or higher compliance in the preferences, under Java->Compiler:

Screenshot of Compiler preference page

Java 6 processors will only be run if the project's Java compiler compliance level is set to Java 6 or higher, and Eclipse is running on a Java 1.6 or higher JVM.

Next you need to enable annotation processing under Java->Compiler->Annotation Processing:

Screenshot of Annotation Processing properties page

In this dialog you can also specify the generated source directory if desired, and provide any processor options that are necessary.

Note: "-Aclasspath" and "-Asourcepath" options are automatically passed to all your Java 5 processors by Eclipse, so it is unnecessary to provide those.

Adding Annotation Processors

You can add annotation processors to your project under Java->Compiler->Annotation Processing->Factory Path:

Screenshot of Factory Path properties page

Processors can be contained in jar files or in Eclipse plug-ins. The Factory Path list includes both Java 5 and Java 6 processors.

Working On Annotation Processors

The annotation processors used in a project must exist in binary form (as jar files or plug-ins) before the project is built. Therefore it is not possible to include both processor code and code to be processed within the same project. Developers of annotation processors are advised to keep annotation processor projects separate from the projects containing the target code that is to be processed. Indeed it may be preferable to keep them in separate workspaces, to facilitate debugging.

Factory Path and Source Control

The factory path is stored in a file named ".factorypath" at the project root, similar to the classpath, and should be treated the same way as the classpath with regard to version control. In order to avoid hard-coding paths to factory jars, you can either use project-relative jars via the "Add Jars..." button, or use a classpath variable via the "Add Variable..." button.

Processor Options and Source Control

Processor options are stored in the .settings folder within each project, which is also where other compiler options are stored. All files within the .settings folder are typically managed with source control.

You may need to use paths as some of the options passed to your annotation processors. Again, by avoiding hard-coding of absolute paths you'll be able to share your configuration in source control. To permit this, Eclipse supports using classpath variables inside of processor options. Variables are delimited on both sides by %, and must be the first segment of a path.

For example, if FOO is a classpath variable that points to d:/foo, then %FOO%/bar.txt will resolve to d:/foo/bar.txt when the processor is called. If the classpath variable does not exist, then the raw string ("%FOO%" in this example) will be added to the environment options. However, the remainder of the string ("bar.txt" in this example) does not need to exist.

The reserved variable ROOT is given special meaning: it is the workspace root, and introduces a project resource. For instance, if quux is the name of a project, then %ROOT%/quux will resolve to the absolute path of quux and %ROOT%/quux/.classpath will resolve to the absolute path of the file .classpath within project quux. When using ROOT, the first segment of the path must actually exist: in the example, the project quux must exist, but .classpath need not.