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

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.

Grails

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 writing, "trunk" contains the "1.0.x" code while the branch "GRAILS_1_1" contains the Grails 1.1 work.

Let's say that you want to get hold of just the Grails source code for "trunk". All you have to do is 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.

So, you have the source code. What's next?

checkout http://jira.codehaus.org/browse/GRAILS and see if you can fix any of them.

Testing Changes

So you've have Grails checked out from Subversion and you've made a change, how do you check that it has had the desired effect?

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

For example:

If your development version of Grails was located at

C:\java\grails-1.0.3-dev

you would set your environmental variable to match

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

Then in your Grails project change <project>/application.properties to

app.grails.version=1.0.3-dev

Debugging

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

Unit tests

Individual unit tests can be run using the command "ant run-test -Dtest=XXXXX"