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:
classic
(the standard compiler of JDK 1.1/1.2) –
javac1.1
and
javac1.2
can be used as aliases.modern
(the standard compiler of JDK 1.3/1.4/1.5) –
javac1.3
and
javac1.4
and
javac1.5
can be used as aliases.jikes
(the Jikes
compiler).jvc
(the Command-Line Compiler from Microsoft's SDK
for Java / Visual J++) – microsoft
can be used
as an alias.kjc
(the kopi
compiler).gcj
(the gcj compiler from gcc).sj
(Symantec java compiler) –
symantec
can be used as an alias.extJavac
(run either modern or classic in a JVM of
its own).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.
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 and classic(ver >= 1.2) .
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 . |
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). |
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 the build will continue even if there are compilation errors; 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.Legal values are 1.3 , 1.4 and 1.5
– by default, no -source argument will be used
at all. |
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 the current working directory. |
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.
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 |
<javac srcdir="${src}" destdir="${build}" classpath="xyz.jar" debug="on" />
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.
<javac srcdir="${src}" destdir="${build}" fork="true" />
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.
<javac srcdir="${src}" destdir="${build}" fork="java$$javac.exe" />
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.
<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.
<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.
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 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 will enable Microsoft extensions unless you set the property
build.compiler.jvc.extensions
to false before invoking
<javac>
.
Copyright © 2000-2004 The Apache Software Foundation. All rights Reserved.