Grails On Gentoo

Update

Grails 1.0.3 has been released & I've updated the ebuilds accordingly. To update your local overlay run :

hyperion # layman -s energizedwork
A    /usr/portage/local/layman/energizedwork/dev-java/grails/grails-1.0.3.ebuild
U    /usr/portage/local/layman/energizedwork/dev-java/grails/Manifest
Updated to revision 3552.
* 
* Success:
* ------
* 
* Successfully synchronized overlay "energizedwork".

Quick Install

For the impatient and trusting

emerge layman
sed -i "s/\(overlays.*layman-global.txt\)/\1\n\thttps:\/\/svn.energizedwork.com\/skunkworks\/gentoo\/layman.xml/g" /etc/layman/layman.cfg
layman -k -L
layman -k -a energizedwork
echo 'source /usr/portage/local/layman/make.conf' >> /etc/make.conf
emerge -av grails

Overview

Grails is a web application framework built on Java & Groovy that employs a code by convention approach which is refreshing for a territory that is normally awash with XML configuration files and boilerplate coding requirements. The introduction from the User Guide gives some more details on Grails' makeup & focus.

Preparation

There's no official Grails ebuild (yet!), so we're going to use the portage overlay mechanism to add a grails ebuild to our local portage tree.

Layman - manage your local repository of Gentoo overlays

To install Grails we'll first install a useful Gentoo utility called 'layman'. Searching for it we see the following:

hyperion # emerge --search layman
Searching...   
[ Results for search key : layman ]
[ Applications found : 1 ]
 
*  app-portage/layman
      Latest version available: 1.1.1
      Latest version installed: 1.1.1
      Size of files: 45 kB
      Homepage:      http://layman.sourceforge.net
      Description:   A python script for retrieving gentoo overlays.
      License:       GPL-2

OK, good, we can find it in the standard portage tree. Let's go ahead and install it:

hyperion # emerge -av layman

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild  N    ] app-portage/layman-1.1.1  USE="-test" 46 kB 

Total: 1 package (1 new), Size of downloads: 46 kB

Would you like to merge these packages? [Yes/No] Yes
>>> Verifying ebuild Manifests...

...

 * You are now ready to add overlays into your system.
 * 
 * layman -L
 * 
 * will display a list of available overlays.
 * 
 * Select an overlay and add it using
 * 
 * layman -a overlay-name
 * 
 * If this is the very first overlay you add with layman,
 * you need to append the following statement to your
 * /etc/make.conf file:
 * 
 * source /usr/portage/local/layman/make.conf
 * 
 * If you modify the 'storage' parameter in the layman
 * configuration file (/etc/layman/layman.cfg) you will
 * need to adapt the path given above to the new storage
 * directory.
 * 
 * Please add the 'source' statement to make.conf only AFTER 
 * you added your first overlay. Otherwise portage will fail.

The EnergizedWork Overlay

Next up we'll add the EnergizedWork portage overlay to the mix. Edit /etc/layman/layman.cfg and append the overlay list URL to the 'overlays' section:

[MAIN]
...
overlays  : http://www.gentoo.org/proj/en/overlays/layman-global.txt
            https://svn.energizedwork.com/skunkworks/gentoo/layman.xml

...

Let's run layman and see if it shows up:

