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.

19 thoughts on “Developing Grails: setting yourself up

  1. Wolfgang

    Hi Peter,

    great writeup! Thanks for sharing this information and looking forward for more installments of this series.

    Regards,

    Wolfgang

  2. Peter Post author

    @Burt & Dmitriy This is the first I’ve heard of that book effort – nice idea. I think I’ll stick to the blog format for now, but look into porting stuff across to the book. How does the book manage images?

    @Andrew Great news! Looking forward to trying it out when it’s available.

  3. Dmitriy Kopylenko

    @Peter – it’s basically Textile text format automatically transformed into HTML when pushed to Github. So, whatever Textile’s way of inserting images, I guess.

  4. Matt

    Just out of interest – what benefits do you see to using git over svn. I don’t have any opinions and I’m not trying to start a flame war – just interested in your opinion.

  5. Peter Post author

    @Matt A thorough answer would take too long, but basically it comes down to:

    1. You can work much more easily offline with Git than with Subversion.
    2. Branching and merging Just Work™ and are actively encouraged with Git.

    I love it because you can easily maintain multiple local branches for working on different issues and just switch between them whenever you need to. You can even fix commits after you have made them (but before you push them to the server).

    There are other little benefits too, but the main ones are the two above. Subversion benefits from better tool support currently, and a simpler model to understand.

  6. Rob Fletcher

    Great write-up

    One thing I did need to do was to increase heap space allocated to Ant in order to get the tests to run. I used ANT_OPTS=Xmx512m

  7. Thierry

    I may have enough time to contribute, but I’m too often behind a firewall.

    The last time I tried GIT through proxy was a failure.
    Proxy support has been added ?

  8. Peter Post author

    @Thierry I haven’t used git behind a proxy, but if you do a google search for “git proxy” you’ll find several possible solutions. Whether any of them will work for you, I don’t know. I hope so!

  9. Pingback: Give open source some love back! « Schneide Blog

  10. Chris Bedford

    Hi, Peter:

    Great post.. I have been poking into Grails internals and this is going to help me do some experiments.

    Your blog readers might get some use out of this article that I recently wrote up on how to set up an IDE (I used IDEA in my example) to debug into Grails and depended-on Spring, etc. sources:

    http://buildchimp.com/wordpress/?p=459

    best regards
    -chris

  11. chris bedford

    Hi..

    One last comment: the git locations and build steps provided in your recipe have gotten a little stale. You might want to point your blog readers to this location which has the new location and the gradle based build instructions.

    This more or less worked for me.. I had to go outside the instructions provided.. Once i did that it produced a 1.3.1 grails distro that i could hack on locally.

    > http://www.grails.org/Installation

  12. Peter Post author

    Thanks Chris. I did a bunch of updates to the article. I realised that the discussion on IDEs was pretty out of date too.

Leave a Reply

Your email address will not be published. Required fields are marked *