Javac

Description

Compiles a Java source tree.

The source and destination directory will be recursively scanned for Java source files to compile. Only Java files that have no corresponding .class file or where the class file is older than the .java file will be compiled.

Note: Ant uses only the names of the source and class files to find the classes that need a rebuild. It will not scan the source and therefore will have no knowledge about nested classes, classes that are named different from the source file, and so on. See the <depend> task for dependency checking based on other than just existence/modification times.

When the source files are part of a package, the directory structure of the source tree should follow the package hierarchy.

It is possible to refine the set of files that are being compiled. This can be done with the includes, includesfile, excludes, and excludesfile attributes. With the includes or includesfile attribute, you specify the files you want to have included. The exclude or excludesfile attribute is used to specify the files you want to have excluded. In both cases, the list of files can be specified by either the filename, relative to the directory(s) specified in the srcdir attribute or nested <src> element(s), or by using wildcard patterns. See the section on directory-based tasks, for information on how the inclusion/exclusion of files works, and how to write wildcard patterns.

It is possible to use different compilers. This can be specified by either setting the global build.compiler property, which will affect all <javac> tasks throughout the build, or by setting the compiler attribute, specific to the current <javac> task. Valid values for either the build.compiler property or the compiler attribute are:

The default is javac1.x with x depending on the JDK version you use while you are running Ant. If you wish to use a different compiler interface than those supplied, you can write a class that implements the CompilerAdapter interface (package org.apache.tools.ant.taskdefs.compilers). Supply the full classname in the build.compiler property or the compiler attribute.

The fork attribute overrides the build.compiler property or compiler attribute setting and expects a JDK1.1 or higher to be set in JAVA_HOME.

You can also use the compiler attribute to tell Ant which JDK version it shall assume when it puts together the command line switches - even if you set fork="true". This is useful if you want to run the compiler of JDK 1.1 while you current JDK is 1.2+. If you use compiler="javac1.1" and (for example) depend="true" Ant will use the command line switch -depend instead of -Xdepend.

This task will drop all entries that point to non-existent files/directories from the classpath it passes to the compiler.

Windows Note:When the modern compiler is used in unforked mode on Windows, it locks up the files present in the classpath of the <javac> task, and does not release them. The side effect of this is that you will not be able to delete or move those files later on in the build. The workaround is to fork when invoking the compiler.

Parameters

