Gradle Project Source Code: Where Should It Go?

• ⚠️ Putting Java code outside src/main/java causes Gradle build failures.
• 🧠 Eclipse Buildship plugin finds the Gradle structure automatically if src/main/java is used.
• 🛠️ Changing default source sets in Gradle means you must set this up clearly in build.gradle.
• 📉 Changing .classpath files by hand creates conflicts when syncing Eclipse projects.
• 🔁 Refreshing a Gradle project in Eclipse fixes most import or recognition problems.

Setting up a Gradle-based Java project in Eclipse is simple if you follow Gradle’s standard project structure. Developers who do not follow these rules often run into problems in their IDEs and builds. This guide shows you how to set up folders correctly. We will focus on the src/main/java rule. We will also show how Eclipse best recognizes and works with the Gradle layout. Our aim is to help you stop build errors, cut down setup time, and make development smoother with Gradle and Eclipse.

Why Gradle Project Structure Matters

Gradle uses "convention over configuration." This means it expects your code, files, and tests to be in certain places. When you put files where they should be, you get simpler setup, faster builds, and smooth connection with IDEs like Eclipse.

For Java projects, this means your main code should be under src/main/java. Your tests go in src/test/java. The more you follow these rules, the less you will need to set up your build. And you will be less likely to have Eclipse integration issues.

The structure directly affects how Gradle compiles your code, puts your application together, and runs your tests. What's more, plugins like Eclipse's Buildship need this structure to set up your project correctly in the workspace.

Standard Gradle Directory Layout

Here is the default folder layout for the java plugin in Gradle:

your-project/
├── build.gradle
├── settings.gradle
└── src
    ├── main
    │   ├── java
    │   └── resources
    └── test
        ├── java
        └── resources

Let’s look at each part:

• src/main/java
  This holds the main Java source files for your application. Gradle automatically compiles these and puts them into your main application package.

• src/main/resources
  This contains files that are not code. Examples are .properties, XMLs, YAML files, or any settings files your application needs when it runs. These files are put into the build output with your compiled code.

• src/test/java
  Test source code goes here (for example, JUnit or TestNG test classes). This is kept separate. This helps make sure test code does not mix with main code. It also makes things clearer and separates different parts of your project.

• src/test/resources
  These are files used for testing. Examples are fake data, settings just for tests, or dummy files.

Following this structure helps tools like Gradle, Eclipse, and CI systems know what is part of your app’s main features. They also know what is only used in tests or when the app runs.

Eclipse Gradle Java Integration

Eclipse uses the Buildship plugin to work with Gradle. When you bring a project into Eclipse with Buildship, it reads your build.gradle file. Then it sets up your Eclipse workspace with the right classpaths, source folders, and project settings.

How it works:

1. Eclipse reads the build.gradle file.
2. It finds source sets like src/main/java and adds them to the Java Build Path.
3. It makes .classpath and .project files automatically.
4. The project is linked up and ready for work.

✅ Pro Tip: Always link your Gradle project after changing build.gradle or adding new folders.

To refresh your Gradle project in Eclipse:

• Right-click on the project.
• Choose Gradle → Refresh Gradle Project.

This makes sure the IDE shows the most recent Gradle settings.

Setting up build.gradle for Source Sets

Gradle expects the default layout. But you can change your source sets in the build.gradle file.

Here is an example of setting source sets clearly:

sourceSets {
    main {
        java {
            srcDirs = ['src/main/java']
        }
    }
    test {
        java {
            srcDirs = ['src/test/java']
        }
    }
}

By doing this, even folder structures that are not standard will work with Gradle’s build process. That said, using these settings when you already follow the standard layout might not be needed. But they do help show what the project is for. They are also very useful in big or complex projects.

In addition, make sure the needed plugins are listed:

plugins {
    id 'java'
    id 'eclipse'
}

The eclipse plugin makes the correct Eclipse files (.project and .classpath) based on your Gradle settings. This makes sure everything matches up.

Common Structure Mistakes to Avoid

When setting up your Gradle project, do not make these common errors:

• Putting Java classes directly in src/
  Gradle will not find code that is not in src/main/java or the set source folder. This causes build errors, like "package does not exist."

• Placing test files in src/main/java
  Mixing test and main code makes builds bigger. It can also cause test setup to leak into your main project.

• Forgetting to refresh after changes
  Adding new source folders needs a project link. If you do not do this, Eclipse will not recognize them. It will mark files as "not on the build path."

• Changing .classpath files by hand
  Gradle makes this file. It is rewritten when you link projects. Changing it by hand can cause issues. Do not do this.

Let Gradle and Eclipse handle the build setup files. This helps keep things the same, especially when many people work on projects together.

