How does incremental Java compilation work?

I’m looking for an explanation of how Gradle does incremental compilation of Java code.

Background: I have a tiny little test project where it works fine: no changes, no rebuild; change the source, Gradle recompiles. And I have an experimental Gradle script for building our large, hairy production source tree where it does not work: if I change the source code, Gradle does not recompile. (It does recompile if I delete .class files.)

Before I try to strip this down to a reproducible example and report a bug, I need to understand how Gradle does incremental compilation. Perhaps there is a subtle error in my build script causing this. But I can’t find anything in the documentation – the user manual contains two occurrences of the word “incremental” with no concrete explanation.

Oh yeah: I did find GRADLE-66, so I have a rough idea of what Gradle does NOT do: it does not parse the source code, it does not use jmake, it does not incorporate Eclipse’s compiler, and it does not use Ant’s task. Am I right so far?

Gradle does (currently) use Ant’s javac task; however, by default it won’t do incremental compilation. It’s important to distinguish Gradle’s incremental build feature from incremental compilation. The former is a generic feature that works for all tasks (if they describe their inputs and outputs), and results in only a subset of tasks being executed for a particular build. However, the tasks that are executed are fully executed. Incremental compilation is something different; it’s a special compilation feature that only compiles a subset of the files passed to the compilation task.

Gradle implements incremental compilation with Ant’s depend task. By default, this feature isn’t turned on because it isn’t very reliable. For a well-factored multi-project build, Gradle’s incremental build feature can still save a lot of compilation time, because typically only some of the projects will have to be recompiled. In other words, some projects will be fully recompiled, and others not at all.