(Quick Reference)

18.2 Build From Source and Run Tests - Reference Documentation

Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith

Version: null

18.2 Build From Source and Run Tests

In order to build Grails from source and run the tests, you need to first have the following pre-requisites.
  • JDK (1.6+)
  • Git client

Once you have all the pre-requisite packages installed, the next step is to download the Grails source code. The source code is hosted at GitHub in several different git repositories owned by the "grails" GitHub user.

To download the source using git, use the "git clone" command followed by the public URL of the repository you want to clone (download). For example, to clone the "grails-core" repository, run the following:

git clone http://github.com/grails/grails-core.git

The above will create a "grails-core" directory in your current working directory populated with the project source and the git repository.

Create the required jars

./gradlew libs

This will create everything you need to run Grails. This target also skips running the extensive collection of Grails test classes (Grails' 1000+ tests can bring a single core processor to a grinding halt for some time).

Once the jars have been built, simply set GRAILS_HOME to the checkout directory and add the "bin" directory to your path.

Run the test suite

All you have to do to run the full suite of tests is:

./gradlew test

These will take a while (15-30 mins), so consider running individual tests using the command line. For example, to run the tests in src/test/org/codehaus/groovy/grails/orm/hibernate/MappingDslTests.groovy, run the following command:

./gradlew -Dtest.single=MappingDslTest grails-test-suite-persistence:test

You need to give it the specific test suite that the test exists in, just using the "test" target won't work.

Developing in IntelliJ IDEA

You need to run the following gradle task:

./gradlew idea

Then open the project file which is generated in IDEA. Simple!

Developing in STS / Eclipse

You need to run the following gradle task:

./gradlew cleanEclipse eclipse

Before importing projects to STS do the following action:

  • Edit grails-scripts/.classpath and remove the line "<classpathentry kind="src" path="../scripts"/>".

Use "Import->General->Existing Projects into Workspace" to import all projects to STS. There will be a few build errors. To fix them do the following actions:

  • Add "~/.gradle/cache/com.springsource.springloaded/springloaded-core/jars/springloaded-core-XXXX.jar" to grails-core's classpath.
  • Remove "src/test/groovy" from grails-plugin-testing's source path GRECLIPSE-1067
  • Add "~/.gradle/cache/javax.servlet.jsp/jsp-api/jars/jsp-api-2.1.jar" to the classpath of grails-web
  • Fix the source path of grails-scripts. Add linked source folder linking to "../scripts". If you get build errors in grails-scripts, do "../gradlew cleanEclipse eclipse" in that directory and edit the .classpath file again (remove the line "<classpathentry kind="src" path="../scripts"/>"). Remove possible empty "scripts" directory under grails-scripts if you are not able to add the linked folder.
  • Do a clean build for the whole workspace.
  • To use Eclipse GIT scm team provider: Select all projects (except "Servers") in the navigation and right click -> Team -> Share project (not "Share projects"). Choose "Git". Then check "Use or create repository in parent folder of project" and click "Finish".
  • Get the recommended code style settings from the mailing list thread (final style not decided yet, currently profile.xml). Import the code style xml file to STS in Window->Preferences->Java->Code Style->Formatter->Import . Grails code uses spaces instead of tabs for indenting.

Debug

To debug Grails run the Grails application using:

grails-debug <command>

and then connect to it remotely via the IDE. There should be an option for "remote debugging". Unless you modify the "grails-debug" script, you should connect to port 5005.

If you need to debug stuff that happens during application start-up, then you should modify the "grails-debug" script and change the "suspend" option from 'n' to 'y'.

You can read more about the JPDA Connection settings here: http://java.sun.com/j2se/1.5.0/docs/guide/jpda/conninv.html#Invocation

It's also possible to get Eclipse to wait for incoming debugger connections and instead of using "-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005" you could use this "-Xrunjdwp:transport=dt_socket,server=n,address=8000" (which assumes the Eclipse default port for remote java applications) Inside eclipse you create a new "Remote Java Application" launch configuration and change the connection type to "Standard (Socket Listen)" and click debug. This allows you to start a debugger session in eclipse and just leave it running and you're free to debug anything without having to keep remembering to relaunch a "Socket Attach" launch configuration. You might find it handy to have 2 scripts, one called "grails-debug", and another called "grails-debug-attach"