Difference Between src/main/java and src/test/java

These folders are split to keep different concerns separate.

• src/main/java:
  Here is where you write the core logic of your application. This includes service classes, models, and helper classes. This is the code that goes to users when the app is live.

• src/test/java:
  This folder is for unit and integration tests. These are usually JUnit or other test frameworks. It might have fake data, checks, and tools just for tests.

Benefits of this split:

• Smaller files for release (test code is not included).
• Clearer code setup.
• Faster build times.
• Easier setup for CI systems that run tests separately from builds.

This layout also lets you have test-specific setups that are separate from the main project's needs.

Importing and Syncing Gradle Projects in Eclipse

Setting up your Gradle Java project in Eclipse the right way is important for smooth work. Follow these steps for the correct setup:

1. Open Eclipse.
2. Go to File > Import > Gradle > Existing Gradle Project.
3. Pick the main project folder that has the build.gradle file.
4. Finish the import process. Eclipse and Buildship will handle the structure.

If you make changes later (for example, adding a new source folder, changing plugin versions), go back to your project:

• Right-click → Gradle → Refresh Gradle Project.

This updates the .classpath and other details. Eclipse will now show your updated Gradle settings.

Customizing Source Folder Structure

Gradle lets you be flexible with your source layout. You can use custom source sets. You should use this carefully, especially in older or modular applications.

For example:

sourceSets {
    main {
        java {
            srcDirs = ['app/src']
        }
    }
}

In big or non-standard structures, this method keeps things tidy. It also lets Gradle know where to find your files.

However, be careful about making things too complex. If your team is used to the standard src/main/java layout, changing it can cause confusion and setup problems in IDEs or CI/CD systems.

How a Typical Gradle Java Project Looks in Eclipse

When everything is set up correctly in Eclipse, your project will look like this:

Project Explorer
└── your-project
    ├── build.gradle
    ├── settings.gradle
    └── src
        ├── main
        │   ├── java (recognized as Source Folder)
        │   └── resources
        └── test
            ├── java (test source folder)
            └── resources

Eclipse marks source folders with a special icon in the Project Explorer. Code within these folders will be compiled and ready when the app runs or when tests run, based on where they are.

Errors Due to Wrong Structure

Getting the structure wrong can cause many problems. Some of these are very hard to find. Look out for:

• ❗ Source file errors (for example, “cannot find symbol”)
• ❌ Gradle build problems
• 🚫 Class not found errors when the app runs
• ⚠ Test files not found or not run

How to fix:

• Check your folder locations.
• Make sure they are listed correctly in your build.gradle file.
• Do a full refresh (or clean build) after changing the structure or settings.

Best Practices for Project Structure

Here are good ways to keep your Eclipse Gradle Java project easy to manage:

• ✅ Use the default gradle project structure (src/main/java, etc.)
• ✅ Turn on the eclipse plugin in build.gradle
• 🔄 Link changes in Eclipse often using "Refresh Gradle Project"
• 🚫 Do not change .classpath or .project files by hand; Gradle manages these
• 📚 Write down any custom setup in a README.md or internal guide
• 🔗 Use version control for your build scripts to keep track of changes

These habits help keep things consistent across different setups. They also cut down the time it takes for new developers to get started.

What About IntelliJ vs Eclipse?

This guide talks about Eclipse. But you might wonder how this applies to IntelliJ IDEA. The good news is that IntelliJ’s Gradle work is even smoother.

Differences:

• IntelliJ can find Gradle projects more easily, even with layouts that are not standard.
• It gives automatic ideas for missing settings or folders.
• It usually needs fewer manual refreshes.

Still, we always suggest sticking to Gradle's expected src/main/java rule. It makes your project easy to move between IDEs. It also makes sure it works with automation tools and helps people work together better.

Final Thoughts

Knowing and using the correct gradle project structure—especially making sure source code is in src/main/java—is very important. It affects how your project builds, how IDEs see it, and if it can be released. When you work in Eclipse with Gradle, the right setup leads to fewer build errors, more reliable code help, and simpler source management.

Use Gradle’s standard ways when you can. Only change them when you must—and set them up carefully. Whether you are starting a new project or making an old one simpler, let these standards guide you to a steady and consistent project.

Need help starting from scratch? Download our [free Gradle Java starter template]. It includes a working src/main/java structure ready to use. It is also set up well for importing into Eclipse.

References

JetBrains. (2021). The State of Developer Ecosystem 2021. JetBrains. https://www.jetbrains.com/lp/devecosystem-2021
Gradle Foundation. (2023). Understanding the Java Plugin. Gradle.org. https://docs.gradle.org