Compiling Java with Ant

The smallest useful build file compiles one module. It sets every attribute that should never be left to a default:

Running ant compile twice shows the first idea of Ant compilation: the first run compiles the four files and lists them (because of listfiles), the second finds the class files newer than the sources and does nothing.

javap confirms what release and debug did to the class files: major version 65 is Java 21, and the SourceFile and LineNumberTable attributes are present.

Source: Apache Ant manual: Javac task

<javac> is a directory-based task. It scans the source directory (the srcdir attribute or one or more nested <src> elements), applies the includes, excludes and default excludes, and maps every X.java to destdir/X.class in the same package directory. A source file whose class file is missing, or older than the source, goes on the list; everything else is skipped. The list is then given to one javac invocation (in the same JVM unless fork is set), and javac may compile further classes it finds through the source path, which Ant sets to the source directories by default.

The consequences are the same in every build:

Source: Apache Ant manual: Javac task, srcdir note

The tables list every attribute of the 1.10.18 <javac> task; the "since" column names the release only where the manual gives one. Attributes that take a path (classpath, sourcepath, bootclasspath, extdirs, modulepath, modulesourcepath, upgrademodulepath and srcdir) can also be written as nested <classpath>, <sourcepath>, <bootclasspath>, <extdirs>, <modulepath>, <modulesourcepath>, <upgrademodulepath> and <src> elements (note that srcdir becomes <src>), and each has a ...ref variant that takes the id of a path defined elsewhere.

The task also accepts nested <include>, <exclude> and <patternset> elements, nested <compilerarg> elements for extra compiler switches, <compilerclasspath> for loading a custom compiler adapter, and a nested element of any defined type that implements CompilerAdapter. There is no proc, parameters or lint attribute: those switches go through <compilerarg>, as the sections below show.

Source: Apache Ant manual: Javac task

source and target are the historical pair of switches, and they have a trap: the compiler of the JDK that runs Ant compiles against its own API, not against the API of the release named. A class compiled with source="21" target="21" on JDK 26 can call a method that exists only in JDK 26 and fail at run time on Java 21. release closes the trap because javac --release also restricts the compiled API to that of the chosen release. javac says so itself when the old pair is used:

With release set, source and target are not used at all, and Ant reports it:

The JDK itself decides which releases --release accepts. JDK 26 no longer supports 7, and 8 still works but is obsolete; compiling the records of tidepool for 8 also fails because records need Java 16:

Some build files cannot be edited, for example those inherited from an old project. For them Ant offers two properties that supply defaults for the source and target attributes when the attributes are not set (the properties are ignored when the attributes are present): ant.build.javac.source and ant.build.javac.target, both since Ant 1.7. They are passed with -D or set in a properties file, and they do not fix the trap above, because they feed -source and -target, not --release.

release needs Ant 1.9.8 or later and JDK 9 or later to run. In a Maven build the same decision is maven.compiler.release (Compiling & Toolchains); in Gradle it is options.release or a toolchain (Java Projects, Toolchains).

Source: Apache Ant manual: Properties controlling javac

Source: JDK 26 javac: --release

By default <javac> puts the Ant libraries on the class path of the compilation, so that a build file that compiles custom tasks does not need to name ant.jar. It also makes the result depend on which Ant is installed. Ant 1.10.18 warns when the attribute is left out:

Set includeantruntime="false" on every <javac>. The one case that needs true is a task that compiles a class that extends Ant classes, for example a custom task such as the <checkstations> task of Writing Custom Tasks; there, name the Ant jar on the class path instead (${ant.core.lib} is the built-in property that points at it). A build file can also set the build.sysclasspath property, which decides where the Ant run-time class path goes: last, the default the warning names, appends it after the build’s own class path, first puts it before, only uses it alone, and ignore leaves it out.

Source: Apache Ant manual: Javac task and build.sysclasspath

tidepool has three modules, and each depends on the previous one. Ant has no project model, so the dependency between modules is a class path pointing at the previous module’s output directory, and the order is the order of the targets' depends. The same file shows the nested <compilerarg> and a processor path for the picocli annotation processor (explained in the next sections):

Three things in this build file are classic sources of bugs:

Source: Apache Ant manual: Javac task

The compiler attribute (or the build.compiler property, which affects every <javac> in the build) selects the implementation of the CompilerAdapter interface that builds the command line. The values the manual lists:

With nothing set, the default is the javacX adapter that matches the JDK running Ant, which is why release="21" works on JDK 26 without a compiler attribute. The old values of the table (jikes, jvc, kjc, gcj, sj, classic) are listed for completeness; their compilers are not maintained, and no current build needs them. A value that is neither a known name nor a class fails with a message about the class:

javac10+ and extJavac both worked on this installation; the second one starts a separate JVM, as the manual says, and the build output is the same.

