This page covers the practical steps and underlying build infrastructure for setting up a development IDE to work with the Spring Boot source code. It focuses on Eclipse (using the provided Oomph setup file) and Gradle Buildship import, and explains how the EclipseConventions build plugin keeps project IDE settings synchronized with the build.
For background on the build conventions that generate these IDE settings, see the ConventionsPlugin System and JavaConventions and Task Configuration. For information on contributing workflows and code formatting requirements, see Contributing and Development Workflow.
The build requires JDK 25 or higher to compile (BUILD_JAVA_VERSION = 25 in JavaConventions). All source is compiled to Java 17 bytecode (RUNTIME_JAVA_VERSION = 17). Both JDKs should be available on the machine before importing the project.
| Requirement | Value | Source |
|---|---|---|
| Build JDK | Java 25+ | buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java138-140 |
| Source / target compatibility | Java 17 | buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java140 |
| Gradle wrapper | Defined in gradle/wrapper/ | ./gradlew in project root |
The repository ships a complete Eclipse Oomph project setup file at eclipse/spring-boot-project.setup1-431 Oomph automates plugin installation, JRE registration, memory configuration, Gradle project import, and working set creation in a single step.
Eclipse Oomph setup flow:
Sources: eclipse/spring-boot-project.setup1-431
The setup file registers a JavaSE-24 JRE from ${jre.location-24}. Gradle import tasks use ${jre.location-17} as the Java home for the Buildship import tasks.
eclipse/spring-boot-project.setup22-30
| Option | Value |
|---|---|
-Xmx | 2048m |
-Xms | 512m |
eclipse/spring-boot-project.setup33-42
The P2Task in the Oomph setup installs the following Eclipse features automatically:
| Feature ID | Purpose |
|---|---|
org.eclipse.platform.feature.group | Eclipse platform |
org.eclipse.jdt.feature.group | Java Development Tools |
io.spring.javaformat.eclipse.feature.feature.group | Spring JavaFormat formatter |
org.eclipse.m2e.feature.feature.group | Maven integration (M2E) |
org.eclipse.oomph.setup.maven.feature.group | Oomph Maven support |
org.eclipse.oomph.setup.workingsets.feature.group | Oomph working sets |
org.eclipse.buildship.feature.group | Buildship Gradle integration |
org.eclipse.buildship.oomph.feature.group | Buildship Oomph integration |
org.eclipse.wst.web_ui.feature.feature.group | Web Tools Platform (WTP) |
The Spring JavaFormat plugin is sourced from https://repo.spring.io/javaformat-eclipse-update-site/. Buildship is sourced from https://download.eclipse.org/buildship/updates/e49/releases/.
Sources: eclipse/spring-boot-project.setup67-98
Oomph registers two separate GradleImportTask entries, both using ${jre.location-17} as the Gradle Java home:
The locateNestedProjects: true flag on the first task causes Buildship to discover all ~200 subprojects declared in settings.gradle and import each as a separate Eclipse project.
The buildSrc directory is imported as a separate Gradle build because it is an independent included build with its own build.gradle.
Sources: eclipse/spring-boot-project.setup99-111
Once imported, projects are sorted into Eclipse working sets by directory location pattern. The WorkingSetTask in the setup file defines the following working sets:
| Working Set | Location Pattern |
|---|---|
platform | .*/platform(/.*)? |
core | .*/core(/.*)? |
module | .*/module(/.*)? |
loader | .*/loader(/.*)? |
configuration-metadata | .*/configuration-metadata(/.*)? |
buildpack | .*/buildpack(/.*)? |
build-plugin | .*/build-plugin(/.*)? |
cli | .*/cli(/.*)? |
test-support | .*/test-support(/.*)? |
integration-test | .*/integration-test(/.*)? |
smoke-test | .*/smoke-test(/.*)? |
system-test | .*/system-test(/.*)? |
starter | .*/starter(/.*)? |
documentation | .*/documentation(/.*)? |
build | spring-boot-build, buildSrc, gradle |
The Package Explorer is also configured to display working sets as its root objects.
Sources: eclipse/spring-boot-project.setup112-213
Beyond the one-time Oomph setup, the build system continuously synchronizes per-project Eclipse settings files each time ./gradlew eclipse is run. This is handled by EclipseConventions, which is registered as part of ConventionsPlugin and therefore applied to every subproject.
EclipseConventions class interactions:
Sources: buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java1-124 buildSrc/src/main/java/org/springframework/boot/build/ConventionsPlugin.java54
EclipseSynchronizeJdtSettings)The eclipseSynchronizeJdtSettings task writes .settings/org.eclipse.jdt.core.prefs with:
org.eclipse.jdt.core.compiler.release=true
This enables the JDK release flag in the Eclipse compiler to match the --release argument used by Gradle's JavaCompile tasks.
Sources: buildSrc/src/main/java/org/springframework/boot/build/EclipseSynchronizeJdtSettings.java43-54
EclipseSynchronizeResourceSettings)The eclipseSynchronizateResourceSettings task writes .settings/org.eclipse.core.resources.prefs with:
encoding/<project>=UTF-8
This ensures that Eclipse's per-project encoding matches the UTF-8 encoding configured on all JavaCompile, Javadoc, and Format tasks in JavaConventions.
Sources: buildSrc/src/main/java/org/springframework/boot/build/EclipseSynchronizeResourceSettings.java43-54
EclipseConventions also calls model.jdt(this::configureJdt) to set:
sourceCompatibility = JavaVersion.toVersion(17) (from JavaConventions.RUNTIME_JAVA_VERSION)targetCompatibility = JavaVersion.toVersion(17)javaRuntimeName = "JavaSE-" + systemRequirements.getJava().getVersion() (evaluated after project evaluation)Sources: buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java85-108
EclipseConventions removes Kotlin plugin-contributed build directories from the Eclipse classpath when they are tagged as test entries. This is a workaround for a Buildship bug (issue #1238) where Kotlin subproject classpath entries get incorrectly duplicated.
Sources: buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java90-122
In addition to per-project file synchronization, the Oomph setup file applies workspace-level Eclipse preferences.
org.eclipse.jdt.ui)| Preference Key | Value / Purpose |
|---|---|
content_assist_autoactivation_delay | 40 ms |
content_assist_disabled_computers | Disables javaNoTypeProposalCategory, javaTypeProposalCategory, textProposalCategory, code recommender templates |
org.eclipse.jdt.ui.typefilter.enabled | Filters java.awt.*, org.hibernate.collection.* from type proposals |
escape¥Strings | true |
content_assist_favorite_static_members | Pre-imports AssertJ, Hamcrest, JUnit, Mockito, MockMvc static members |
smart_backspace, smart_opening_brace, smart_semicolon, smart_tab, smartIndentAfterNewline, smartPaste | All true |
noformat template | Inserts // @formatter:off / // @formatter:on wrapper |
Sources: eclipse/spring-boot-project.setup216-265
org.eclipse.jdt.core)| Preference Key | Value |
|---|---|
org.eclipse.jdt.core.compiler.problem.nonExternalizedStringLiteral | ignore |
Sources: eclipse/spring-boot-project.setup267-273
org.eclipse.core.resources)| Preference Key | Value |
|---|---|
encoding | UTF-8 |
refresh.enabled | false (auto-refresh disabled) |
Sources: eclipse/spring-boot-project.setup275-285
org.eclipse.m2e.core)| Preference Key | Value |
|---|---|
eclipse.m2.hideFoldersOfNestedProjects | true |
eclipse.m2.updateIndexes | false |
eclipse.m2.defaultPomEditorPage | true |
Sources: eclipse/spring-boot-project.setup287-301
org.eclipse.ui.editors)| Preference Key | Value |
|---|---|
printMarginColumn | 120 |
lineNumberRuler | false |
printMargin | true |
showWhitespaceCharacters | true |
whitespaceCharacterAlphaValue | 20 |
Sources: eclipse/spring-boot-project.setup302-325
Several Spring IDE validators are disabled to reduce noise in the error/warning views for a project that does not use XML bean definitions:
BeansCorePlugin.DISABLE_AUTO_DETECTION = truebeansvalidator rules disabledbootvalidator disableduseChangeDetectionForJavaFiles = falseSources: eclipse/spring-boot-project.setup328-409
org.eclipse.ui.workbench)| Preference Key | Value |
|---|---|
HeapStatus.showMax | true (shows max heap in the status bar) |
RUN_IN_BACKGROUND | true |
Sources: eclipse/spring-boot-project.setup411-421
Code formatting is enforced by the Spring JavaFormat plugin. The Oomph setup installs the io.spring.javaformat.eclipse.feature Eclipse plugin, which applies formatting automatically on save.
Format violations can also be fixed from the command line:
./gradlew format
For buildSrc only:
./gradlew -p buildSrc format
Checkstyle rules are in config/checkstyle/ and are applied to all Java source by JavaConventions.configureSpringJavaFormat().
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java289-304 CONTRIBUTING.adoc44-48
If not using Oomph, the project can be imported manually into Eclipse via Buildship:
org.eclipse.buildship.feature.group).https://repo.spring.io/javaformat-eclipse-update-site/.buildSrc/ as a second, separate Gradle project.After import, run ./gradlew eclipse from the project root to generate the per-project .settings/ files that EclipseConventions manages.
Sources: CONTRIBUTING.adoc44-46 buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java47-83
Sources: buildSrc/src/main/java/org/springframework/boot/build/ConventionsPlugin.java54 buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java1-124 buildSrc/src/main/java/org/springframework/boot/build/EclipseSynchronizeJdtSettings.java1-56 buildSrc/src/main/java/org/springframework/boot/build/EclipseSynchronizeResourceSettings.java1-56 buildSrc/src/main/java/org/springframework/boot/build/EmptyPropertiesPersistableConfigurationObject.java1-57 eclipse/spring-boot-project.setup1-431 eclipse/eclipse.properties1
Refresh this wiki