From f8800557d3fa2cdf7c715f48c703d6424516c4ad Mon Sep 17 00:00:00 2001
From: Chris Beams <cbeams@vmware.com>
Date: Fri, 20 Jan 2012 14:53:56 +0100
Subject: [PATCH] Update README and add IDE import helper scripts

 - Update building from source section with Gradle instructions
 - Add import-into-eclipse.sh interactive helper script
 - Add import-into-idea.md with steps and known issues

Note that use of STS Gradle tooling was attempted, but several issues
remain before it can handle the spring-framework build. In the meantime
the instructions laid out in import-into-eclipse provide an error-free
import.
---
 README.md              |  29 ++++++++--
 import-into-eclipse.sh | 124 +++++++++++++++++++++++++++++++++++++++++
 import-into-idea.md    |  32 +++++++++++
 3 files changed, 179 insertions(+), 6 deletions(-)
 create mode 100755 import-into-eclipse.sh
 create mode 100644 import-into-idea.md

diff --git a/README.md b/README.md
index d4549d3a5f..3a7ba778d1 100644
--- a/README.md
+++ b/README.md
@@ -31,14 +31,31 @@ Check out the [Spring forums](http://forum.springsource.org) and the
 ## Issue Tracking
 Spring's JIRA issue tracker can be found [here](http://jira.springsource.org/browse/SPR). Think
 you've found a bug? Please consider submitting a reproduction project via the
-[spring-framework-issues](https://github.com/springsource/spring-framework-issues) repository. The
-[readme](https://github.com/springsource/spring-framework-issues#readme) provides simple
-step-by-step instructions.
+[spring-framework-issues](https://github.com/SpringSource/spring-framework-issues) repository. The
+[readme](https://github.com/SpringSource/spring-framework-issues#readme) provides simple
+step-by-step instructions.  <a name="building_from_source"/>
+
 
 ## Building from source
-Instructions on
-[building Spring from source](https://github.com/SpringSource/spring-framework/wiki/Building-from-source)
-are available via the project wiki.
+The Spring Framework uses a [Gradle](http://gradle.org)-based build system. In the instructions
+below, [`./gradlew`](http://vimeo.com/34436402) is invoked from the root of the source tree and
+serves as a cross-platform, self-contained bootstrap mechanism for the build. The only
+prerequisites are [git](http://help.github.com/set-up-git-redirect) and JDK 1.6+.
+
+### check out sources
+`git clone git://github.com/SpringSource/spring-framework.git`
+
+### compile and test, build all jars, distribution zips and docs
+`./gradlew build`
+
+### install all spring-\* jars into your local Maven cache
+`./gradlew install`
+
+### import sources into your IDE
+Run `./import-into-eclipse.sh` or read `import-into-idea.md` as appropriate.
+
+... and discover more commands with `./gradlew tasks`. See also the
+[Gradle build and release FAQ](https://github.com/SpringSource/spring-framework/wiki/Gradle-build-and-release-FAQ).
 
 ## Contributing
 [Pull requests](http://help.github.com/send-pull-requests) are welcome; you'll be asked to sign our
diff --git a/import-into-eclipse.sh b/import-into-eclipse.sh
new file mode 100755
index 0000000000..c8c87c04c6
--- /dev/null
+++ b/import-into-eclipse.sh
@@ -0,0 +1,124 @@
+STS_TEST_VERSION='2.8.1.RELEASE'
+
+cd `dirname $0`
+clear
+cat <<EOM
+
+-----------------------------------------------------------------------
+Spring Framework Eclipse/STS project import guide
+
+This script will guide you through the process of importing the
+Spring Framework sources into Eclipse/STS. It is recommended that you
+have a recent version of the SpringSource Tool Suite (this script has
+been tested against STS $STS_TEST_VERSION), but at the minimum you will
+need Eclipse + AJDT.
+
+If you need to download and install STS, please do that now by
+visiting http://springsource.org/downloads/sts
+
+Otherwise, press enter and we'll begin.
+EOM
+
+read
+
+# this command:
+# - wipes out any existing Eclipse metadata
+# - generates OXM test classes to avoid errors on import into Eclipse
+# - generates metadata for all subprojects
+# - skips metadata gen for the root project (-x :eclipse) to work
+#   around Eclipse's inability to import hierarchical project structures
+COMMAND="./gradlew clean cleanEclipse :spring-oxm:compileTestJava eclipse -x :eclipse"
+
+cat <<EOM
+
+-----------------------------------------------------------------------
+STEP 1: Generate subproject Eclipse metadata
+
+The first step will be to generate Eclipse project metadata for each
+of the spring-* subprojects. This happens via the built-in
+"Gradle wrapper" script (./gradlew in this directory). If this is your
+first time using the Gradle wrapper, this step may take a few minutes
+while a Gradle distribution is downloaded for you.
+
+The command run will be:
+
+    $COMMAND
+
+Press enter when ready.
+EOM
+
+read
+
+$COMMAND || exit
+
+cat <<EOM
+
+-----------------------------------------------------------------------
+STEP 2: Import subprojects into Eclipse/STS
+
+Within Eclipse/STS, do the following:
+
+File > Import... > Existing Projects into Workspace
+   > When prompted for the 'root directory', provide $PWD
+   > Press enter. You will see the modules show up under "Projects"
+   > All projects should be selected/checked. Click Finish.
+   > When the project import is complete, you should have no errors.
+
+When the above is complete, return here and press the enter key.
+EOM
+
+read
+
+COMMAND="./gradlew :eclipse"
+
+cat <<EOM
+
+-----------------------------------------------------------------------
+STEP 3: generate root project Eclipse metadata
+
+Unfortunately, Eclipse does not allow for importing project
+hierarchies, so we had to skip root project metadata generation in the
+during step 1. In this step we simply generate root project metadata
+so you can import it in the next step.
+
+The command run will be:
+
+    $COMMAND
+
+Press the enter key when ready.
+EOM
+
+read
+
+$COMMAND || exit
+
+cat <<EOM
+-----------------------------------------------------------------------
+STEP 4: Import root project into Eclipse/STS
+
+Follow the project import steps listed in step 2 above to import the
+root project.
+
+Press enter when complete, and move on to the final step.
+EOM
+
+read
+
+cat <<EOM
+-----------------------------------------------------------------------
+STEP 5: Enable Git support for all projects
+
+- In the Eclipse/STS Package Explorer, select all spring* projects.
+- Right-click to open the context menu and select Team > Share Project...
+- In the Share Project dialog that appears, select Git and press Next
+- Check "Use or create repository in parent folder of project"
+- Click Finish
+
+When complete, you'll hvae have Git support enabled for all projects.
+
+Note: if any projects have errors after adding Git support
+(e.g. spring-aspects), simply go to Project > Clean... and clean that
+project. This should remove any errors.
+
+You're ready to code! Goodbye!
+EOM
diff --git a/import-into-idea.md b/import-into-idea.md
new file mode 100644
index 0000000000..15a4e9e62d
--- /dev/null
+++ b/import-into-idea.md
@@ -0,0 +1,32 @@
+The following has been tested against Intellij IDEA 11.0.1
+
+## Steps
+
+_Within your locally cloned spring-framework working directory:_
+
+1. Generate IDEA metadata with `./gradlew cleanIdea idea`
+2. Import into IDEA as usual
+3. Set the Project JDK as appropriate
+4. Add git support
+5. Code away
+
+## Known issues
+
+1. MockServletContext and friends will fail to compile in spring-web. To fix this, uncheck the 'export' setting for all servlet-api and tomcat-servlet-api jars. The problem is that spring-web needs Servlet 2.5, but it's picking up Servlet 3.0 from projects that it depends on.
+2. spring-context will fail to build because there's a duplicate instance of GroovyMessenger in spring-context/src/test/java/org/springframework/scripting/groovy/Messenger.groovy. The solution to this is not known.  It's not a problem on Eclipse, because Eclipse doesn't automatically compile .groovy files like IDEA (apparently) does.
+
+There are no other known problems at this time.  Please add to this list, and if you're ambitious, consider playing with the Gradle IDEA generation DSL to fix these problems automatically, e.g.:
+
+* http://gradle.org/docs/current/dsl/org.gradle.plugins.ide.idea.model.IdeaProject.html
+* http://gradle.org/docs/current/dsl/org.gradle.plugins.ide.idea.model.IdeaModule.html
+* http://gradle.org/docs/current/groovydoc/org/gradle/plugins/ide/idea/model/IdeaModule.html
+
+## Tips
+
+In any case, please do not check in your own generated .iml, .ipr, or .iws files. You'll notice these files are already intentionally in .gitignore. The same policy goes for eclipse metadata.
+
+## FAQ
+
+Q. What about IDEA's own [Gradle support](http://confluence.jetbrains.net/display/IDEADEV/Gradle+integration)?
+
+A. Unknown. Please report back if you try it and it goes well for you.