The compiler attribute is also how the command-line switches are chosen when fork is set: compiler="javac1.1" with a forked JDK 1.1 javac makes Ant write -depend instead of -Xdepend. Today the useful part is the reverse, fork.

Source: Apache Ant manual: Javac task, compiler values

By default <javac> calls the compiler API inside the JVM that runs Ant. fork="true" starts the javac executable of the JDK instead, or the one named by executable. Forking is the way to compile with a JDK other than the one running Ant, to give the compiler more memory (memoryMaximumSize), and to avoid the file locking the manual describes for Windows (an unforked modern compiler keeps the class path JARs open, so a later delete or move of them fails). The -v flag shows the command that is built; the arguments below also show the defaults Ant chooses: the class path is the output directory, the source path is the srcdir, and -g:none appears because debug is off.

The first four lines also explain why a file was compiled: with -v, Ant says which class file did not exist or was older. A wrong executable fails early with a short message:

When the compile is expected to use another installed JDK, prefer a build property such as jdk.home (set from the JAVA_HOME environment variable or from a properties file) over a hard-coded path, and read the build’s JDK from ant -version and ant -diagnostics (Running Ant). In Maven and Gradle the same need is met by toolchains, which select the JDK by version and vendor instead of by path.

Source: Apache Ant manual: Javac task

Without deprecation, javac prints only two summary lines for a deprecated API. The deprecation attribute and the -Xlint switches give the details. The next experiments compile a class that calls new Date(126, 0, 1):

Lint categories and "warnings are errors" go through <compilerarg>; the -Werror switch turns the build into a gate:

A compile error fails the build with Compile failed; see the compiler error output for details., because failonerror defaults to true. Set failonerror="false" together with errorProperty when the build must go on, for example to collect all failures before reporting; updatedProperty is set only when a compile took place and succeeded, which is why it stays unset below:

Source: Apache Ant manual: Javac task

Annotation processors need three decisions in an Ant build: where the processor JARs are, whether processing is switched on, and what options it receives. The <javac> task has no attribute for them; all three go through <compilerarg>.

The tidepool CLI uses picocli-codegen, a processor that writes GraalVM native-image configuration for the @Command class. The build file above passes it a processor path and the project option the processor requires:

Two nested elements are needed for a path, because -processorpath and its value are separate arguments; pathref converts a <path> to the platform’s path string. After the build the processor’s output is next to the class files:

A processor that is only on the compile class path is a trap on a recent JDK. Since JDK 23 javac no longer runs processors that it discovers on the class path unless processing is requested explicitly: the JDK 26 javac manual says that without -proc annotation processing happens only if another option configures it (such as -processorpath or -processor). The experiment compiles all seven tidepool sources with picocli-codegen on the class path and counts the files below META-INF:

Compilation succeeded in all three runs and printed nothing about the skipped processor, so the failure shows up later, as a missing generated class or a missing configuration file. The fix is either a processor path (preferred: it keeps processors off the application class path) or -proc:full. -proc:only runs processors without compiling, which is useful to generate sources into a directory with -s before a second compile. For the processor itself, picocli documents the project option and how to enable the processor.

The equivalents are annotationProcessorPaths in the Maven compiler plugin (Compiling & Toolchains) and the annotationProcessor configuration in Gradle (Java Projects); both keep processors off the compile class path by construction.

Source: JDK 26 javac: -proc and --processor-path

Source: picocli: Annotation Processor

Ant supports the Java module system from 1.9.7. There are two shapes.

A single module. A module-info.java at the root of the source directory is compiled like any other file; add modulepath when it requires modules that are not in the JDK. This build compiles tidepool-model as the module io.tidepool.model:

Several modules in one go. With modulesourcepath, one <javac> compiles a set of modules from a layout of one directory per module, and writes one output directory per module under destdir. The * token in the manual’s example stands for the module name. Here io.tidepool.engine requires io.tidepool.model (transitively) and org.apache.commons.csv, and the CSV JAR goes on the modulepath:

Without the modulepath, the compile fails at the requires line:

Two further points. A JAR on the module path becomes a named module (an automatic module if it has no module-info), while the same JAR on the classpath is in the unnamed module and invisible to requires; an Ant build that mixes both must keep the paths apart. And upgrademodulepath is for the rare case of replacing an upgradeable JDK module. Packaging the compiled modules into a modular JAR or a runtime image is on Packaging Archives.

Source: Apache Ant manual: Javac task, module examples

A class with a native method needs a C header with the JNI function prototype. javac -h generates it while compiling, and the Ant attribute nativeheaderdir (Ant 1.9.8) passes the directory:

