Setting up a Grails development environment

So, you'd like to delve into the Grails source code? Whatever reason you have for doing so, you first need to set yourself up so that you can easily run and debug with the source code version of Grails. Where to start?

Pre-requisites

You won't go far without some essential tools and libraries, but to be honest you probably already have all of them:

JDK (preferably 1.5+)
Ant
Subversion client
spring-framework-2.5.6-with-dependencies.zip (Contains source code for spring 2.5.6 framework will all required dependencies in one package. Please download from springsource.com)
Groovy 1.6 (Included with grails 1.1.1)

In fact, you don't even need Ant since Grails includes a copy in its "ant" directory, but it's a good idea to set up Ant independently.

Getting hold of the Grails source code

Once you have all the pre-requisite packages installed, it's time to get hold of the Grails source code. Typically you will want to get hold of "trunk", but on occasion there will be a branch that you need to work with instead. At the time of this writing, "trunk" contains the "1.1.1-SNAPSHOT" version source code. Please check the "gradle.properties" file in the root checkout folder for the version of grails checked out from the svn.

For those wanting to work via the IntelliJ IDE please see section below on intelliJ.

In order to get hold of the current snapshot version of Grails source code, please check it out from the Codehaus repository:

svn co http://svn.codehaus.org/grails/trunk/grails

The above will create a "grails" directory in your current working directory populated with the project source. If you want to work with a branch instead, ask on the mailing list for the URL to use.

Building and running

After you have made a change to Grails, how do you check that it has had the desired effect?

Create the required jars

Running "ant jar" 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. You will also have to update the application.properties file for any project you run with the development version so that the {{app.grails.version}} property matches the version of Grails you are using.

For example, say Grails trunk is at version 1.0.3-SNAPSHOT and your development version of Grails is located at C:\java\grails-1.0.3-dev , then you would set the environment variable:

GRAILS_HOME = C:\java\grails-1.0.3-dev

and change each project's application.properties so that they contain:

app.grails.version = 1.0.3-SNAPSHOT

Note that you only have to do this for projects that you are running with your development version of Grails!

Run the test suite

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

ant test

These will take a while (15-30 mins), so consider running individual tests using the command line:

ant -Dtest=XXXXX test

where XXXXX is the name of the test class _minus the Tests suffix_! So if you wanted to run the test case grails.test.MockUtilsTests , then you would use:

ant -Dtest=MockUtils test

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'.

IntelliJ

IntelliJ IDE support working with the grails 1.1.1 source code. You get the source code from svn at

svn co http://svn.codehaus.org/grails/trunk/grails

Once downloaded the IntelliJ IDE will ask to set the SPRING_HOME directory. Point this to the extracted spring source 2.5.6 directory. Also you might need to set the groovy SDK facet. If so then point the SDK to the grails included groovy-all-1.6.jar. This jar file can be located in GRAILS_HOME/lib folder.

To make sure everything is setup correctly. Choose 'Build|Make Project' option.

IntelliJ Running/Debugging

Click on the drop-down list next to the "Run" button and select "Edit configurations". In the dialog that appears, just click on the "+" symbol and select "Remote". Give the configuration a name (such as "Grails Remote") and then click on "OK". You will now be able to select "Grails Remote" from that drop-down list we mentioned and click on the "Debug" button. You can now set breakpoints to your heart's content.

Note that you do not have to worry about the port because IntelliJ uses 5005 by default