Attribute Description Required
srcdir Location of the java files. (See the note below.) Yes, unless nested <src> elements are present.
destdir Location to store the class files. No
includes Comma- or space-separated list of files (may be specified using wildcard patterns) that must be included; all .java files are included when omitted. No
includesfile The name of a file that contains a list of files to include (may be specified using wildcard patterns). No
excludes Comma- or space-separated list of files (may be specified using wildcard patterns) that must be excluded; no files (except default excludes) are excluded when omitted. No
excludesfile The name of a file that contains a list of files to exclude (may be specified using wildcard patterns). No
classpath The classpath to use. No
sourcepath The sourcepath to use; defaults to the value of the srcdir attribute (or nested <src> elements). To suppress the sourcepath switch, use sourcepath="". No
bootclasspath Location of bootstrap class files. No
classpathref The classpath to use, given as a reference to a path defined elsewhere. No
sourcepathref The sourcepath to use, given as a reference to a path defined elsewhere. No
bootclasspathref Location of bootstrap class files, given as a reference to a path defined elsewhere. No
extdirs Location of installed extensions. No
encoding Encoding of source files. (Note: gcj doesn't support this option yet.) No
nowarn Indicates whether the -nowarn switch should be passed to the compiler; defaults to off. No
debug Indicates whether source should be compiled with debug information; defaults to off. If set to off, -g:none will be passed on the command line for compilers that support it (for other compilers, no command line argument will be used). If set to true, the value of the debuglevel attribute determines the command line argument. No
debuglevel Keyword list to be appended to the -g command-line switch. This will be ignored by all implementations except modern, classic(ver >= 1.2) and jikes. Legal values are none or a comma-separated list of the following keywords: lines, vars, and source. If debuglevel is not specified, by default, nothing will be appended to -g. If debug is not turned on, this attribute will be ignored. No
optimize Indicates whether source should be compiled with optimization; defaults to off. Note that this flag is just ignored by Sun's javac starting with JDK 1.3 (since compile-time optimization is unnecessary). No
deprecation Indicates whether source should be compiled with deprecation information; defaults to off. No
target Generate class files for specific VM version (e.g., 1.1 or 1.2). Note that the default value depends on the JVM that is running Ant. In particular, if you use JDK 1.4+ the generated classes will not be usable for a 1.1 Java VM unless you explicitly set this attribute to the value 1.1 (which is the default value for JDK 1.1 to 1.3). We highly recommend to always specify this attribute.
A default value for this attribute can be provided using the magic ant.build.javac.target property.
No
verbose Asks the compiler for verbose output; defaults to no. No
depend Enables dependency-tracking for compilers that support this (jikes and classic). No
includeAntRuntime Whether to include the Ant run-time libraries in the classpath; defaults to yes. No
includeJavaRuntime Whether to include the default run-time libraries from the executing VM in the classpath; defaults to no. No
fork Whether to execute javac using the JDK compiler externally; defaults to no. No
executable Complete path to the javac executable to use in case of fork="yes". Defaults to the compiler of the Java version that is currently running Ant. Ignored if fork="no".
Since Ant 1.6 this attribute can also be used to specify the path to the executable when using jikes, jvc, gcj or sj.
No
memoryInitialSize The initial size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m) No
memoryMaximumSize The maximum size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m) No
failonerror Indicates whether compilation errors will fail the build; defaults to true. No
source Value of the -source command-line switch; will be ignored by all implementations prior to javac1.4 (or modern when Ant is not running in a 1.3 VM) and jikes.
If you use this attribute together with jikes, you must make sure that your version of jikes supports the -source switch. By default, no -source argument will be used at all.
Note that the default value depends on the JVM that is running Ant. We highly recommend to always specify this attribute.
A default value for this attribute can be provided using the magic ant.build.javac.source property.
No
compiler The compiler implementation to use. If this attribute is not set, the value of the build.compiler property, if set, will be used. Otherwise, the default compiler for the current VM will be used. (See the above list of valid compilers.) No
listfiles Indicates whether the source files to be compiled will be listed; defaults to no. No
tempdir Where Ant should place temporary files. This is only used if the task is forked and the command line args length exceeds 4k. Since Ant 1.6. No; default is java.io.tmpdir.

Parameters specified as nested elements

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes srcdir) as well as the nested <include>, <exclude> and <patternset> elements.

src, classpath, sourcepath, bootclasspath and extdirs

<javac>'s srcdir, classpath, sourcepath, bootclasspath, and extdirs attributes are path-like structures and can also be set via nested <src>, <classpath>, <sourcepath>, <bootclasspath> and <extdirs> elements, respectively.

compilerarg

You can specify additional command line arguments for the compiler with nested <compilerarg> elements. These elements are specified like Command-line Arguments but have an additional attribute that can be used to enable arguments only if a given compiler implementation will be used.

Attribute Description Required
value See Command-line Arguments. Exactly one of these.
line
file
path
compiler Only pass the specified argument if the chosen compiler implementation matches the value of this attribute. Legal values are the same as those in the above list of valid compilers.) No

Examples

  <javac srcdir="${src}"
         destdir="${build}"
         classpath="xyz.jar"
         debug="on"
         source="1.4"
  />

compiles all .java files under the ${src} directory, and stores the .class files in the ${build} directory. The classpath used includes xyz.jar, and compiling with debug information is on. The source level is 1.4, so you can use assert statements.

  <javac srcdir="${src}"
         destdir="${build}"
         fork="true"
         source="1.2"
         target="1.2"
  />

compiles all .java files under the ${src} directory, and stores the .class files in the ${build} directory. This will fork off the javac compiler using the default javac executable. The source level is 1.2 (similar to 1.1 or 1.3) and the class files should be runnable under JDK 1.2+ as well.

  <javac srcdir="${src}"
         destdir="${build}"
         fork="java$javac.exe"
         source="1.5"
  />

