Google Git
Sign in
eclipse / gerrit / platform / eclipse.platform.common / 9fdca46330652666e6d1d14a37881d89d5d9de90 / . / bundles / org.eclipse.jdt.doc.isv / guide / jdt_api_compile.htm
blob: 2bebe995353068e35a0db8afb6b2719e4ecb51cd [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
<title>Compiling Java code</title>
<link rel="stylesheet" type="text/css" href="../book.css">
</head>
<body>
<h2> Compiling Java code</h2>
<p> The JDT plug-ins include an incremental and batch Java compiler for building
Java .class files from source code. There is no direct API provided by the
compiler. It is installed as a builder on Java projects. Compilation is triggered
using standard platform build mechanisms.</p>
<p> The platform build mechanism is described in detail in <a href="../../org.eclipse.platform.doc.isv/guide/resAdv_builders.htm" class="XRef">
Incremental project builders</a> .</p>
<h3> Compiling code</h3>
<p> You can programmatically compile the Java source files in a project using
the build API.</p>
<font color="#4444cc"><pre>
IProject myProject;
IProgressMonitor myProgressMonitor;
myProject.build(IncrementalProjectBuilder.INCREMENTAL_BUILD, myProgressMonitor);
</pre></font>
<p> For a Java project, this invokes the Java incremental project builder
(along with any other incremental project builders that have been added
to the project's build spec). The generated .class files are written to
the designated output folder. Additional resource files are also copied to the output folder.&nbsp;</p>
<p> In the case of a full batch build, all the
.class files in the output folder may be 'scrubbed' to ensure that no stale
files are found. This is controlled using a JDT Core Builder Option (<a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#CORE_JAVA_BUILD_CLEAN_OUTPUT_FOLDER">CORE_JAVA_BUILD_CLEAN_OUTPUT_FOLDER</a>).&nbsp;
The default for this option is to clean output folders.&nbsp; Unless this option
is reset, you must ensure that you place all .class files for which
you do not have corresponding source files in a separate class file folder
on the classpath instead of the output folder.</p>
<p>The
incremental and batch builders can be configured with other options that
control which resources are copied to the output folder.&nbsp; The following sample shows how to set up a resource filter so that files ending with '.ignore' and folders named 'META-INF',
are not copied to the output folder:
<font color="#4444cc">
<pre> Hashtable options = JavaCore.getOptions();
options.put(JavaCore.CORE_JAVA_BUILD_RESOURCE_COPY_FILTER, &quot;*.ignore,META-INF/&quot;);
JavaCore.setOptions(options);
</pre>
</font></p>
<p> Filenames are filtered if they match one of the supplied patterns. Entire
folders are filtered if their name matches one of the supplied folder names
which end in a path separator.</p>
<p> The incremental and batch builders can also be configured to only generate
a single error when the .classpath file has errors. This option is set by
default and eliminates numerous errors.&nbsp; See <a href="jdt_api_options.htm#builder">JDT
Core Builder Options</a> for a complete list of builder-related options and
their defaults. </p>
<p>The compiler can also be configured using <a href="../reference/api/org/eclipse/jdt/core/JavaCore.html"><b>JavaCore</b></a>
options.&nbsp; For example, you can define the severity that should be used for
different kinds of problems that are found during compilation.&nbsp; See <a href="jdt_api_options.htm#compiler">JDT
Core Compiler Options </a>for a complete list of compiler-related options and their defaults. </p>
<p>When programmatically configuring options for the builder or compiler, you
should determine the scope of the option.&nbsp; For example, setting up a
resource filter may only apply to a particular project.&nbsp; The following example sets up
the same resource filter shown earlier, but sets it only the individual
project. </p>
<font color="#4444cc">
<pre>
Hashtable options = myProject.getOptions(false); // get only the options set up in this project
options.put(JavaCore.CORE_JAVA_BUILD_RESOURCE_COPY_FILTER, &quot;*.ignore,META-INF/&quot;);
myProject.setOptions(options);
</pre>
</font>
<h3>Using the batch compiler</h3>
<h4>Finding the batch compiler</h4>
<p>The batch compiler class is located in the internal classes of the
JDT/Core plug-in. So it is in the <i>jdtcore.jar</i> file in the directory
<i>plugins/org.eclipse.jdt.core</i>.
The name of the class is <i>org.eclipse.jdt.internal.compiler.batch.Main</i>.
</p>
<h4>Running the batch compiler</h4>
<ul>
<li>Using the main method.</li>
Using the main method. The Main class has a main method. This
is the classical way to invoke the batch compiler on a command-line.
<ul>
<li>
For example on a command-line:
<p><code><font color="#3366FF">java -classpath org.eclipse.jdt.core_3.1.0.jar org.eclipse.jdt.internal.compiler.batch.Main
-classpath rt.jar A.java</font></code></p>
<p>or:</p>
<p><code><font color="#3366FF">java -jar org.eclipse.jdt.core_3.1.0.jar -classpath rt.jar A.java</font></code></p>
</li>
<li>For example in a java source:
<p><code><font color="#3366FF">org.eclipse.jdt.internal.compiler.batch.Main.main(new
String[] {"-classpath", "rt.jar", "A.java"});</font></code></p>
</li></ul>
<li>
Using the static compile(String) method.
<p>The <code>compile(String)</code> method is a convenient method to invoke
the batch compiler in a java application. Instead of
<code><font color="#3366FF">org.eclipse.jdt.internal.compiler.batch.Main.main(new
String[] {"-classpath", "rt.jar", "A.java"});</font></code>
you can simply write <code><font color="#3366FF">org.eclipse.jdt.internal.compiler.batch.Main.compile("-classpath
rt.jar A.java");</font></code></p></li>
</ul>
<h4>Which options are available?</h4>
<p>
With the orange background, these are suggested options.
</p>
<table BORDER CELLSPACING=2 CELLPADDING=2 COLS=2>
<tr>
<th>Name</th>
<th>Usage</th>
</tr>
<tr>
<th colspan="2">Classpath options</th>
</tr>
<tr>
<td valign=top bgcolor="#FFCCAA" width="250">-bootclasspath &lt;dir&nbsp;1&gt;;&lt;dir&nbsp;2&gt;;...;&lt;dir&nbsp;P&gt;</td>
<td valign=top bgcolor="#FFCCAA">This is a list of directory or jar files used to bootstrap the class files used by the compiler. By default the libraries of the running
VM are used. Entries are separated by the platform path separator.
<br>Each directory or file can specify access rules for types between '[' and ']'.
</td>
</tr>
<tr>
<td valign="top" bgcolor="#FFCCAA" width="250">-cp<br>-classpath &lt;dir&nbsp;1&gt;;&lt;dir&nbsp;2&gt;;...;&lt;dir&nbsp;P&gt;</td>
<td valign=top bgcolor="#FFCCAA">This is a list of directory or jar files used to compile the source files. The default value is the value of the property "java.class.path".
Entries are separated by the platform path separator.
<br>Each directory or file can specify access rules for types between '[' and ']' (e.g. [-X] to forbid access to type X, [~X] to
discourage access to type X, [+p/X:-p/*] to forbid access to all types in package p but allow access to p/X).
</td>
</tr>
<tr>
<td valign=top width="250">-extdirs &lt;dir&nbsp;1&gt;;&lt;dir&nbsp;2&gt;;...;&lt;dir&nbsp;P&gt;</td>
<td valign=top>This is a list of directory used to specify the location of extension zip/jar files. Entries are separated by the platform path separator.</td>
</tr>
<tr>
<td valign=top width="250">-endorseddirs &lt;dir&nbsp;1&gt;;&lt;dir&nbsp;2&gt;;...;&lt;dir&nbsp;P&gt;</td>
<td valign=top>This is a list of directory used to specify the location of endorsed zip/jar files. Entries are separated by the platform path separator.</td>
</tr>
<tr>
<td valign=top width="250">-sourcepath &lt;dir&nbsp;1&gt;;&lt;dir&nbsp;2&gt;;...;&lt;dir&nbsp;P&gt;</td>
<td valign=top>This is a list of directory used to specify the source files. Entries are separated by the platform path separator.
<br>Each directory can specify access rules for types between '[' and ']'.</td>
</tr>
<tr>
<td valign=top bgcolor="#FFCCAA" width="250">-d &lt;dir 1&gt;|none</td>
<td bgcolor="#FFCCAA">This is used to specify in which directory the generated .class files should be dumped. If it is omitted, no package directory structure is created.<br>
If you don't want to generate .class files, use <font color="#3366FF">-d none</font>.</td>
</tr>
<tr>
<td valign=top width="250">-encoding &lt;encoding name&gt;</td>
<td>Specify default source encoding format (custom encoding can also be specified on a per file basis by suffixing each input source file/folder name with <font color="#3366FF">[encoding &lt;encoding name&gt;]</font>).</td>
</tr>
<tr>
<th colspan="2">Compliance options</th>
</tr>
<tr>
<td valign=top width="250">-target 1.1|1.2|1.3|1.4|1.5|5|5.0|1.6|6|6.0</td>
<td>This specifies the .class file target setting.
The possible value are:
<ul>
<li><font color="#3366FF">1.1</font> (major version: 45 minor: 3)</li>
<li><font color="#3366FF">1.2</font> (major version: 46 minor: 0)</li>
<li><font color="#3366FF">1.3</font> (major version: 47 minor: 0)</li>
<li><font color="#3366FF">1.4</font> (major version: 48 minor: 0)</li>
<li><font color="#3366FF">1.5</font>, <font color="#3366FF">5</font> or <font color="#3366FF">5.0</font> (major version: 49 minor: 0)</li>
<li><font color="#3366FF">1.6</font>, <font color="#3366FF">6</font> or <font color="#3366FF">6.0</font> (major version: 50 minor: 0)</li>
</ul>
Defaults are:
<ul>
<li><font color="#3366FF">1.1</font> in <font color="#3366FF">-1.3</font> mode</li>
<li><font color="#3366FF">1.2</font> in <font color="#3366FF">-1.4</font> mode</li>
<li><font color="#3366FF">1.5</font> in <font color="#3366FF">-1.5</font> mode</li>
<li><font color="#3366FF">1.6</font> in <font color="#3366FF">-1.6</font> mode</li>
</ul>
</td>
</tr>
<tr>
<td valign=top>-1.3</td>
<td>Set compliance level to <font color="#3366FF">1.3</font>. Implicit -source 1.3 -target 1.1.</td>
</tr>
<tr>
<td valign=top>-1.4</td>
<td>Set compliance level to <font color="#3366FF">1.4</font> (default). Implicit -source 1.3 -target 1.2.</td>
</tr>
<tr>
<td valign=top>-1.5</td>
<td>Set compliance level to <font color="#3366FF">1.5</font>. Implicit -source 1.5 -target 1.5.</td>
</tr>
<tr>
<td valign=top>-1.6</td>
<td>Set compliance level to <font color="#3366FF">1.6</font>. Implicit -source 1.6 -target 1.6.</td>
</tr>
<tr>
<td valign=top width="250">-source 1.3|1.4|1.5|5|5.0|1.6|6|6.0</td>
<td>This is used to enable the source level of the compiler.<br>
The possible value are:
<ul>
<li><font color="#3366FF">1.3</font></li>
<li><font color="#3366FF">1.4</font></li>
<li><font color="#3366FF">1.5</font>, <font color="#3366FF">5</font> or <font color="#3366FF">5.0</font></li>
<li><font color="#3366FF">1.6</font>, <font color="#3366FF">6</font> or <font color="#3366FF">6.0</font></li>
</ul>
Defaults are:
<ul>
<li><font color="#3366FF">1.3</font> in <font color="#3366FF">-1.3</font> mode</li>
<li><font color="#3366FF">1.3</font> in <font color="#3366FF">-1.4</font> mode</li>
<li><font color="#3366FF">1.5</font> in <font color="#3366FF">-1.5</font> mode</li>
<li><font color="#3366FF">1.6</font> in <font color="#3366FF">-1.6</font> mode</li>
</ul>
In <font color="#3366FF">1.4</font>, <font color="#3366FF"><I>assert</I></font> is treated as a keyword. In <font color="#3366FF">1.5</font>, <font color="#3366FF"><I>enum</I></font> and <font color="#3366FF"><i>assert</i></font> are treated as a keyword.</td>
</tr>
<tr>
<th colspan="2">Warning options</th>
</tr>
<tr>
<td valign=top width="250">-warn:<blockquote>allDeprecation<br>allJavadoc<br><font color="#FF0000">assertIdentifier</font><br>boxing<br><font color="#FF0000">charConcat</font><br>conditionAssign<br><font color="#FF0000">constructorName</font>
<br>dep-ann<br><font color="#FF0000">deprecation</font><br><font color="#FF0000">discouraged</font><br>emptyBlock<br>enumSwitch<br>fieldHiding<br>finalBound<br><font color="#FF0000">finally</font>
<br><font color="#FF0000">forbidden</font><br>hiding<br>incomplete-switch<br>indirectStatic
<br><font color="#FF0000">intfAnnotation</font><br><font color="#FF0000">intfNonInherited</font><br>javadoc<br>localHiding
<br><font color="#FF0000">maskedCatchBlocks</font><br>nls<br><font color="#FF0000">noEffectAssign</font><br>null<br>over-ann<br><font color="#FF0000">pkgDefaultMethod</font><br>semicolon<br><font color="#FF0000">serial</font><br>
specialParamHiding<br>static-access<br><font color="#FF0000">staticReceiver</font><br><font color="#FF0000">suppress</font><br>synthetic-access<br>syntheticAccess<br>tasks(&lt;task1&gt;|...|&lt;taskN&gt;)<br>
<font color="#FF0000">typeHiding</font><br><font color="#FF0000">unchecked</font><br>unnecessaryElse<br>unqualified-field-access<br>unqualifiedField<br>uselessTypeCheck
<br>unused<br>unusedArgument<br><font color="#FF0000">unusedImport</font><br><font color="#FF0000">unusedLocal</font><br><font color="#FF0000">unusedPrivate</font><br>unusedThrown
<br><font color="#FF0000">varargsCast</font><br><font color="#FF0000">warningToken</font>
</blockquote>
</td>
<td valign=top>Set warning level.<br>e.g. <font color="#3366FF">-warn:unusedLocal,deprecation</font><br>
<p>In <font color="#FF0000">red</font> are the default settings.</p>
<p>
<pre>
-warn:&lt;warnings separated by ,&gt; enable exactly the listed warnings
-warn:+&lt;warnings separated by ,&gt; enable additional warnings
-warn:-&lt;warnings separated by ,&gt; disable specific warnings
</pre>
<table>
<tr>
<th align=left valign=top>allDeprecation</th>
<td valign=top>deprecation even inside deprecated code</td>
</tr>
<tr>
<th align=left valign=top>allJavadoc</th>
<td valign=top>invalid or missing javadoc</td>
</tr>
<tr>
<th align=left valign=top>assertIdentifier</th>
<td valign=top>occurrence of <i>assert</i> used as identifier</td>
</tr>
<tr>
<th align=left valign=top>boxing</th>
<td valign=top>autoboxing conversion</td>
</tr>
<tr>
<th align=left valign=top>charConcat</th>
<td valign=top>when a char array is used in a string concatenation without being converted explicitly to
a string</td>
</tr>
<tr>
<th align=left valign=top>conditionAssign</th>
<td valign=top>possible accidental boolean assignment</td>
</tr>
<tr>
<th align=left valign=top>constructorName</th>
<td valign=top>method with constructor name</td>
</tr>
<tr>
<th align=left valign=top>dep-ann</th>
<td valign=top>missing @Deprecated annotation</td>
</tr>
<tr>
<th align=left valign=top>deprecation</th>
<td valign=top>usage of deprecated type or member outside deprecated code</td>
</tr>
<tr>
<th align=left valign=top>discouraged</th>
<td valign=top>use of types matching a discouraged access rule</td>
</tr>
<tr>
<th align=left valign=top>emptyBlock</th>
<td valign=top>undocumented empty block</td>
</tr>
<tr>
<th align=left valign=top>enumSwitch,<br>incomplete-switch</th>
<td valign=top>incomplete enum switch</td>
</tr>
<tr>
<th align=left valign=top>fieldHiding</th>
<td valign=top>field hiding another variable</td>
</tr>
<tr>
<th align=left valign=top>finalBound</th>
<td valign=top>type parameter with final bound</td>
</tr>
<tr>
<th align=left valign=top>finally</th>
<td valign=top>finally block not completing normally</td>
</tr>
<tr>
<th align=left valign=top>forbidden</th>
<td valign=top>use of types matching a forbidden access rule</td>
</tr>
<tr>
<th align=left valign=top>hiding</th>
<td valign=top>macro for fieldHiding, localHiding, typeHiding and maskedCatchBlock</td>
</tr>
<tr>
<th align=left valign=top>indirectStatic</th>
<td valign=top>indirect reference to static member</td>
</tr>
<tr>
<th align=left valign=top>intfAnnotation</th>
<td valign=top>annotation type used as super interface</td>
</tr>
<tr>
<th align=left valign=top>intfNonInherited</th>
<td valign=top>interface non-inherited method compatibility</td>
</tr>
<tr>
<th align=left valign=top>javadoc</th>
<td valign=top>invalid javadoc</td>
</tr>
<tr>
<th align=left valign=top>localHiding</th>
<td valign=top>local variable hiding another variable</td>
</tr>
<tr>
<th align=left valign=top>maskedCatchBlocks</th>
<td valign=top>hidden catch block</td>
</tr>
<tr>
<th align=left valign=top>nls</th>
<td>non-nls string literals (lacking of tags //$NON-NLS-&lt;n&gt;)</td>
</tr>
<tr>
<th align=left valign=top>noEffectAssign</th>
<td valign=top>for assignment with no effect</td>
</tr>
<tr>
<th align=left valign=top>null</th>
<td>missing or redundant null check</td>
</tr>
<tr>
<th align=left valign=top>over-ann</th>
<td>missing @Override annotation</td>
</tr>
<tr>
<th align=left valign=top>pkgDefaultMethod</th>
<td valign=top>attempt to override package-default method</td>
</tr>
<tr>
<th align=left valign=top>serial</th>
<td valign=top>missing serialVersionUID</td>
</tr>
<tr>
<th align=left valign=top>semicolon</th>
<td valign=top>unnecessary semicolon or empty statement</td>
</tr>
<tr>
<th align=left valign=top>specialParamHiding</th>
<td valign=top>constructor or setter parameter hiding another field</td>
</tr>
<tr>
<th align=left valign=top>static-access</th>
<td valign=top>macro for indirectStatic and staticReceiver</td>
</tr>
<tr>
<th align=left valign=top>staticReceiver</th>
<td valign=top>if a non static receiver is used to get a static field or call a static method</td>
</tr>
<tr>
<th align=left valign=top>suppress</th>
<td valign=top>enable @SuppressWarnings</td>
</tr>
<tr>
<th align=left valign=top>syntheticAccess,<br>synthetic-access</th>
<td valign=top>when performing synthetic access for innerclass</td>
</tr>
<tr>
<th align=left valign=top>tasks</th>
<td valign=top>enable support for tasks tags in source code</td>
</tr>
<tr>
<th align=left valign=top>typeHiding</th>
<td valign=top>type parameter hiding another type</td>
</tr>
<tr>
<th align=left valign=top>unchecked</th>
<td valign=top>unchecked type operation</td>
</tr>
<tr>
<th align=left valign=top>unnecessaryElse</th>
<td valign=top>unnecessary else clause</td>
</tr>
<tr>
<th align=left valign=top>unqualified-field-access,<br>unqualifiedField</th>
<td valign=top>unqualified reference to field</td>
</tr>
<tr>
<th align=left valign=top>unused</th>
<td valign=top>macro for unusedArgument, unusedImport, unusedLocal, unusedPrivate and unusedThrown</td>
</tr>
<tr>
<th align=left valign=top>unusedArgument</th>
<td valign=top>unused method argument</td>
</tr>
<tr>
<th align=left valign=top>unusedImport</th>
<td valign=top>unused import reference</td>
</tr>
<tr>
<th align=left valign=top>unusedLocal</th>
<td valign=top>unused local variable</td>
</tr>
<tr>
<th align=left valign=top>unusedPrivate</th>
<td valign=top>unused private member declaration</td>
</tr>
<tr>
<th align=left valign=top>unusedThrown</th>
<td valign=top>unused declared thrown exception</td>
</tr>
<tr>
<th align=left valign=top>uselessTypeCheck</th>
<td valign=top>unnecessary cast/instanceof operation</td>
</tr>
<tr>
<th align=left valign=top>varargsCast</th>
<td valign=top>varargs argument need explicit cast</td>
</tr>
<tr>
<th align=left valign=top>warningToken</th>
<td valign=top>unhandled warning token in @SuppressWarnings</td>
</tr>
</table>
</p>
</td>
</tr>
<tr>
<td valign=top>-nowarn</td>
<td>No warning (equivalent to <font color="#3366FF">-warn:none</font>)</td>
</tr>
<tr>
<td valign=top>-deprecation</td>
<td>Equivalent to <font color="#3366FF">-warn:deprecation</font>.</td>
</tr>
<tr>
<th colspan="2">Debug options</th>
</tr>
<tr>
<td valign=top>-g[:none|:lines,vars,source]
</td>
<td>Set the debug attributes level<br>
<table>
<tr>
<th align=left>-g</th>
<td>All debug info (equivalent to <font color="#3366FF">-g:lines,vars,source</font>)
</td>
</tr>
<tr>
<th align=left>-g:none</th>
<td>No debug info</td>
</tr>
<tr>
<th align=left>-g:[lines,vars,source]</th>
<td>Selective debug info</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign=top>-preserveAllLocals</td>
<td>Explicitly request the compiler to preserve all local variables (for debug purpose). If omitted, the compiler will removed unused locals.</td>
</tr>
<tr>
<th colspan="2">Advanced options</th>
</tr>
<tr>
<td>@&lt;file&gt;</td>
<td valign=top>Read command-line arguments from file</td>
</tr>
<tr>
<td>-maxProblems&nbsp;&lt;n&gt;</td>
<td valign=top>Max number of problems per compilation unit (100 by default)</td>
</tr>
<tr>
<td valign=top>-log &lt;filename&gt;</td>
<td>Specify a log file in which all output from the compiler will be dumped. This is really useful if you want to debug the batch
compiler or get a file which contains all errors and warnings from a batch build. If the extension is <b>.xml</b>, the generated log
will be a xml file.
</td>
</tr>
<tr>
<td valign=top>-proceedOnError</td>
<td>Keep compiling when error, dumping class files with problem methods or problem types. This is recommended only if you want
to be able to run your application even if you have remaining errors.</td>
</tr>
<tr>
<td valign=top>-verbose</td>
<td>Print accessed/processed compilation units in the console or the log file if specified.</td>
</tr>
<tr>
<td valign=top>-referenceInfo</td>
<td>Compute reference info. This is useful only if connected to the builder. The reference infos are useless otherwise.</td>
</tr>
<tr>
<td valign=top>-progress</td>
<td>Show progress (only in -log mode)</td>
</tr>
<tr>
<td valign=top>-time
</td>
<td>Display speed information</td>
</tr>
<tr>
<td valign=top>-noExit</td>
<td>Do not call <font color="#3366FF">System.exit(n)</font> at end of compilation (<font color="#3366FF">n=0</font> if no error)</td>
</tr>
<tr>
<td valign=top>-repeat &lt;n&gt;
</td>
<td>Repeat compilation process <font color="#3366FF">&lt;n&gt;</font> times (perf analysis).</td>
</tr>
<tr>
<td valign=top>-inlineJSR</td>
<td>Inline JSR bytecode (implicit if target >= 1.5)</td>
</tr>
<tr>
<td valign=top>-enableJavadoc</td>
<td>Consider references inside javadoc</td>
</tr>
<tr>
<th colspan="2">Helping options</th>
</tr>
<tr>
<td>-? -help</td>
<td valign=top>Display the help message</td>
</tr>
<tr>
<td valign=top>-v -version</td>
<td>Display the build number of the compiler. This is very useful to report a bug.</td>
</tr>
<tr>
<td valign=top>-showversion</td>
<td>Display the build number of the compiler and continue. This is very useful to report a bug.</td>
</tr>
</table>
<h4>Examples</h4>
<table>
<tr>
<td valign=top><code><font color="#3366FF">d:\temp -classpath rt.jar -time -g -d d:/tmp</font></code>
</td>
<td valign=top>It compiles all source files in d:\temp and its subfolders. The classpath is simply rt.jar. It generates all debug
attributes and all generated .class files are dumped in d:\tmp. The speed of the compiler will be displayed once the batch process
is completed.</td>
</tr>
<tr>
<td valign=top><code><font color="#3366FF">d:\temp\Test.java -classpath d:\temp;rt.jar -g:none</font></code>
</td>
<td valign=top>It compiles only Test.java and it will retrieve any dependant files from d:\temp. The classpath is rt.jar and d:\temp, which means that all necessary classes
are searched first in d:\temp and then in rt.jar. It generates no debug attributes and all generated .class files are dumped in d:\tmp.</td>
</tr>
</table>
<h3>Using the ant javac adapter</h3>
The Eclipse compiler can be used inside an Ant script using the javac adapter.
In order to use the Eclipse compiler, you simply need to define the <b>build.compiler</b>
property in your script. Here is a small example. <font color="#4444cc">
<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;project name=&quot;compile&quot; default=&quot;main&quot; basedir=&quot;../.&quot;&gt;
<b>&lt;property name=&quot;build.compiler&quot; value=&quot;org.eclipse.jdt.core.JDTCompilerAdapter&quot;/&gt;</b>
&lt;property name=&quot;root&quot; value=&quot;${basedir}/src&quot;/&gt;
&lt;property name=&quot;destdir&quot; value=&quot;d:/temp/bin&quot; /&gt;
&lt;target name=&quot;main&quot;&gt;
&lt;javac srcdir=&quot;${root}&quot; destdir=&quot;${destdir}&quot; debug=&quot;on&quot; nowarn=&quot;on&quot; extdirs=&quot;d:/extdirs&quot; source=&quot;1.4&quot;&gt;
&lt;classpath&gt;
&lt;pathelement location=&quot;${basedir}/../org.eclipse.jdt.core/bin&quot;/&gt;
&lt;/classpath&gt;
&lt;/javac&gt;
&lt;/target&gt;
&lt;/project&gt;
</pre>
</font> The syntax used for the javac Ant task can be found in the <a href="http://jakarta.apache.org/ant/manual/CoreTasks/javac.html">
Ant javac task documentation</a>. The current adapter supports the Javac Ant task 1.4.1 up to 1.6.5 versions.
<p>If you are using a version above 1.5.0, you can use the nested compiler argument element to specify compiler
specific options.
</p>
<font color="#4444cc">
<pre>...
&lt;javac srcdir=&quot;${root}&quot; destdir=&quot;${destdir}&quot; debug=&quot;on&quot; nowarn=&quot;on&quot; extdirs=&quot;d:/extdirs&quot; source=&quot;1.4&quot;&gt;
&lt;classpath&gt;
&lt;pathelement location=&quot;${basedir}/../org.eclipse.jdt.core/bin&quot;/&gt;
&lt;/classpath&gt;
&lt;compilerarg compiler=&quot;org.eclipse.jdt.core.JDTCompilerAdapter&quot; line=&quot;-1.5 -warn:+boxing&quot;/&gt;
&lt;/javac&gt;
...
</pre>
</font>
<p>To prevent from getting compiler dependant scripts, we advice you to use the compiler argument set to <code>org.eclipse.jdt.core.JDTCompilerAdapter</code>.
If this is not set, the script can only be used with the Eclipse compiler. If set, the nested compiler argument is ignored if the name is different from the
compiler name specified by the <code>build.compiler</code> property.</p>
<h3> Problem determination</h3>
<p> JDT Core defines a specialized marker (marker type "<b>org.eclipse.jdt.core.problem</b>
") to denote compilation problems. To programmatically discover problems
detected by the compiler, the standard platform marker protocol should be
used. See <a href="../../org.eclipse.platform.doc.isv/guide/resAdv_markers.htm" class="XRef">
Resource Markers</a>
for an overview of using markers.</p>
<p> The following snippet finds all Java problem markers in a compilation
unit.</p>
<font color="#4444cc">
<pre> public IMarker[] findJavaProblemMarkers(ICompilationUnit cu)
throws CoreException {
IResource javaSourceFile = cu.getUnderlyingResource();
IMarker[] markers =
javaSourceFile.findMarkers(IJavaModelMarker.JAVA_MODEL_PROBLEM_MARKER,
true, IResource.DEPTH_INFINITE);
}
</pre>
</font>
<p> Java problem markers are maintained by the Java project builder and are
removed automatically as problems are resolved and the Java source is recompiled.</p>
<p>The problem id value is set by one of the constants in <b><a href="../reference/api/org/eclipse/jdt/core/compiler/IProblem.html">
IProblem</a>
</b>. The problem's id is reliable, but the message is localized and therefore
can be changed according to the default locale. The constants defined in <b><a href="../reference/api/org/eclipse/jdt/core/compiler/IProblem.html">
IProblem</a>
</b> are self-descriptive. </p>
<p>An implementation of <b><a href="../reference/api/org/eclipse/jdt/core/IProblemRequestor.html">
IProblemRequestor</a>
</b> should be defined to collect the problems discovered during a Java operation.
Working copies can be reconciled with problem detection if a <b><a href="../reference/api/org/eclipse/jdt/core/IProblemRequestor.html">
IProblemRequestor</a>
</b> has been supplied for the working copy creation. To achieve this, you
can use the <b><a href="../reference/api/org/eclipse/jdt/core/ICompilationUnit.html#reconcile(int, boolean, org.eclipse.jdt.core.WorkingCopyOwner, org.eclipse.core.runtime.IProgressMonitor)">
reconcile</a></b> method. Here is an example: <font color="#4444cc">
<pre>
ICompilationUnit unit = ..; // get some compilation unit
// create requestor for accumulating discovered problems
IProblemRequestor problemRequestor = new IProblemRequestor() {
public void acceptProblem(IProblem problem) {
System.out.println(problem.getID() + &quot;: &quot; + problem.getMessage());
}
public void beginReporting() {}
public void endReporting() {}
public boolean isActive() { return true; } // will detect problems if active
};
// use working copy to hold source with error
ICompilationUnit workingCopy = unit.getWorkingCopy(new WorkingCopyOwner() {}, problemRequestor, null);
((IOpenable)workingCopy).getBuffer().setContents(&quot;public class X extends Zork {}&quot;);
// trigger reconciliation
workingCopy.reconcile(NO_AST, true, null, null);
</pre></font> You can add an action on the reported problems in the acceptProblem(IProblem)
method. In this example, the reported problem will be that <b>Zork cannot
be resolved or is not a valid superclass</b> and its id is <b>IProblem.SuperclassNotFound</b>.
</p>
<h3>Excluding warnings using <code>SuppressWarnings</code></h3>
<p>Java 5.0 offers the option to the user to disable compilation warnings relative to a subset of a compilation unit using
the annotation <code>java.lang.SuppressWarning</code>.</p>
<pre>
@SuppressWarning("unused") public void foo() {
String s;
}
</pre>
<p>Without the annotation, the compiler would complain that the local variable <code>s</code> is never used.
With the annotation, the compiler silently ignore this warning locally to the <code>foo</code> method. This enables to
keep the warnings in other locations of the same compilation unit or the same project.</p>
<p>The list of tokens that can be used inside an <code>SuppressWarning</code> annotation is:</p>
<ul>
<li><font color="green">all</font> to suppress all warnings</li>
<li><font color="green">boxing</font> to suppress warnings relative to boxing/unboxing operations</li>
<li><font color="green">cast</font> to suppress warnings relative to cast operations</li>
<li><font color="green">dep-ann</font> to suppress warnings relative to deprecated annotation</li>
<li><font color="green">deprecation</font> to suppress warnings relative to deprecation</li>
<li><font color="green">fallthrough</font> to suppress warnings relative to missing breaks in switch statements</li>
<li><font color="green">finally</font> to suppress warnings relative to finally block that don't return</li>
<li><font color="green">hiding</font> to suppress warnings relative to locals that hide variable</li>
<li><font color="green">incomplete-switch</font> to suppress warnings relative to missing entries in a switch statement (enum case)</li>
<li><font color="green">nls</font> to suppress warnings relative to nls warnings</li>
<li><font color="green">null</font> to suppress warnings relative to null analysis</li>
<li><font color="green">restriction</font> to suppress warnings relative to usage of discouraged or forbidden references</li>
<li><font color="green">serial</font> to suppress warnings relative to missing serialVersionUID field for a serializable class</li>
<li><font color="green">static-access</font> to suppress warnings relative to incorrect static access</li>
<li><font color="green">synthetic-access</font> to suppress warnings relative to unoptimized access from inner classes</li>
<li><font color="green">unchecked</font> to suppress warnings relative to unchecked operations</li>
<li><font color="green">unqualified-field-access</font> to suppress warnings relative to field access unqualified</li>
<li><font color="green">unused</font> to suppress warnings relative to unused code</li>
</ul>
</body>
</html>