hyperion # layman -L -k
* arcon                     [Subversion] (source: https://arcon.svn.sourcefo...)
...
* emacs                     [Subversion] (source: https://overlays.gentoo.or...)
* energizedwork             [Subversion] (source: https://svn.energizedwork....)
* enlightenment             [Subversion] (source: http://overlays.gentoo.org...)
...

Good stuff, looks like it picked it up. Notice however that it's got a yellow star beside it - this means that it isn't an officially supported Gentoo overlay. We had to add the -k (ignore) switch to layman for it to show up at all. This is good foresight by the Gentoo folks as adding overlays is easy with layman, opening the door for malicious ebuild makers to hose your system (or worse!). I'll mention now that there's NO WARRANTY supplied with any of the ebuilds hosted by EnergizedWork, so use at your own risk. It's always good practice to read an ebuild beforehand if you've got it from somewhere other than the official portage tree. Now that we're done with the official nastiness (*sigh*), let's push on.

Since layman can now see the energizedwork overlay we can add it to our system:

hyperion # layman -k -a energizedwork
* Running command "/usr/bin/svn co "https://svn.energizedwork.com/skunkworks/gentoo/overlay//" "/usr/portage/local/layman/energizedwork""...
A    /usr/portage/local/layman/energizedwork/dev-java
...
Checked out revision 3054.
* Successfully added overlay "energizedwork".

We're almost there - just one last thing to do before we can use the overlay to install grails. Do you remember the warning message at the end of the layman ebuild?:

 * If this is the very first overlay you add with layman,
 * you need to append the following statement to your
 * /etc/make.conf file:
 * 
 * source /usr/portage/local/layman/make.conf

Let's do what it says and see what happens:

hyperion # echo 'source /usr/portage/local/layman/make.conf' >> /etc/make.conf
hyperion # emerge -s grails
Searching...   
[ Results for search key : grails ]
[ Applications found : 1 ]
 
*  dev-java/grails
      Latest version available: 1.0.1
      Latest version installed: [ Not Installed ]
      Size of files: 28,581 kB
      Homepage:      http://grails.codehaus.org/
      Description:   open-source web application framework
      License:       Apache-2.0

w00t! (sorry)

Grails is now available to emerge.
NOTE: Running emerge --sync does not update overlays - run layman --sync ALL to do this, or better still add an alias to your profile to do both.

Command Summary

To recap, this is what we've done so far:

• emerged layman (emerge layman)
• added the overlay list URL to the layman configuration (/etc/layman/layman.cfg)
• locally installed the energizedwork overlay (layman -k -L; layman -k -a energizedwork)
• added layman to our portage configuration (echo 'source /usr/portage/local/layman/make.conf' >> /etc/make.conf)

Installing Grails

We should now be able to install Grails:

hyperion # emerge -av grails

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild  N    ] dev-java/grails-1.0.1  USE="java" 0 kB [1]

Total: 1 package (1 new), Size of downloads: 0 kB
Portage tree and overlays:
 [0] /usr/portage
 [1] /usr/portage/local/layman/energizedwork

Would you like to merge these packages? [Yes/No]
...
 * Grails 1.0.1 installed.
 * Please run 'source /etc/profile' to make it visible in your current profile
...

OK, let's update our profile and give it a whirl:

hyperion # source /etc/profile
hyperion # grails

Welcome to Grails 1.0.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: /opt/grails		
		
No script name specified. Use 'grails help' for more info

Finally!

Working with Grails

Now that Grails is installed it's time to build something. Let's create a sample project as a normal user and fire it up to make sure everything's ok:

gus@hyperion ~/scree $ grails create-app gentoo-test
Welcome to Grails 1.0.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: /opt/grails		
		
Base Directory: /home/gus/scree
Environment set to development
Note: No plugin scripts found
Running script /opt/grails/scripts/CreateApp.groovy
    [mkdir] Created dir: /home/gus/scree/gentoo-test/src
    [mkdir] Created dir: /home/gus/scree/gentoo-test/src/java
    [mkdir] Created dir: /home/gus/scree/gentoo-test/src/groovy
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/controllers
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/services
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/domain
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/taglib
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/utils
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/views
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/views/layouts
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/i18n
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/conf
    [mkdir] Created dir: /home/gus/scree/gentoo-test/test
    [mkdir] Created dir: /home/gus/scree/gentoo-test/test/unit
    [mkdir] Created dir: /home/gus/scree/gentoo-test/test/integration
    [mkdir] Created dir: /home/gus/scree/gentoo-test/scripts
    [mkdir] Created dir: /home/gus/scree/gentoo-test/web-app
    [mkdir] Created dir: /home/gus/scree/gentoo-test/web-app/js
    [mkdir] Created dir: /home/gus/scree/gentoo-test/web-app/css
    [mkdir] Created dir: /home/gus/scree/gentoo-test/web-app/images
    [mkdir] Created dir: /home/gus/scree/gentoo-test/web-app/META-INF
    [mkdir] Created dir: /home/gus/scree/gentoo-test/lib
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/conf/spring
    [mkdir] Created dir: /home/gus/scree/gentoo-test/grails-app/conf/hibernate
[propertyfile] Creating new property file: /home/gus/scree/gentoo-test/application.properties
     [copy] Copying 2 files to /home/gus/scree/gentoo-test
     [copy] Copying 2 files to /home/gus/scree/gentoo-test/web-app/WEB-INF
     [copy] Copying 5 files to /home/gus/scree/gentoo-test/web-app/WEB-INF/tld
     [copy] Copying 87 files to /home/gus/scree/gentoo-test/web-app
     [copy] Copying 17 files to /home/gus/scree/gentoo-test/grails-app
     [copy] Copying 1 file to /home/gus/scree/gentoo-test
     [copy] Copying 1 file to /home/gus/scree/gentoo-test
     [copy] Copying 1 file to /home/gus/scree/gentoo-test
[propertyfile] Updating property file: /home/gus/scree/gentoo-test/application.properties
Created Grails Application at /home/gus/scree/gentoo-test

So far so good. Let's change directory into the project folder and run the application:

gus@hyperion ~/scree $ cd gentoo-test/
gus@hyperion ~/scree/gentoo-test $ grails run-app

Welcome to Grails 1.0.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: /opt/grails		
		
Base Directory: /home/gus/scree/gentoo-test
Environment set to development
Note: No plugin scripts found
Running script /opt/grails/scripts/RunApp.groovy
    [mkdir] Created dir: /home/gus/.grails/1.0.1/projects/gentoo-test/classes
  [groovyc] Compiling 6 source files to /home/gus/.grails/1.0.1/projects/gentoo-test/classes
    [mkdir] Created dir: /home/gus/.grails/1.0.1/projects/gentoo-test/resources/grails-app/i18n
[native2ascii] Converting 10 files from /home/gus/scree/gentoo-test/grails-app/i18n to /home/gus/.grails/1.0.1/projects/gentoo-test/resources/grails-app/i18n
     [copy] Copying 1 file to /home/gus/.grails/1.0.1/projects/gentoo-test/classes
     [copy] Copying 1 file to /home/gus/.grails/1.0.1/projects/gentoo-test/resources
     [copy] Copying 1 file to /home/gus/.grails/1.0.1/projects/gentoo-test
Running Grails application..

...

Open http://localhost:8080 in a web browser of your choice (or use wget of course! :}) and see Grails in all it's glory.

Where To Go From Here

Follow the Grails Quick Start to get a feel for some of the out-of-the-box capabilities that Grails brings. You'll find the User Guide helpful when you've got stuck in and need more info.

Grails also has a wealth of plugins that are worth investigating - run grails list-plugins to see what's out there.

To be effective with Grails you'll need to get comfortable with Groovy - I thoroughly recommend Groovy in Action (affectionately known as GinA :)

Nabble.com provides a useful searchable archive of the Grails mailing lists which are worth subscribing to. You've also got the Grails WIKI and the JIRA issue tracker.

Good Luck from here! If you have any questions/comments/rants/praise/other please feel free to ping me.

--Gus