The header is written only when the class is compiled. Ant decides what to compile from class file timestamps and does not look at native headers, so a deleted header is not regenerated while the class file is newer than the source; delete the class (or the whole output directory) to force it. The header above also contains the MAX_CONSTITUENTS constant: javac -h writes the constants of the class as #define lines.

The older <javah> task generated the same headers from compiled classes. It was deprecated with Java 9 and removed from the JDK in Java 10, and Ant 1.10.2 made it fail with an explicit message rather than a missing executable:

<rmic> has the same history: rmic was deprecated in Java 13 and removed in Java 15, and the Ant task fails on Java 15 and later unless you give it an explicit executable of an older JDK:

Modern RMI needs no stubs (dynamic proxies replace them since Java 5), so the answer for a build is to delete the <rmic> call. The -iiop and -idl options (CORBA) fail from Java 11, because that release removed the CORBA packages; the manual states that Ant 1.10.3 and later fail on them.

Source: Apache Ant manual: Javah task

Source: Apache Ant manual: Rmic task

Timestamps catch a changed source but not what it means for its callers. Suppose Client calls Api.twice(int), and Api is changed to return a String. Only Api.java is newer, so a plain <javac> recompiles only that file, Client.class stays, and the build succeeds. The failure comes at run time:

The <depend> task reads the class references encoded in the existing class files (it does not parse the sources), builds the inverse "affected by" relation, and deletes the class files of every class that depends on a class that is out of date. The following <javac> then recompiles them, and the compiler reports the real problem. cache stores the dependency information between runs, and closure="true" follows indirect dependencies too (A depends on B depends on C):

The attributes of <depend> are srcdir (required, a path of source directories), destdir (the class files to analyse; defaults to srcdir), cache, closure, dump (write the dependencies to the debug log), classpath (jars and classes to also check against, which should not contain JARs that never change, such as the JDK or third-party libraries) and warnOnRmiStubs. It forms an implicit fileset, so <include> and <exclude> work as in <javac>. The task is part of ant.jar.

Its limits matter. It cannot see a class relationship that the compiler removed, such as the inlined value of a public static final constant (changing DEBUG in a Constants class is not picked up by the classes that read it), it cannot relate a non-public class to a source file, and it costs time on large trees. A clean build on CI, or the incremental compilation of Maven and Gradle, is the more robust answer; Gradle tracks class-level dependencies by itself, and the Maven compiler plugin recompiles the module when it detects a change. See Build Automation Fundamentals for the general picture. The depend attribute of <javac> is not a substitute: the manual says it only works for the jikes and classic compilers.

Source: Apache Ant manual: Depend task

Property resource bundles were ISO-8859-1 only until Java 9 (which made them UTF-8, JEP 226), so files kept in another encoding had to be converted with the JDK tool native2ascii. That tool is gone from the JDK: JDK 26 has no native2ascii executable. Ant’s task works anyway because, since Ant 1.9.8, the builtin converter is Ant’s own implementation. It converts a directory of files from a native encoding to ASCII with \uXXXX escapes (the reverse attribute converts back, supported by the sun and builtin converters):

The reverse="true" run on build/i18n with the same encoding gave back the original text. The attributes are src (default basedir), dest (required), encoding, ext (rename the output files), reverse, implementation (default, sun, kaffe or builtin), the usual includes/excludes set and an optional nested <mapper>; if src and dest are the same directory, ext or a mapper is required. Use it when a legacy tool chain needs pure-ASCII properties files; for new code keep the files in UTF-8.

Source: Apache Ant manual: Native2Ascii task

Source: JEP 226: UTF-8 Property Resource Bundles

Compiling JSP pages is a different compile with different tools. The core Ant <jspc> task is deprecated: the manual says it was tested only against Tomcat 4.x, has known problems with Tomcat 5.x that will not be fixed, and recommends the task that Tomcat ships instead. The Jasper JspC task, its Ant integration and the production setting are in Jasper Configuration & Precompilation.

Source: Apache Ant manual: Jspc task

More on the other two tools is on Compiling & Toolchains and Java Projects; the side-by-side verdict is on Comparing Ant, Maven & Gradle.

Java Development with Ant (Ant 1.5, 2002) compiles with <javac srcdir destdir classpath> and does not mention includeantruntime, release, modulepath or nativeheaderdir, which came with Ant 1.8, 1.9.8 and 1.9.7. Its JNI chapter relies on <javah>, which fails on Java 10 and later (use nativeheaderdir); its RMI material relies on <rmic>, which fails on Java 15 and later; its source="1.4" examples fail on a current compiler, which rejects releases older than 8 (and flags 8 as obsolete); its JSP precompilation with <jspc> is Tomcat-4-only and deprecated; and the jikes compiler it recommends for speed is no longer maintained. The section’s bibliography (Bibliography) gives the publisher page of the book.

Rewriting such a build is covered on Deprecations & Migration.