compiles all .java files under the ${src} directory, and stores the .class files in the ${build} directory. This will fork off the javac compiler, using the executable named java$javac.exe. Note that the $ sign needs to be escaped by a second one. The source level is 1.5, so you can use generics.

  <javac srcdir="${src}"
         destdir="${build}"
         includes="mypackage/p1/**,mypackage/p2/**"
         excludes="mypackage/p1/testpackage/**"
         classpath="xyz.jar"
         debug="on"
  />

compiles .java files under the ${src} directory, and stores the .class files in the ${build} directory. The classpath used includes xyz.jar, and debug information is on. Only files under mypackage/p1 and mypackage/p2 are used. All files in and below the mypackage/p1/testpackage directory are excluded from compilation. You didn't specify a source or target level, so the actual values used will depend on which JDK you ran Ant with.

  <javac srcdir="${src}:${src2}"
         destdir="${build}"
         includes="mypackage/p1/**,mypackage/p2/**"
         excludes="mypackage/p1/testpackage/**"
         classpath="xyz.jar"
         debug="on"
  />

is the same as the previous example, with the addition of a second source path, defined by the property src2. This can also be represented using nested <src> elements as follows:

  <javac destdir="${build}"
         classpath="xyz.jar"
         debug="on">
    <src path="${src}"/>
    <src path="${src2}"/>
    <include name="mypackage/p1/**"/>
    <include name="mypackage/p2/**"/>
    <exclude name="mypackage/p1/testpackage/**"/>
  </javac>

If you want to run the javac compiler of a different JDK, you should tell Ant, where to find the compiler and which version of JDK you will be using so it can choose the correct command line switches. The following example executes a JDK 1.1 javac in a new process and uses the correct command line switches even when Ant is running in a Java VM of a different version:

  <javac srcdir="${src}"
         destdir="${build}"
         fork="yes"
         executable="/opt/java/jdk1.1/bin/javac"
         compiler="javac1.1"
  />

Note: If you wish to compile only source files located in certain packages below a common root, use the include/exclude attributes or <include>/<exclude> nested elements to filter for these packages. Do not include part of your package structure in the srcdir attribute (or nested <src> elements), or Ant will recompile your source files every time you run your compile target. See the Ant FAQ for additional information.

If you wish to compile only files explicitly specified and disable javac's default searching mechanism then you can unset the sourcepath attribute:

  <javac sourcepath="" srcdir="${src}"
         destdir="${build}" >
    <include name="**/*.java"/>
    <exclude name="**/Example.java"/>
  </javac>
That way the javac will compile all java source files under "${src}" directory but skip the examples. The compiler will even produce errors if some of the non-example files refers to them.

If you wish to compile with a special JDK (another than the one Ant is currently using), set the executable and fork attribute. Using taskname could show in the log, that these settings are fix.

  <javac srcdir="." 
         destdir="." 
         executable="path-to-java14-home/bin/javac" 
         fork="true"
         taskname="javac1.4" />

Note: If you are using Ant on Windows and a new DOS window pops up for every use of an external compiler, this may be a problem of the JDK you are using. This problem may occur with all JDKs < 1.2.

Jikes Notes

You need Jikes 1.15 or later.

Jikes supports some extra options, which can be set be defining the properties shown below prior to invoking the task. The setting for each property will be in affect for all <javac> tasks throughout the build. The Ant developers are aware that this is ugly and inflexible – expect a better solution in the future. All the options are boolean, and must be set to true or yes to be interpreted as anything other than false. By default, build.compiler.warnings is true, while all others are false.

Property Description Default
build.compiler.emacs Enable emacs-compatible error messages. false
build.compiler.fulldepend Enable full dependency checking; see
the +F switch in the Jikes manual.
false
build.compiler.pedantic Enable pedantic warnings. false
build.compiler.warnings
Deprecated. Use <javac>'s nowarn attribute instead.
Don't disable warning messages. true

Jvc Notes

Jvc will enable Microsoft extensions unless you set the property build.compiler.jvc.extensions to false before invoking <javac>.