Developing Grails: setting yourself up @ Peter Ledbrook

Developing Grails: setting yourself up

Posted on July 17th, 2009 Peter 19 comments

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-coreThis 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:
- Git Magic
- Git for Subversion users
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:$PATHOf 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.

Groovy & Grails
19 responses to “Developing Grails: setting yourself up”
1. Wolfgang July 17th, 2009 at 14:46
  
  Hi Peter,
  
  great writeup! Thanks for sharing this information and looking forward for more installments of this series.
  
  Regards,
  
  Wolfgang
2. Burt Beckwith July 17th, 2009 at 15:16
  
  Great to see you blogging (and twittering) again. Thanks for writing this up – hopefully you’ll be able to contribute here also: http://github.com/dima767/grails-internals-handbook/tree/master
3. Jorge July 17th, 2009 at 16:01
  
  Waiting for next steps, Peter!
4. Colin Harrington July 17th, 2009 at 16:43
  
  Excellent writeup. Time to dive in a little deeper
5. Dmitriy Kopylenko July 17th, 2009 at 20:43
  
  Hi Peter,
  
  It would be real cool if you contribute the core technical stuff to the ‘Grails Internals’ handbook: http://github.com/dima767/grails-internals-handbook/tree/master
6. Andrew Eisenberg July 17th, 2009 at 20:53
  
  Just be patient…better Eclipse support for Groovy is on the way!
7. Dmitriy Kopylenko July 17th, 2009 at 23:42
  
  Hi Peter. Great stuff. I really hope that you find some time and contribute this technical stuff to http://github.com/dima767/grails-internals-handbook/tree/master
8. Stefan July 19th, 2009 at 11:52
  
  Peter, thanks for this – this is excellent for git noobs.
9. Peter July 20th, 2009 at 10:43
  
  @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.
10. Dmitriy Kopylenko July 20th, 2009 at 11:33
  
  @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.
11. Matt July 21st, 2009 at 08:55
  
  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.
12. Peter July 21st, 2009 at 12:11
  
  @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.
13. Rob Fletcher July 23rd, 2009 at 21:50
  
  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
14. Thierry July 24th, 2009 at 09:35
  
  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 ?
15. Peter July 24th, 2009 at 10:18
  
  @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!
16. Give open source some love back! « Schneide Blog August 14th, 2009 at 09:34
  
  [...] bug reports. I believe that every contribution helps an open source project and many projects need help. The whole development team will work on projects they like. One day per month does not sound much [...]
17. Chris Bedford June 18th, 2010 at 06:09
  
  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
18. chris bedford June 18th, 2010 at 22:24
  
  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
19. Peter June 21st, 2010 at 09:11
  
  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

Name (required)

Mail (will not be published) (required)

Website