Compiling Java code

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.

The platform build mechanism is described in detail in Incremental project builders .

Compiling code

You can programmatically compile the Java source files in a project using the build API.

   IProject myProject;
   IProgressMonitor myProgressMonitor;
   myProject.build(IncrementalProjectBuilder.INCREMENTAL_BUILD, myProgressMonitor);

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. 

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 ( CORE_JAVA_BUILD_CLEAN_OUTPUT_FOLDER).  The default for this option is to clean output folders.  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.

The incremental and batch builders can be configured with other options that control which resources are copied to the output folder.  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:

   Hashtable options = JavaCore.getOptions();
   options.put(JavaCore.CORE_JAVA_BUILD_RESOURCE_COPY_FILTER, "*.ignore,META-INF/");
   JavaCore.setOptions(options);

Filenames are filtered out if they match one of the supplied patterns. Entire folders are filtered out if their name matches one of the supplied folder names which end in a path separator.

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.  See JDTCore Builder Options for a complete list of builder-related options and their defaults.

The compiler can also be configured using JavaCore options.  For example, you can define the severity that should be used for different kinds of problems that are found during compilation.  See JDTCore Compiler Options for a complete list of compiler-related options and their defaults.

When programmatically configuring options for the builder or compiler, you should specify the scope of the option.  For example, setting up a resource filter may apply to a particular project only:

   Hashtable options = myProject.getOptions(false);  // get only the options set up in this project
   options.put(JavaCore.CORE_JAVA_BUILD_RESOURCE_COPY_FILTER, "*.ignore,META-INF/");
   myProject.setOptions(options);

Using the batch compiler

Finding the batch compiler

The batch compiler class is located in the JDT Core plug-in. The name of the class is org.eclipse.jdt.compiler.batch.BatchCompiler. It is packaged into plugins/org.eclipse.jdt.core_3.4.0.<qualifier>.jar. Since 3.2, it is also available as a separate download. The name of the file is ecj.jar. Its corresponding source is also available. To get them, go to the download page and search for the section JDT Core Batch Compiler. This jar contains the batch compiler and the javac ant adapter.

Since 3.3, this jar also contains the support for jsr199 (Compiler API) and the support for jsr269 (Annotation processing). In order to use the annotations processing support, a 1.6 VM is required.

So it can be used as a standalone application and inside an Ant build outside of Eclipse.

Running the batch compiler

• From the command line.

  java -jar org.eclipse.jdt.core_3.4.0<qualifier>.jar -classpath rt.jar A.java

  or:

  java -jar ecj.jar -classpath rt.jar A.java

• Using the static compile(String commandLine, PrintWriter outWriter, PrintWriter errWriter, CompilationProgress progress) method of the class BatchCompiler.

  
  org.eclipse.jdt.compiler.CompilationProgress progress = null; // instantiate your subclass
  org.eclipse.jdt.internal.compiler.batch.BatchCompiler.compile(
     "-classpath rt.jar A.java",
     new PrintWriter(System.out),
     new PrintWriter(System.err),
     progress);
  
  

  You can control how progress is reported, or how the batch compiler is canceled, by subclassing the class org.eclipse.jdt.compiler.CompilationProgress.

Which options are available?

The recommended options have an orange background.

    -warn:none                               disable all warnings
    -warn:<warnings separated by ,>    enable exactly the listed warnings
    -warn:+<warnings separated by ,>   enable additional warnings
    -warn:-<warnings separated by ,>   disable specific warnings

Examples

Using the ant javac adapter

The Eclipse compiler can be used inside an Ant buildfile using the javac adapter. In order to use the Eclipse compiler, you simply need to define the build.compiler property in your buildfile.

In order to get the batch compiler working in an ant buildfile, the ant runtime classpath needs to contain the Eclipse batch compiler. When you run your ant buildfile:

1. outside of Eclipse: the easiest way to set up the ant runtime classpath is to add the ecj.jar file using the -lib argument or dumping it inside the ANT_HOME location.
2. inside Eclipse using the same JRE than Eclipse: the Eclipse batch compiler is implicitely added to the ant runtime classpath.
3. inside Eclipse using the different JRE: the Eclipse batch compiler must be explicitely added to the ant runtime classpath. This can be done using the ecj.jar file or using the org.eclipse.jdt.core jar file and the jdtCompilerAdapter.jar file located inside the org.eclipse.jdt.core jar file (this jar file needs to be extracted first).

Here is a small example:

