Appendix A. Installing Groovy
Installing Groovy is easy. This appendix shows you how to do it, with a review of the various options involved.
A.1. Installing a JDK
Groovy generates Java bytecodes that are interpreted by a Java virtual machine. This means you have to have Java installed in order to install Groovy. You need a full Java Development Kit (JDK), rather than a Java Runtime Environment (JRE). You only need the Standard Edition (SE) of Java, rather than the Enterprise[1] Edition.
1 Just as an aside, when did the word business get deprecated in favor of the word enterprise? Is it a Star Trek thing? Does being an Enterprise Architect mean you design starships for a living? Are Enterprise Java Beans used when making coffee on a starship?
The official JDK for Java SE is available from Oracle at http://mng.bz/83Ct. At the time of this writing, the current version is Java SE 7u25 (Java 7, update 25), but Groovy works on any version of Java 1.5 and above.
Be sure to set an environment variable called JAVA_HOME to point to the installation directory. You also probably want to add the bin folder under JAVA_HOME to your path.
On Windows that will look like this:
C:> set JAVA_HOME="C:Program FilesJavajdk1.7.0" C:> set PATH=%JAVA_HOME%in;%PATH%
Those commands will set the JAVA_HOME and PATH properties in the local shell. To set them everywhere, right-click My Computer, select Properties, click Advanced, and then click Environment Variables. Add them as System variables, and start a new shell.[2]
2 The specifics of the process will be slightly different on different Windows versions, but the concepts are the same. Set the variables as System environment variables, and start a new shell because Windows won’t update an existing one.
On Macs or Unix flavors, the same settings are
$ export JAVA_HOME=/Library/Java/... $ export PATH=$PATH:$JAVA_HOME/bin
There are too many variations on these statements to count, depending on directory structure and version numbers, but the principles are always the same: install Java, set the JAVA_HOME variable to point to it, and add its bin subdirectory to your path.
A.2. Installing Groovy
Assuming you’ve installed Java, installing Groovy is easy. Again, there are several options, but the basic process comes down to downloading and unzipping the distribution, setting a GROOVY_HOME environment variable, and adding its bin subdirectory to your path.
If you’re not a fan of automated installers or you don’t have root privileges on your machine, you can download a zipped, binary distribution of Groovy directly. The current version can always be found at http://groovy.codehaus.org/Download. You can get either the binary release or the source release (or both). Either way, unzip the download into a directory of your choice.
On Windows, following the same pattern as the Java installation, it’s
C:> set GROOVY_HOME=C:Groovygroovy-2.1.6 C:> set PATH=%GROOVY_HOME%in;%PATH%
On a Mac or Unix, the same process is
$ export GROOVY_HOME=... $ export PATH=$PATH:$GROOVY_HOME/bin
If you don’t mind installers, a good one is available for Windows. An EXE installer is available on the same download page, which will install Groovy to a directory of your choice, set the GROOVY_HOME variable for you, and add the bin folder underneath it to your path. It also offers to install some optional libraries for you, which are useful and do not interfere with your regular installation in any way. I’ve been using the Windows installer at client sites for years and have never had a problem with it. It will, by the way, notify you if you don’t have a JAVA_HOME environment variable set.
If you’re on a Mac or other Unix box, you have other convenient alternatives available. First, there’s a MacPorts (www.macports.org) option. Run
$ sudo port install groovy
That will download and install the latest version. If you prefer HomeBrew (http://mxcl.github.io/homebrew), the relevant command is
$ brew install groovy
That, too, will download the latest version, install it, and create soft links to the executable scripts in your path.
The other major alternative is to use GVM, the Groovy enVironment Manager (http://gvmtool.net). This is the best option if you plan to switch versions at any time. GVM is installed using curl, with this command:
$ curl –s get.gvmtool.net | bash
GVM assumes you are using a bash shell, but the same process works for most Unix flavors. It also works on Windows if you install Cygwin. See the web page for details.
The great advantage of GVM is that it makes switching versions almost trivially easy. If you have GVM installed, you can find out which versions of Groovy are available by typing
$ gvm list groovy
You can install the latest one like this:
$ gvm install groovy
If you supply a version number to the install command, you can select which version of Groovy to install. You can switch from one version of Groovy to another using
$ gvm use groovy [version]
If the version you request isn’t installed, GVM will download and install it for you. In my own work, I don’t switch Groovy versions that often, but I switch Grails versions frequently and the same tool works for Groovy, Grails, Griffon, and a few other software distributions. GVM installs software under a .gvm folder in your home directory, so you should set the GROOVY_HOME variable to point there. For example, on my Mac, I have
$ export GROOVY_HOME=/Users/kousen/.gvm/groovy/current
That’s useful because switching versions through GVM updates the current link. I don’t have to explicitly add that folder to my path, though, because the tool adds soft links to a bin folder already in my path.
A.3. Testing your installation
The easiest way to see if your Groovy installation is working is to try out the Groovy shell or the Groovy console. If you type
$ groovysh
you should get a response like this:
Groovy Shell (2.1.5, JVM: 1.7.0_11) Type 'help' or 'h' for help. ------------------------------------ groovy:000> println 'Hello, World!' Hello, World! ===> null groovy:000>
The Groovy shell is essentially the REPL[3] for Groovy (or even Java). Note that the response here is null because the println command has a void return type.
3 Read-Eval-Print-Loop, discussed further in appendix B.
The Groovy console is a bit more useful. Start it with this command:
$ groovyConsole
On Windows, that spawns a separate process. On Macs and Unix flavors, the groovyConsole command locks up that particular shell, so you might want to run it in the background by appending an ampersand (&). The result looks like figure A.1.
Figure A.1. The Groovy console, which comes with the Groovy distribution. Remember to go under the View menu and select Auto Clear Output On Run to make the tool far more practical.
The Groovy console appends its results to the output window, which can be problematic. Worse, if you type a line that throws an exception,[4] the result window stops scrolling, even if you later fix the error. My recommendation, therefore, is to select the last entry under the View menu, entitled Auto Clear Output On Run. That will make the console clear the output every time you execute a script. The Groovy console includes an Abstract Syntax Tree browser, among other things. It’s useful even if you normally work with an IDE.
4 I know you would never do that, but you know what your coworkers are like. They’re capable of anything.
Speaking of IDEs, the next section documents their current level of support.
A.4. IDE support
If you’re an Eclipse user, the Groovy Eclipse plugin is state-of-the-art. To add it to an existing Eclipse distribution, use the update string found on the page at http://groovy.codehaus.org/Eclipse+Plugin. The plugin can also be found at the Eclipse Marketplace.
Eclipse has an annoying bug that requires the installation directory to be writable by the user. Groovy Eclipse cannot be installed into a so-called “shared” install, which often includes the c:Program Files directory on Windows. Simply move your Eclipse installation somewhere else, and you’ll be fine.
If you only want to use Groovy, the Groovy Eclipse plugin is sufficient. If you want to use Grails as well, then you can install the Groovy and Grails Tool Suite, GGTS. GGTS is a set of plugins based on Eclipse and is managed by Pivotal (formerly SpringSource). You can download GGTS from www.springsource.org/downloads/sts-ggts. Be careful: the site lists the STS downloads first and the GGTS downloads below that.
Both STS and GGTS come from the same code base. The difference is the initial set of plugins. GGTS comes with both the Groovy Eclipse plugin and Grails support that provides an entire Grails perspective, various wizards, keyboard shortcuts, and more.
The major IDE alternative is IntelliJ IDEA. The page at www.jetbrains.com/idea/features/groovy_grails.html discusses its Groovy and Grails features. It even has Griffon support, which is pretty unusual at this point. IntelliJ IDEA is the tool of choice of most of the core Groovy, Grails, and Griffon team members, but it’s a commercial product and therefore requires a license.[5] If you participate in an open source project or make presentations at your local Java/Groovy/Grails user group, you can get a free license, which is one more reason to participate in the open source world.
5 There’s a community edition that didn’t used to offer Grails support, but that may be changing. Be sure to check the website for current capabilities.
The web page at http://groovy.codehaus.org/IDE+Support lists plugins and support for other IDEs, ranging from Emacs to TextMate to UltraEdit. If you can’t find the one you’re interested in, be sure to ask on the mailing lists. Somebody will know and tell you where to find what you need.
A.5. Installing other projects in the Groovy ecosystem
The GVM tool currently will install and manage Groovy, Grails, Griffon, and Gradle distributions, among other projects.[6] That’s the easiest way to proceed if you’re on a Mac or Unix distribution. Again, on Macs both HomeBrew and MacPorts have options for the same set of projects. On Windows, Groovy has the installer mentioned earlier in this chapter.
6 The current list of candidates is Groovy, Grails, Griffon, Gradle, Lazybones, Vertx, and Groovyserv.
Grails is always a ZIP file that you download and unzip. Then you set an environment variable (GRAILS_HOME in this case) and add the bin subdirectory to your path. Griffon and Gradle work much the same way.
Note that all of these projects have their own source code repositories on GitHub. You can always clone the distribution and build it yourself, though that tends to get involved. See the respective project pages for details. One of the best things about GitHub is that you can browse the source code without downloading anything. It’s a good idea to get familiar with the test cases contained in the various projects, because they’re the executable documentation for each. Web pages can go out of date, but continuous integration servers execute test cases all the time. When they break everybody knows about it, and they get fixed right away.
The only other project discussed extensively in this book is Spock. Spock is a library rather than a framework and is usually installed as part of a Gradle (or Maven) build. Its source code is on GitHub, too.