Apache Ant User Manual

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 therefor will have no knowledge about nested classes, classes that are named different from the source file and so on.

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/copied. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.

It is possible to use different compilers. This can be selected with the "build.compiler" property. Here are the choices:-

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) - javac1.3 and javac1.4 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)

For JDK 1.1/1.2, classic is the default. For JDK 1.3/1.4, modern is the default. If you wish to use a different compiler interface than those supplied, write a class that implements the CompilerAdapter interface (package org.apache.tools.ant.taskdefs.compilers). Supply the full classname in the "build.compiler" property.

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

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

Parameters

Attribute	Description	Required
srcdir	location of the java files. (See Notes at the end)	Yes, unless nested `<src>` elements are present.
destdir	location to store the class files.	No
includes	comma-separated list of patterns of files that must be included; all files are included when omitted.	No
includesfile	the name of a file that contains include patterns.	No
excludes	comma-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted.	No
excludesfile	the name of a file that contains exclude patterns.	No
defaultexcludes	indicates whether default excludes should be used (`yes` \| `no`); default excludes are used when omitted.	No
classpath	the classpath to use.	No
bootclasspath	location of bootstrap class files.	No
classpathref	the classpath 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. (gcj doesn't support this option yet)	No
nowarn	indicates whether -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`.	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`).	No
verbose	asks the compiler for verbose output.	No
depend	enables dependency-tracking for compilers that support this (jikes and classic)	No
includeAntRuntime	whether to include the Ant run-time libraries; defaults to `yes`.	No
includeJavaRuntime	whether to include the default run-time libraries from the executing VM; defaults to `no`.	No
fork	whether to execute Javac using the JDK compiler externally; defaults to `no`. You can also give a complete path to the javac executable to use instead of `yes`, which would run the compiler of the Java vesrion that is currently running Ant.	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 except `modern`, legal values are "1.3" and "1.4" - by default, no `-source` argument will be used at all.	No
debuglevel	Keyword list to be appended to the `-g` command line switch. This will be ignored by all implementations except `modern`, legal values are "none" or a comma separated list of the following keywords. Valid keywords are "lines", "vars" and "source" - if debuglevel is not specified, by default, nothing will be appended to `-g`	No

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`, `bootclasspath` and `extdirs`

Javac's srcdir, classpath, bootclasspath and extdirs attributes are path-like structures and can also be set via nested <src>, <classpath>, <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 here	Exactly one of these.
line
file
path
implementation	Only use this argument if the chosen implementation matches this attribute. Possible choices are the same as those of the build.compiler property.	No.

Examples

  <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 contains xyz.jar, and 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 contains xyz.jar, and debug information is on. Only files under mypackage/p1 and mypackage/p2 are used. Files in 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>

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.

Note: If you wish to compile only source-files located in some packages below a common root you should not include these packages in the srcdir-attribute. Use include/exclude-attributes or elements to filter for these packages. If you include part of your package-structure inside the srcdir-attribute (or nested src-elements) Ant will start to recompile your sources every time you call it.

Jikes Notes

Jikes supports some extra options, which can be set be defining properties prior to invoking the task. 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"

build.compiler.emacs	Enable emacs compatible error messages
build.compiler.warnings This property has been deprecated, use the nowarn attribute instead	don't disable warning messages
build.compiler.pedantic	enable pedantic warnings
build.compiler.fulldepend	enable full dependency checking, "+F" in the jikes manual.