gnodet commented on PR #1123: URL: https://github.com/apache/maven-compiler-plugin/pull/1123#issuecomment-5876661640
Thanks for the detailed review — you're right that 4.x is genuinely more incremental than 3.x, and that distinction is worth acknowledging. **3.x behavior** In 3.x, `useIncrementalCompilation=true` (the default) was all-or-nothing: the plugin detected *whether* something changed, then always recompiled *all* sources. Five triggers were checked: immutable output, dependency JAR change, source mtime change, input file tree change (added/removed files), or a prior-execution overlap in the same session. Any trigger → recompile everything. `useIncrementalCompilation=false` was the per-file mode: `StaleSourceScanner` compared each `.java` mtime against its corresponding `.class` mtime, and only stale files were passed to javac. No dependency tracking, no stale output cleanup on deletion (`Foo.class` would linger after `Foo.java` was deleted). Hence the "not recommended" label. **4.x behavior** 4.x introduces a richer model. The default configuration is determined by `incrementalCompilationConfiguration()` + `amendincrementalCompilation()`: - With annotation processors (or Java < 23): `OPTIONS, DEPENDENCIES, SOURCES, REBUILD_ON_ADD, REBUILD_ON_CHANGE` — any modification triggers a full rebuild of all sources. Safe, equivalent in correctness to 3.x `true`. - Java ≥ 23, no annotation processors: `OPTIONS, DEPENDENCIES, SOURCES` — when only existing source file *contents* change (no additions, no removals, no dependency/option change), only the modified files are recompiled (partial build). The output directory is added to the classpath so javac can resolve unchanged classes. Note: the 4.x mapping of the legacy `useIncrementalCompilation=true` is `DEPENDENCIES, SOURCES, REBUILD_ON_ADD` — which adds a full rebuild on *file addition*, but still allows partial builds on pure modifications. **The correctness concern** The partial-build path carries the same risk as 3.x `false`: if you change a method signature in `Foo.java`, only `Foo.java` is recompiled. `Bar.java` (which calls `Foo`) is left with a potentially stale `.class`. At runtime this can produce `NoSuchMethodError` or similar. The plugin explicitly documents this limitation in `IncrementalBuild.Limitations`: *"the current compiler-plugin does not detect structural changes other than file addition or removal."* This also raises a question about whether the default for Java ≥ 23 / no-processor projects should include `rebuild-on-change` for correctness — but that is a separate discussion from this PR. **What this PR documents** The Javadoc clarification here is accurate: `incrementalCompilation` selects a *change-detection strategy*, not a dependency-based recompiler. No mode in 3.x or 4.x recompiles changed classes together with their transitive dependents. We also updated the disclaimer to remove a mention of `modules` that was inaccurate — it implied a delegation to javac that is not yet implemented (when `MODULES` is active, `sourceFiles` is left empty and compilation is skipped entirely). _This comment was generated by an AI agent, Hermès on behalf of @gnodet._ <!-- reviewer: gnodet-bot --> -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
