bundles/org.eclipse.jdt.doc.isv/guide/jdt_apt_getting_started.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
    <meta name="copyright" content="Copyright (c) IBM Corporation and others 2006, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
    <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
    <title>Getting started with APT in Eclipse</title>
 </head>

 <body>
 <h1>Getting Started</h1>
 <h2>APT in Eclipse</h2>

 <p>
 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
 <a href="http://download.oracle.com/javase/6/docs/jdk/api/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
 and Eclipse 3.3 added support for processors using the
 <a href="http://download.oracle.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
 Java 6 annotation processing APIs</a>.</p>
 <p>
 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.</p>
 <p>
 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 &quot;enableTypeGenerationInEditor&quot; in
 the set of strings it returns from its implementation of
 <a href="http://download.oracle.com/javase/6/docs/jdk/api/apt/mirror/com/sun/mirror/apt/AnnotationProcessorFactory.html#supportedOptions()">
 <code>AnnotationProcessorFactory.supportedOptions()</code></a>. This string is defined in
 the class <code>org.eclipse.jdt.apt.core.AptPreferenceConstants</code>.</p>
 <p>
 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.</p>

 <p>
 For more detailed information about how the APT plugins work and how to write annotation
 processors of your own, you can view the
 <a href="http://www.eclipse.org/jdt/apt/index.html">JDT-APT project web site</a>.
 </p>

 <h3>Batch Compilation</h3>
 The Eclipse Java compiler is available outside of the Eclipse IDE by using the
 <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm">batch mode compiler</a>, via ecj.jar or the Java 6
 <a href="http://download.oracle.com/javase/6/docs/api/javax/tools/JavaCompiler.html">
 <code>javax.tools.JavaCompiler</code></a> interface. Java 5 annotation processors
 are not available in this way, but Java 6 annotation processors are fully supported.

 <h3>Turning on Annotation Processing</h3>
 You must have your project's compiler configured to use Java 5.0 or higher compliance
 in the preferences, under Java-&gt;Compiler:
 <p>
 <img src="images/compiler_dialog.png" alt="Screenshot of Compiler preference page"/></p>
 <p>
 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.</p>
 <p>Next you need to enable annotation processing under
 Java-&gt;Compiler-&gt;Annotation Processing:</p>
 <p>
 <img src="images/annotation_processing.png" alt="Screenshot of Annotation Processing properties page"/></p>
 <p>
 In this dialog you can also specify the generated source directory if desired,
 and provide any processor options that are necessary.</p>
 <p>
 <b>Note: "-Aclasspath" and "-Asourcepath" options are automatically passed
 to all your Java 5 processors by Eclipse, so it is unnecessary to provide those.</b>
 </p>
 <h3>Adding Annotation Processors</h3>
 You can add annotation processors to your project under Java-&gt;Compiler-&gt;Annotation Processing-&gt;Factory Path:

 <p>
 <img src="images/factory_path.png" alt="Screenshot of Factory Path properties page"/></p>
 <p>
 Processors can be contained in jar files or in Eclipse plug-ins. The Factory Path list includes
 both Java 5 and Java 6 processors.</p>

 <h3>Working On Annotation Processors</h3>
 <p>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.</p>

 <h3>Factory Path and Source Control</h3>

 <p>The factory path is stored in a file named &quot;.factorypath&quot; 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.</p>

 <h3>Processor Options and Source Control</h3>

 <p>
 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.</p>
 <p>
 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.</p>
 <p>
 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 (&quot;%FOO%&quot; in this example) will be added to
 the environment options.  However, the remainder of the string (&quot;bar.txt&quot; in this example)
 does not need to exist.</p>
 <p>
 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.</p>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2006, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"/>
	<title>Getting started with APT in Eclipse</title>
	</head>

	<body>
	<h1>Getting Started</h1>
	<h2>APT in Eclipse</h2>

	<p>
	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
	<a href="http://download.oracle.com/javase/6/docs/jdk/api/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
	and Eclipse 3.3 added support for processors using the
	<a href="http://download.oracle.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
	Java 6 annotation processing APIs</a>.</p>
	<p>
	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.</p>
	<p>
	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
	<a href="http://download.oracle.com/javase/6/docs/jdk/api/apt/mirror/com/sun/mirror/apt/AnnotationProcessorFactory.html#supportedOptions()">
	<code>AnnotationProcessorFactory.supportedOptions()</code></a>. This string is defined in
	the class <code>org.eclipse.jdt.apt.core.AptPreferenceConstants</code>.</p>
	<p>
	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.</p>

	<p>
	For more detailed information about how the APT plugins work and how to write annotation
	processors of your own, you can view the
	<a href="http://www.eclipse.org/jdt/apt/index.html">JDT-APT project web site</a>.
	</p>

	<h3>Batch Compilation</h3>
	The Eclipse Java compiler is available outside of the Eclipse IDE by using the
	<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm">batch mode compiler</a>, via ecj.jar or the Java 6
	<a href="http://download.oracle.com/javase/6/docs/api/javax/tools/JavaCompiler.html">
	<code>javax.tools.JavaCompiler</code></a> interface. Java 5 annotation processors
	are not available in this way, but Java 6 annotation processors are fully supported.

	<h3>Turning on Annotation Processing</h3>
	You must have your project's compiler configured to use Java 5.0 or higher compliance
	in the preferences, under Java->Compiler:
	<p>
	<img src="images/compiler_dialog.png" alt="Screenshot of Compiler preference page"/></p>
	<p>
	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.</p>
	<p>Next you need to enable annotation processing under
	Java->Compiler->Annotation Processing:</p>
	<p>
	<img src="images/annotation_processing.png" alt="Screenshot of Annotation Processing properties page"/></p>
	<p>
	In this dialog you can also specify the generated source directory if desired,
	and provide any processor options that are necessary.</p>
	<p>
	<b>Note: "-Aclasspath" and "-Asourcepath" options are automatically passed
	to all your Java 5 processors by Eclipse, so it is unnecessary to provide those.</b>
	</p>
	<h3>Adding Annotation Processors</h3>
	You can add annotation processors to your project under Java->Compiler->Annotation Processing->Factory Path:

	<p>
	<img src="images/factory_path.png" alt="Screenshot of Factory Path properties page"/></p>
	<p>
	Processors can be contained in jar files or in Eclipse plug-ins. The Factory Path list includes
	both Java 5 and Java 6 processors.</p>

	<h3>Working On Annotation Processors</h3>
	<p>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.</p>

	<h3>Factory Path and Source Control</h3>

	<p>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.</p>

	<h3>Processor Options and Source Control</h3>

	<p>
	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.</p>
	<p>
	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.</p>
	<p>
	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.</p>
	<p>
	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.</p>
	</body>
	</html>