Javac Task

## 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: 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 differently 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, by setting the compiler attribute, specific to the current `<javac>` task or by using a nested element of any typedeffed or componentdeffed type that implements `org.apache.tools.ant.taskdefs.compilers.CompilerAdapter`. 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 and later) – javac1.3, javac1.4, javac1.5 and javac1.6, javac1.7 (since Ant 1.8.2), javac1.8 (since Ant 1.8.3), javac1.9 (since Ant 1.9.5), javac9 (since Ant 1.9.8) and javac10+ (since Ant 1.10.2) 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 javacX 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 JDK 1.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 your 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.

If your source contains native methods or fields annotated with the `@Native` annotation you can set the nativeheaderdir attribute in order to use the `-h` switch of `javac` to generate the native header files. Note that the logic Ant uses to determine which files to compile does not take native headers into account, i.e. if the `.class` is more recent than the corresponding `.java` file the file will not get compiled even if a native header file generated for it would be outdated.

### Parameters

Attribute | Description | Required
--- | --- | ---
srcdir | Location of the java files. (See the note below.) | Yes, unless nested `<src>` elements or modulesourcepath attribute or corresponding elements are present
destdir | Location to store the class files. | No
includes | Comma- or space-separated list of patterns of files that must be included. | No; defaults to all `.java` files
includesfile | Name of a file. Each line of this file is taken to be an include pattern. | No
excludes | Comma- or space-separated list of patterns of files that must be excluded. | No; defaults to default excludes or none if defaultexcludes is no
excludesfile | Name of a file. Each line of this file is taken to be an exclude pattern. | No
defaultexcludes | Indicates whether default excludes should be used or not (yes|no). | No; defaults to yes
classpath | The classpath to use. | No
sourcepath | The sourcepath to use. To suppress the `sourcepath` switch, use sourcepath=. | No; defaults to srcdir unless nested `<src>` elements are specified
bootclasspath | Location of bootstrap class files. (See below for using the `-X` and `-J-X` parameters for specifying the bootstrap classpath). | 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 | The bootstrapclasspath to use, 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. | No; defaults to off
debug | Indicates whether source should be compiled with debug information. 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; defaults to off
debuglevel | Keyword list to be appended to the `-g` command-line switch. Legal values are none or a comma-separated list of the following keywords: lines, vars, and source. | No; ignored when debug is false or any implementation other than modern, javac1.2 and jikes; by default, nothing will be appended to `-g`
optimize | Indicates whether source should be compiled with optimization. Note that this flag is just ignored by Sun's `javac` since JDK 1.3 (because compile-time optimization is unnecessary). | No; defaults to off
deprecation | Indicates whether source should be compiled with deprecation information. | No; defaults to `off`
verbose | Asks the compiler for verbose output. | No; defaults to 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. 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; defaults to yes, unless `build.sysclasspath` property is set
includeJavaRuntime | Whether to include the default run-time libraries from the executing JVM in the classpath. 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; defaults to no
fork | Whether to execute `javac` using the JDK compiler externally. | No; defaults to no
executable | Complete path to the `javac` executable to use in case of fork is yes. 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; defaults to the compiler of current JDK, ignored if fork is no
memoryInitialSize | The initial size of the memory for the underlying JVM, if `javac` is run externally. (Examples: 83886080, 81920k, or 80m) | No; defaults to the standard JVM memory setting, ignored if fork is no
memoryMaximumSize | The maximum size of the memory for the underlying JVM, if `javac` is run externally; ignored otherwise. (Examples: 83886080, 81920k, or 80m) | No; defaults to the standard JVM memory setting, ignored if fork is no
failonerror | Indicates whether compilation errors will fail the build>. | No; defaults to true
errorProperty | The property to set to true if compilation fails. Since Ant 1.7.1. | No
source | Java language features accepted by compiler, as specified by the `-source` command-line switch. Valid feature versions are 1.3, 1.4, 1.5 or 5, etc. The attribute will be ignored by all implementations prior to javac1.4 (or modern when Ant is not running in a JVM 1.3), 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. | No; by default, no `-source` argument will be used at all unless the magic `ant.build.javac.source` property is set Note that the default value depends on JDK that is running Ant. We highly recommend to always specify this attribute.
target | Generate class files for specific JVM version (cross-compile). | No; by default, no `-target` argument will be used at all unless the magic `ant.build.javac.target` property is set Note that the default value depends on JDK that is running Ant and on source (see Cross-Compilation Options). We highly recommend to always specify this attribute.
compiler | The compiler implementation to use. See the above list of valid compilers. | No; defaults to the value of the `build.compiler` property, if set, or default compiler for the current JDK otherwise
listfiles | Indicates whether the source files to be compiled will be listed. | No; defaults to no
tempdir | Where Ant should place temporary files. This is only used if the task is forked and the command line args length exceeds 4 kB. Since Ant 1.6. | No; default is `java.io.tmpdir`
updatedProperty | The property to set to 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. If set to true (default), 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. Since Ant 1.8, an empty `package-info.class` is created 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 | No
modulesourcepath | Specify where to find input source files for multiple module compilation. since Ant 1.9.7 | Yes, unless srcdir attribute or nested `<src>` elements are present
modulesourcepathref | The modulesourcepath to use, given as reference to a path defined elsewhere. since Ant 1.9.7 | No
upgrademodulepath | Specify the location of modules that replace upgradeable modules in the runtime image. since Ant 1.9.7 | No
upgrademodulepathref | The upgrademodulepath to use, given as reference to a path defined elsewhere. since Ant 1.9.7 | No
nativeheaderdir | Specify where to place generated native header files. Since Ant 1.9.8. | No, ignored when compiling on JDK 7 or earlier
release | Specify the value for the `--release` switch. When set and running on JDK 9+ the source and target attributes as well as the bootclasspath will be ignored. Since Ant 1.9.8. | No, ignored when compiling on JDK 8 or earlier

