Daily Archives: July 17, 2009

Developing Grails: setting yourself up

Grails is in need of developers – just take a look at the number of issues in JIRA. The trouble is, developers don’t want to spend a long time familiarising themselves with how Grails works just to fix a bug. So, I hope to lower the barrier to entry by showing you how to develop and debug Grails itself in a series of articles. I’ll start with setting up the development environment.

Prerequisites

  • A JDK (1.5 or above). Make sure that you set the JAVA_HOME environment variable to the location of the JDK, *not* a JRE.
  • Ant (I think 1.7+).

That’s it! You don’t even need to install Groovy.

Getting the Grails source

Once upon a time, Grails used to be hosted in a Subversion repository on Codehaus. Those days are gone: you now need git to get the source code from GitHub. I won’t explain how to install git here (should be dead easy on unix-type operating systems), but for ye poor Windows users, try this blog post.

Once git is installed, you have a couple of options:

  1. sign up to GitHub, fork the Grails repository, and then clone your fork locally; or
  2. clone the Grails public URL.

I recommend the first option, because then it’s easy to submit your changes to the Grails development team via a push. The details of forking and pushing are described in one of the GitHub guides. Simply use the “fork” button on the main Grails page on GitHub.

Update I have updated the URL below to take into account the rearrangement of the Grails projects in GitHub.

The other option doesn’t require you to have a GitHub account. Instead, use your git client to get the source code directly:

git clone git://github.com/grails/grails-core.git grails-core
This will copy the Grails repository into a directory called “grails-core”. This will get you the core Grails code, but not the documentation, functional tests, Maven plugin nor a few other things. The core is what most people are interested in though.

Just remember that if you use the second option, you can’t push changes to the Grails team. You’ll have to create patch files and attach them to JIRA issues.

I’m not going to explain how to use git here, but if you need some help, take a look at these introductions:

System configuration

The next trick is to use the development version of Grails for your projects. This is surprisingly straightforward: just set the GRAILS_HOME environment variable to your Grails directory and update the path. So for example, if you have cloned the Grails repository in ~/dev/grails-core, then you set the environment variables like so:

export GRAILS_HOME = ~/dev/grails-core
export PATH = $GRAILS_HOME/bin:$PATH
Of course, the exact syntax you should use depends on your platform. Once these variables are set, you will be using your development version of Grails every time you run the grails command.

Build Grails

Update As of Grails 1.3, we use Gradle to build the project. I have updated the code below, but left the pre-1.3 commands in parentheses.

The source code is all very well, but the Grails command line won’t work until you have built the project. The easiest way to do this is to run

./gradlew libs
(pre-1.3: ant jar)
from the Grails source directory (.../grails-core). You can also run the unit tests with

./gradlew test
(pre-1.3: ant test)
And to execute a single test case:

./gradlew testSingleNameOfTestClassMinusTestExtension
(pre-1.3: ant -Dtest=NameOfTestClassMinusTestExtension test)
So if you want to run the GrailsClassUtilsTests, it’s

./gradlew testSingleGrailsClassUtils
(pre-1.3: ant -Dtest=GrailsClassUtils test)

Editing the source code

So far so good, but it’s not much good having a development version of Grails if you aren’t going to edit it. This is where things get tricky. Grails consists mostly of Java and Groovy code, so if you want to use an IDE, you need one that supports Groovy. IntelliJ IDEA is the prime candidate, but it’s commercial. That said, since you’ll be working on an open source project (Grails), you could use a (free) open source licence. One option is to register as a developer on Codehaus, but you may not be accepted until you have submitted a several (or more) patches that pass code reviews.

If you do have a licence for IntelliJ, you’ll find project files in the root of the Grails directory. Load those up and you’re away! Eclipse is probably a non-starter until SpringSource do their thing with the Groovy/Grails plugin. I’d like to recommend Netbeans, but every time I have tried it for the Grails source code, it has failed (usually becoming unusably slow or simply hanging). Hopefully things will improve in the not too distant future.

Update SpringSource Tool Suite (STS) with Groovy & Grails support is now working very well – and it’s free! IntelliJ Community edition is also free and comes with Groovy (but not Grails support). Since you only need the Groovy bit for working on the Grails code, the Community edition is also a viable option.

Next steps

You should now be set up for Grails development and raring to go. So, in the next installment, I shall look at how the Grails command line is implemented and shine a light on some of the mysteries of scripts and classpaths.