spring-framework/import-into-eclipse.md

Spring Framework - Eclipse Project Import Guide

This document will guide you through the process of importing the Spring Framework projects into Eclipse IDE or the Spring Tools for Eclipse. It is recommended that you have a recent version of Eclipse. The build uses JDK 25 (see .sdkmanrc), so as a bare minimum you will need Eclipse with full Java 25 support.

The following instructions have been tested against Spring Tools for Eclipse 5.4.0 (based on Eclipse IDE 4.41). The instructions should also work with the latest release of the Eclipse IDE for Java Developers; Spring Tools is not required.

Steps

When instructed to execute ./gradlew from the command line, be sure to execute it within your locally cloned spring-framework working directory.

1. Ensure that the Forbidden reference (access rule) in Eclipse is set to Info (Preferences → Java → Compiler → Errors/Warnings → Deprecated and restricted API → Forbidden reference (access rule)).
2. Optionally install the Kotlin Plugin for Eclipse if you need to execute Kotlin-based tests or develop Kotlin extensions.
3. Optionally install the AspectJ Development Tools (AJDT) if you need to work with the spring-aspects project.
4. Optionally install the TestNG plugin in Eclipse if you need to execute individual TestNG test classes or tests in the spring-test module.
   • As an alternative to installing the TestNG plugin, you can execute the org.springframework.test.context.testng.TestNGTestSuite class as a "JUnit 6" test class in Eclipse.
5. Compile all main and test classes from the command line first with ./gradlew testClasses. This pre-compiles spring-core and generates the JAXB types for spring-oxm (see Known Issues below).
6. To apply Spring Framework specific settings, run ./gradlew cleanEclipse eclipse from the command line.
7. Import all projects into Eclipse (File → Import → General → Existing Projects into Workspace → Navigate to the locally cloned spring-framework directory → Select Finish).
   • If you have not installed AJDT, exclude the spring-aspects project from the import, if prompted, or close it after the import.
8. Code away!

Known Issues

1. spring-core should be pre-compiled due to repackaged dependencies.
   • See *RepackJar tasks in the spring-core.gradle build file.
2. spring-oxm should be pre-compiled due to JAXB types generated for tests.
   • Note that executing ./gradlew testClasses as explained in the Steps above will compile spring-core and generate JAXB types for spring-oxm.
3. spring-aspects does not compile due to references to aspect types unknown to Eclipse.
   • If you installed AJDT into Eclipse it should work.
4. The Java 21 and Java 24 multi-release sources in spring-core (src/main/java21, src/main/java24, and src/test/java21) are not configured as source folders in Eclipse, since an Eclipse project supports only a single Java compliance level.
   • Use ./gradlew :spring-core:java21Test or ./gradlew :spring-core:java24Test to build and test those sources from the command line.
5. While JUnit tests pass from the command line with Gradle, some may fail when run from the IDE.
   • Resolving this is a work in progress.
   • If attempting to run all JUnit tests from within the IDE, you may need to set the following VM option to avoid out of memory errors: -Xmx2048m
   • Tests run via Gradle are also configured with the following VM options (see TestConventions in buildSrc), which you may need to set in your Eclipse launch configuration as well: --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED -Xshare:off

Tips

In any case, please do not check in your own generated .classpath file, .project file, or .settings folder. You'll notice these files are already intentionally in .gitignore. The same policy holds for IntelliJ IDEA metadata.