Eclipse Java builds: choose ecj or delegate to Maven and Gradle

The decision and constraints

Decide how Eclipse should turn Java source into class files. The two supported patterns are:

• Local ecj compilation: Eclipse uses its own incremental compiler inside the IDE. Maven or Gradle is still used for CI, but not for everyday Eclipse builds.
• Delegated builds: Eclipse asks Maven through m2e, or Gradle through Buildship, to compile, so the IDE runs the same build definition as CI.

Constraints that shape the choice:

• Local iteration speed: ecj is incremental and usually faster.
• Diagnostic fidelity: delegated builds make Eclipse problems match CI compiler output.
• Annotation processors: Lombok, MapStruct, QueryDSL, and similar tools may behave differently under ecj and javac.
• Project size: large multi-module Maven reactors or Gradle builds can make delegated IDE compilation noticeably slower.
• Network and offline access: delegated builds need dependency resolution, so validate with offline flags when appropriate.

Supported options compared

Option	Compiler	Classpath source	Speed	CI parity	Best for
Eclipse incremental build (ecj)	ecj inside Eclipse	Eclipse classpath, often derived from Maven or Gradle metadata	Fast, incremental	Approximate; edge cases can differ	Day-to-day editing
Maven delegated IDE builds	javac via Maven	pom.xml model	Slower per change	High for Maven CI	Teams where Eclipse errors must match Maven
Gradle delegated IDE builds	javac via Gradle	build.gradle or settings.gradle	Slower per change	High for Gradle CI	Teams where Eclipse errors must match Gradle
Hybrid: ecj daily, clean verify before push	ecj for edits; javac for verification	Eclipse plus build file	Fast daily; slower verification	Caught at pre-push check	Most Java teams

Trade-offs to accept

Eclipse-only success is not proof of a clean CI build. ecj and javac have historically differed on some generics, type inference, and annotation-processing edge cases. An error-free Problems view means the code compiled under ecj; it does not guarantee that Maven or Gradle will agree.

Delegation removes most classpath drift because m2e typically derives the Eclipse classpath from the Maven model, and Buildship does the equivalent for Gradle. The cost is slower feedback: every save or rebuild may trigger a full tool invocation instead of an incremental IDE compile. In large multi-module projects, delegate only the modules where diagnostic fidelity matters most.

Annotation processors are the main risk area. Lombok and some MapStruct or QueryDSL setups need explicit Eclipse configuration, and delegated builds may process annotations differently from ecj. Verify processor behavior in both modes before relying on generated code.

Concrete validation procedure

Use this loop to confirm that Eclipse and your command-line build see the same errors.

1. Confirm the JDK and compliance level

Check which JDK Eclipse runs on through eclipse.ini (the -vm argument) and the Installed JREs preference. Then compare the Java compiler compliance level in Eclipse with the source, target, or release values in your Maven compiler plugin or Gradle Java compile configuration. A mismatched JDK changes available APIs and compiler behavior.

2. Introduce a deliberate compile error

In a scratch class, call a method that does not exist:

public class CompileParityCheck {
    public static void main(String[] args) {
        undefinedMethod();
    }
}

Save the file and note the message in the Eclipse Problems view. Then run the same compilation from the command line.

Where: terminal outside Eclipse, or the Eclipse embedded terminal. Permissions: ordinary user read/write access to the project; no elevated privileges required.

Maven:

cd 
mvn compile -o

Gradle:

cd 
./gradlew compileJava --offline

Expected check: the command-line compiler reports an error for the same class and method. Risks: -o or --offline fails if dependencies are not already in the local repository. Remove the offline flag for the first run if needed.

3. Compare the error sets

Confirm that the Eclipse Problems view text and the Maven or Gradle output describe the same failure. Delete the scratch class, rebuild, and verify both views are clean.

4. Toggle delegation and rebuild

Turn IDE build delegation on in your Eclipse build-tool preferences, rebuild the project, and confirm the same error set appears. Turn it off again and confirm Eclipse returns to incremental ecj compilation. Exact menu labels vary by Eclipse release, so verify the path in your installed version before documenting it for a team.

5. Run a clean verification before pushing

Maven:

cd 
mvn clean verify -o

Gradle:

cd 
./gradlew clean build --offline

Expected check: no compile errors appear that Eclipse did not already report. If CI finds errors Eclipse missed, treat the Eclipse build as a local convenience only and fix the code before committing.

Limitations

• This guidance covers standard Java compilation. It does not address OSGi, Tycho, or non-Java language tooling.
• Preference names and delegation options can change between Eclipse releases; verify against your installed version.
• Delegated builds require a working headless Maven or Gradle invocation. In restricted networks, configure local repositories or use offline flags when validating.
• Large multi-module reactors can make delegated IDE builds slow; consider per-project delegation only where fidelity matters most.

Reverting a delegation change

If delegation slows the IDE too much, open the same build-tool preference used to enable it, clear the delegation option, and run Project > Clean. Eclipse returns to ecj incremental compilation; continue using the command-line clean verify as your pre-push gate.