It’s been about a year since I embarked on providing high quality Debian packages of Groovy, Grails and Griffon to the Ubuntu community. The initial learning curve was rather steep, involving a full immersion in the Debian Policy documentation, as well as getting to grips with a myriad of command line tools. Many tools performing similar functions, but each with subtle differences. The method that I finally settled upon is surely not the only way of performing this task, although it produces high quality lintian compliant packages.

This post is my attempt to share what I have learned, and to expose the process that I have set in place. I’m doing this so that others can also get involved, and potentially take over from me one day when I’m through with delivering these packages. Not that I intend to stop delivering these packages any time soon! :-)

Setting up the Environment

Firstly, it is assumed that you will be using a brand new installation of Ubuntu (or Mint) Linux. At the time of writing, 12.04 Precise Pangolin is the flavour of the day and will be used to for the entire setup.

Next, you will need to ensure that you have a GPG key set up in order to sign your packaged artefacts. Because this is outside the scope of this article, you can refer to Ubuntu GNU Privacy Guard Howto for this.

Without any further ado, let’s get right into it and get our environment set up for action. Open a terminal and run the following on the command line:

$ sudo apt-get install build-essential devscripts ubuntu-dev-tools debhelper \
  dh-make diff patch cdbs quilt gnupg fakeroot lintian  pbuilder piuparts

Now that we have all dependencies in place we can proceed by creating a work directory and downloading the latest version of Grails (2.1.0 was the latest at the time of writing).

$ mkdir ~/packages
$ cd packages
$ wget http://dist.springframework.org.s3.amazonaws.com/release/GRAILS/grails-2.1.0.zip

Unzip the folder and rename it to the format $PACKAGE-$VERSION-$RELEASE. Then we create a tarball out of the archive with the format $PACKAGE-$VERSION_$RELEASE.orig.tar.gz:

$ unzip grails-2.1.0.zip
$ mv grails-2.1.0 grails-2.1.0-1.0
$ tar zcvf grails-2.1.0_1.0.orig.tar.gz grails-2.1.0-1.0

A word about the components of the name here:

• PACKAGE: grails, groovy or griffon
• VERSION: 2.1.0 in this case
• RELEASE: Our package version. This component is a number we use to track the VERSION up to the point when it comes out of RC or beta and into final release. eg. RC1 = 0.1, RC5 = 0.5, GA = 1.0, 2.1.RC4 = 0.4, 2.1.GA = 1.0

We should now have a folder named grails-2.1.0-1.0 and a file named grails-2.1.0_1.0.orig.tar.gz in our work directory. It is crucial to stick to these exact naming conventions.

Now we need to clone the Debian metadata that the packaging tools will use to build our packages from GitHub, placing them inside our exploded zip folder.

$ git clone git@github.com:freshgroovy/grails-ubuntu.git
$ mv grails-ubuntu/debian grails-2.1.0-1.0/

It is noteworthy that GitHub repositories exist for grails-ubuntu, griffon-ubuntu and groovy-ubuntu.

We now have all the files in place, so time to start editing what we have. Step into the grails-2.1.0-1.0 folder. Next we’ll add a few lines of code at the head of the startGrails file (same for startGriffon or startGroovy):

$ cd grails-2.1.0-1.0
$ vi bin/startGrails

1
2
3
4
5
6
7
8
9
10

# Added by groovy-dev for Ubuntu PPA
export GRAILS_HOME="/usr/share/grails/2.1.0"
export JAVA_HOME="$(update-alternatives --query java | grep Value | sed 's_^Value: __g' | sed 's_/jre/bin/java__g')"

##############################################################################
##                                                                          ##
##  Grails JVM Bootstrap for UN*X                                           ##
##                                                                          ##
##############################################################################
...

Next we’ll update all files in the debian folder with appropriate VERSION, RELEASE, PRIORITY and DATE:

1
2
3
4
5
6
7
8

VERSION="2.1.0"
RELEASE="1.0"
PRIORITY="50"
DATE="$(date -R)"
find "debian/" -type f | xargs sed -i "s/VERSION/${VERSION}/g"
find "debian/" -type f | xargs sed -i "s/RELEASE/${RELEASE}/g"
find "debian/" -type f | xargs sed -i "s/PRIORITY/${PRIORITY}/g"
find "debian/" -type f | xargs sed -i "s/DATE/${DATE}/g"

We then rename the install, pre- and post- hooks appropriately:

1
2
3

mv "debian/grails-VERSION.install" "debian/grails-${VERSION}.install"
mv "debian/grails-VERSION.postinst" "debian/grails-${VERSION}.postinst"
mv "debian/grails-VERSION.prerm" "debian/grails-${VERSION}.prerm"

Now that we have performed all edits, it’s time to run the Debian build scripts:

1

dpkg-source --commit

This will generate some patch files under debian/patches for the startGrails file that we edited. Simply save the patch file with a name such as start_grails and exit.

We now build the package:

1

debuild -S -sa

The final step is to run this build in a virtual environment with the pbuilder tool. We will use a handy wrapper for pbuilder that will allow you to run it for multiple distributions of Ubuntu. The wrapper script can be found as part of the ubuntu-dev-tools package:

1
2
3

pbuilder-oneiric create  #only on the first time!
pbuilder-oneiric update
pbuilder-oneiric build "${PACKAGE}-${VERSION}_${RELEASE}-1ubuntu0.dsc"

If all is well, our package is now in the pbuilder folder and we should be able to install it with a simple:

$ sudo dpki -i /path/to/my/deb/grails-2.1.0_1.0-1ubuntu0_all.deb

Congratulations! You’ve built and installed your own Grails package.

The Easier Way

Of course there is an easier way: This entire process can be driven by a script. This script can be found in the ubuntu-release-scripts repository on GitHub and simply needs to be added to your path.

Running without parameters reveals some simple help:

$ groovy2dev

Usage: groovy2dev <zipfile> <package> <version> <release> <priority>

To package the 2.1.0 release of Grails as described earlier, we simply run the following command:

$ groovy2dev /path/to/grails-2.1.0.zip grails 2.1.0 1.0 50

This should run through the entire process described above and result in a grails .deb package in the pbuilder output folder.

One Final Thing

Once packaged, we are ready to release the package into the wild. We do this by issuing one single command on the .changes file that was generated earlier. This can only be done if you have the appropriate authorisation from the groovy-dev group on launchpad.

$ dput ppa:groovy-dev/grails grails-2.1.0_1.0-1ubuntu0_source.changes

Any feedback or questions are welcome so feel free to leave a comment.

Enjoy!