Auto-generated GRPC classes aren’t accessible as source folders in EclipseIDE, but exist

by

Summary

The developer was unable to reference generated GRPC classes from the build/generated/sources/proto/main/grpc folder within the Eclipse IDE, despite them being present on the filesystem. Gradle’s compileJava task worked fine. The root cause was a race condition between the Gradle Eclipse plugin configuration and the Eclipse Buildship plugin, where Buildship’s default import logic overwrote the manual source folder additions defined in file.whenMerged. The solution was to use file.beforeMerged to inject source folders into the classpath model before Buildship applied its standard configuration.

Root Cause

The core issue lies in the order of execution during the Eclipse project generation phase via Gradle.

  • Buildship Default Behavior: The Eclipse Buildship plugin (the standard Gradle integration for Eclipse) automatically attempts to detect and configure source folders based on standard conventions (like src/main/java).
  • file.whenMerged Timing: The eclipse.classpath.file.whenMerged hook executes after the classpath model is constructed but before it is written to disk. However, if Buildship runs a “refresh” or “sync” that re-evaluates the project configuration, it can reset the classpath entries, effectively ignoring or deleting the custom entries added via whenMerged.
  • build/generated/sources: Eclipse is generally wary of treating arbitrary build directories as source roots to avoid indexing compiled artifacts or temporary files.
  • The Discrepancy: Why java worked but grpc failed is often due to subtle timing or specific internal filters in Eclipse/Buildship. Sometimes one source folder is accepted while another is rejected if the initial scan fails or if there is a conflict with existing classpath entries. However, the primary failure is the overwriting of the classpath definition.

Why This Happens in Real Systems

This is a classic “Order of Operations” problem common in polyglot build systems and IDE integrations.

  • Imperative vs. Declarative: Gradle is imperative (it runs tasks), while Eclipse expects a declarative project structure (.classpath file). Bridging the gap requires strict control over when the bridge updates the structure.
  • Plugin Conflicts: When you have multiple plugins (like the eclipse plugin and com.diffplug.eclipse) or the IDE itself (Buildship) interacting with the same file, the last one to write wins.
  • State Management: IDEs maintain internal indexes and state. Simply adding a folder to the file system or a text file isn’t enough; the IDE must be told explicitly to “trust” that folder as a source root before it indexes it.

Real-World Impact

  • Blocked Development: Developers cannot write code that imports the generated classes (e.g., import com.billing.BillingServiceGrpc), causing compilation errors in the IDE.
  • False Negatives: The build passes via CLI (./gradlew build), creating a false sense of security, while the developer environment is broken.
  • Tool Distrust: Developers lose faith in the IDE’s Gradle integration, often resorting to manual hacks or switching to IntelliJ IDEA.
  • Inconsistent Environments: If the fix is committed (e.g., the .classpath file), it might work for one user but fail for another depending on their Buildship version or workspace settings.

Example or Code

The developer’s solution effectively beats Buildship to the punch. By using file.beforeMerged, the source folder is added to the classpath model before Buildship’s standard configuration logic is applied.

Here is the correct Gradle configuration snippet:

eclipse {
    classpath {
        file.beforeMerged { cp ->
            // Adding these in beforeMerged ensures they exist in the model
            // before Buildship applies its default detection logic
            cp.entries.add(new org.gradle.plugins.ide.eclipse.model.SourceFolder(
                'build/generated/sources/proto/main/java', null))
            cp.entries.add(new org.gradle.plugins.ide.eclipse.model.SourceFolder(
                'build/generated/sources/proto/main/grpc', null))
        }
    }
}

How Senior Engineers Fix It

Senior engineers approach this by decoupling the “generation” from the “IDE configuration.”

  1. Use the Hook Correctly: Immediately identify if the issue is an overwrite. whenMerged modifies an existing object; beforeMerged ensures the object is initialized with the desired state.
  2. Validate Pathing: Ensure the path strings are relative to the project root and use forward slashes.
  3. Automate the Sync: Ensure the workflow includes ./gradlew cleanEclipse eclipse or a “Refresh Gradle Project” command in the IDE to force a clean regeneration of the metadata files.
  4. Check Buildship Settings: Verify if the “Gradle > Workspace > Automatic Project Synchronization” is interfering. Sometimes disabling auto-sync temporarily allows manual fixes to stick.
  5. Abstract the Config: For multi-module projects, create a shared Gradle convention plugin to apply this Eclipse fix consistently across all modules generating code.

Why Juniors Miss It

  • Assumption of Persistence: Juniors often assume that modifying build.gradle and running a build will automatically update the IDE state. They don’t realize the IDE manages its own metadata files (.classpath, .project) which act as a cache.
  • Ignoring the “Last Write Wins” Rule: They may add the configuration to whenMerged but fail to understand why it gets reverted (Buildship overwrites it).
  • Focus on Code, Not Configuration: Juniors are usually focused on writing Java/GRPC code and view build tools/IDE configuration as “magic” or “plumbing” that shouldn’t need tweaking.
  • Literal Interpretation: Seeing build/generated/sources/... might trigger a mental block because “build folders shouldn’t be source folders,” missing that this is standard practice for generated code.