<?xml version="1.0" encoding="UTF-8"?>
<project name="compile" default="main" basedir="../.">

	<property name="build.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter"/>

	<property name="root" value="${basedir}/src"/>

	<property name="destdir" value="d:/temp/bin" />

	<target name="main">
		<javac srcdir="${root}" destdir="${destdir}" debug="on" nowarn="on" extdirs="d:/extdirs" source="1.4">
		    <classpath>
		      <pathelement location="${basedir}/../org.eclipse.jdt.core/bin"/>
		    </classpath>
		</javac>
	</target>
</project>

The syntax used for the javac Ant task can be found in the Ant javac task documentation. The current adapter supports the Javac Ant task 1.4.1 up to 1.6.5 versions.

If you are using a version above 1.5.0, you can use the nested compiler argument element (<compilerarg>) to specify compiler specific options.

...
<javac srcdir="${root}" destdir="${destdir}" debug="on" nowarn="on" extdirs="d:/extdirs" source="1.4">
    <classpath>
      <pathelement location="${basedir}/../org.eclipse.jdt.core/bin"/>
    </classpath>
    <compilerarg compiler="org.eclipse.jdt.core.JDTCompilerAdapter" line="-1.5 -warn:+boxing"/>
</javac>
...

1. To prevent compiler dependant buildfiles, we strongly advise you to use a <compilerarg> whose "compiler" attribute value is org.eclipse.jdt.core.JDTCompilerAdapter. If this is not set, the buildfile 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 build.compiler property.
2. <compilerarg> should not be used to set values like target value, source value, debug options, or any options that could be set using the defined attributes of the javac ant task. Its usage must be reserved to pass compiler specific options like warning options. When a command-line argument is specified more than once, the Eclipse batch compiler can report errors like:

   duplicate target compliance setting specification: 1.5

Problem determination

JDT Core defines a specialized marker (marker type "org.eclipse.jdt.core.problem ") to denote compilation problems. To programmatically discover problems detected by the compiler, the standard platform marker protocol should be used. See Resource Markers for an overview of using markers.

The following snippet finds all Java problem markers in a compilation unit.

   public IMarker[] findJavaProblemMarkers(ICompilationUnit cu) 
      throws CoreException {
      IResource javaSourceFile = cu.getUnderlyingResource();
      IMarker[] markers = 
         javaSourceFile.findMarkers(IJavaModelMarker.JAVA_MODEL_PROBLEM_MARKER,
            true, IResource.DEPTH_INFINITE);
   }

Java problem markers are maintained by the Java project builder and are removed automatically as problems are resolved and the Java source is recompiled.

The problem id value is set to one of the constants defined in IProblem . 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 IProblem are self-descriptive.

An implementation of IProblemRequestor should be defined to collect the problems discovered during a Java operation. Working copies can be reconciled with problem detection if a IProblemRequestor has been supplied for the working copy creation. To achieve this, you can use the reconcile method. Here is an example:

  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() + ": " + 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("public class X extends Zork {}");

  // trigger reconciliation			
  workingCopy.reconcile(NO_AST, true, null, null);

You can add an action on the reported problems in the acceptProblem(IProblem) method. In this example, the reported problem will be that Zork cannot be resolved or is not a valid superclass and its id is IProblem.SuperclassNotFound.

Excluding warnings using SuppressWarnings

Java 5.0 offers the option to the user to disable compilation warnings relative to a subset of a compilation unit using the annotation java.lang.SuppressWarning.

	@SuppressWarning("unused") public void foo() {
		String s;
	}

Without the annotation, the compiler would complain that the local variable s is never used. With the annotation, the compiler silently ignores this warning locally to the foo method. This enables to keep the warnings in other locations of the same compilation unit or the same project.

The list of tokens that can be used inside an SuppressWarning annotation is:

• all to suppress all warnings
• boxing to suppress warnings relative to boxing/unboxing operations
• cast to suppress warnings relative to cast operations
• dep-ann to suppress warnings relative to deprecated annotation
• deprecation to suppress warnings relative to deprecation
• fallthrough to suppress warnings relative to missing breaks in switch statements
• finally to suppress warnings relative to finally block that don't return
• hiding to suppress warnings relative to locals that hide variable
• incomplete-switch to suppress warnings relative to missing entries in a switch statement (enum case)
• nls to suppress warnings relative to non-nls string literals
• null to suppress warnings relative to null analysis
• restriction to suppress warnings relative to usage of discouraged or forbidden references
• serial to suppress warnings relative to missing serialVersionUID field for a serializable class
• static-access to suppress warnings relative to incorrect static access
• synthetic-access to suppress warnings relative to unoptimized access from inner classes
• unchecked to suppress warnings relative to unchecked operations
• unqualified-field-access to suppress warnings relative to field access unqualified
• unused to suppress warnings relative to unused code