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:
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:
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:
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.