### Parameters specified as nested elements

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

#### `srcdir`, `classpath`, `sourcepath`, `bootclasspath`, `modulepath`, `modulesourcepath`, `upgrademodulepath` and `extdirs`

`<javac>`'s srcdir, classpath, sourcepath, bootclasspath, extdirs, modulepath, modulesourcepath, and upgrademodulepath attributes are path-like structures and can also be set via nested `<src>` (note the different name!), `<classpath>`, `<sourcepath>`, `<bootclasspath>`, `<extdirs>`, `<modulepath>`, `<modulesourcepath>` and `<upgrademodulepath>` 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
prefix | See Command-line Arguments. Since Ant 1.8. | No
suffix | No
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

#### compilerclasspath

Since Ant 1.8.0

A path-like structure holding the classpath to use when loading the compiler implementation if a custom class has been specified. Doesn't have any effect when using one of the built-in compilers.

#### Any nested element of a type that implements `CompilerAdapter`

Since Ant 1.8.0

If a defined type implements the `CompilerAdapter` interface a nested element of that type can be used as an alternative to the compiler attribute.

### Examples

Compile all `.java` files under the `${src}` directory, and store 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}"
           classpath="xyz.jar"
           debug="on"
           source="1.4"/>

Compile all `.java` files under the `${src}` directory, and store the `.class` files in the `${build}` directory. Java compiler is forked 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="true"
           source="1.2"
           target="1.2"/>

Compile all `.java` files under the `${src}` directory, and store the `.class` files in the `${build}` directory. Java compiler is forked 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}"
           fork="java$$javac.exe"
           source="1.5"/>

Compile `.java` files under the `${src}` directory, and store 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}"
           destdir="${build}"
           includes="mypackage/p1/**,mypackage/p2/**"
           excludes="mypackage/p1/testpackage/**"
           classpath="xyz.jar"
           debug="on"/>

This 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 JVM 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"/>

If you want to activate other compiler options like `lint` you could use the `<compilerarg>` element:

    <javac srcdir="${src.dir}"
           destdir="${classes.dir}"
           classpathref="libraries">
      <compilerarg value="-Xlint"/>
    </javac>

If you want to use a custom CompilerAdapter `org.example.MyAdapter` you can either use the compiler attribute:

    <javac srcdir="${src.dir}"
           destdir="${classes.dir}"
           compiler="org.example.MyAdapter"/>

or a define a type and nest this into the task like in:

    <componentdef classname="org.example.MyAdapter"
                  name="myadapter"/>
    <javac srcdir="${src.dir}"
           destdir="${classes.dir}">
      <myadapter/>
    </javac>

in which case your compiler adapter can support attributes and nested elements of its own.

The following examples demonstrate the use of Java 9+ modules.

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

    <javac srcdir="${src}"
           destdir="${build}"
           includeantruntime="false"
           modulepath="modules"
           source="9"/>

Compile all `.java` files in `gen/classes`, `lin32/classes` and `lin64/classes` in all source modules under the `${src}` directory. Generate 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.

    <javac modulesourcepath="${src}/*/{gen,lin{32,64}}/classes"
           destdir="${build}"
           includeantruntime="false"
           modulepath="modules"
           source="9"/>

### 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 effect 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>`.

### Bootstrap options

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:

    <path id="lib.path.ref">
      <fileset dir="lib" includes="*.jar"/>
    </path>
    <javac srcdir="src" destdir="classes">
      <compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/>
    </javac>

### OpenJDK notes

The OpenJDK project has provided the `javac` compiler as an open source 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:

    <property name="patched.javac.jar"
              location="${my.patched.compiler}/dist/lib/javac.jar"/>

    <presetdef name="patched.javac">
      <javac fork="yes">
        <compilerarg value="-J-Xbootclasspath/p:${patched.javac.jar}"/>
      </javac>
    </presetdef>

    <patched.javac srcdir="src/java" destdir="build/classes"
                   debug="yes"/>

### Note on package-info.java

`package-info.java` files were introduced in Java 5 to allow package level annotations. On compilation, if the `.java` file does not contain runtime annotations, there will be no corresponding `.class` file. Prior 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.

Since Ant 1.8.0, an "empty" `package-info.class` file is created if Ant compiles a `package-info.java` and no `package-info.class` file has been created by the compiler itself.