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

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.

The working directory for a forked executable (if any) is the
project's base directory.

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.

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, unless
build.sysclasspath is set.
It is usually best to set this to false so the script's behavior is not
sensitive to the environment in which it is run.

No

includeJavaRuntime

Whether to include the default run-time
libraries from the executing VM in the classpath;
defaults to no.Note: In some setups the run-time libraries may be part
of the "Ant run-time libraries" so you may need to explicitly
set includeAntRuntime to false to ensure that the Java
run-time libraries are not included.

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)

The property to set (to the value "true") if compilation fails.
Since Ant 1.7.1.

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), gcj and jikes.
If you use this attribute together with gcj
or jikes, you must make sure that your version
supports the -source (or -fsource for
gcj)
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.

updatedProperty

The property to set (to the value "true")
if compilation has taken place
and has been successful.
Since Ant 1.7.1.

No

includeDestClasses

This attribute controls whether to include the
destination classes directory in the classpath
given to the compiler.
The default value of this is "true" and this
means that previously compiled classes are on
the classpath for the compiler. This means that "greedy" compilers
will not recompile dependent classes that are already compiled.
In general this is a good thing as it stops the compiler
for doing unnecessary work. However, for some edge cases,
involving generics, the javac compiler
needs to compile the dependent classes to get the generics
information. One example is documented in the bug report:
Bug 40776 - a problem compiling a Java 5 project with generics.
Setting the attribute to "false" will cause the compiler
to recompile dependent classes.
Since Ant 1.7.1.

No - default is "true"

createMissingPackageInfoClass

Some package level annotations in package-info.java
files don't create any package-info.class files so
Ant would recompile the same file every time.
Starting with Ant 1.8 Ant will create an
empty package-info.class for
each package-info.java if there isn't one created
by the compiler.
In some setups this additional class causes problems and it can
be suppressed by setting this attribute to "false".
Since Ant 1.8.3.

No - default is "true"

modulepath

Specify where to find application modules. A list of directories of modules, module files or exploded modules.
since Ant 1.9.7

No

modulepathref

The modulepath to use, given as reference to a PATH defined elsewhere.
since Ant 1.9.7

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.

Examples

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.

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.

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.

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.

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:

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:

compiles all .java files in a single module under the ${src} directory,
and stores the .class files in the ${build} directory. The compilation uses
application modules located in modules folder.The source level is 9 to enable modules.

compiles all .java files in gen/classes, lin32/classes and
lin64/classes in all source modules under the ${src} directory.
Generates module directories in the ${build} directory. Each generated module directory under
the ${build} directory contains .class files from corresponding source module.
The * is a token representing the name of any of the modules in the compilation module set.
The { ... , ... } express alternates for expansion.
The compilation uses application modules located in modules folder.The source level is
9 to enable modules.

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.

Jvc Notes

The Sun javac compiler has a bootclasspath command
line option - this corresponds to the "bootclasspath" attribute/element
of the <javac> task. The Sun compiler also allows more
control over the boot classpath using the -X and -J-X attributes.
One can set these by using the <compilerarg>. Since Ant 1.6.0,
there is a shortcut to convert path references to strings that
can by used in an OS independent fashion (see
pathshortcut). For example:

OpenJDK Notes

The openjdk
project has provided the javac
compiler
as an opensource project. The output of this project is a
javac.jar which contains the javac compiler.
This compiler may be used with the <javac> task with
the use of a -Xbootclasspath/p java argument. The argument needs
to be given to the runtime system of the javac executable, so it needs
to be prepended with a "-J". For example:

Note on package-info.java

package-info.java files were introduced in Java5 to
allow package level annotations. On compilation, if the java file
does not contain runtime annotations, there will be no .class file
for the java file. Up to Ant 1.7.1, when the <javac>
task is run again, the
task will try to compile the package-info java files again.

With Ant 1.7.1 a different kind of logic was introduced that
involved the timestamp of the directory that would normally
contain the .class file. This logic turned out to lead to Ant not
recompiling package-info.java in certain setup.

Starting with Ant 1.8.0 Ant will create
"empty" package-info.class files if it compiles
a package-info.java and
no package-info.class file has been created by the
compiler itself.