The new version comes with a couple of important bug fixes, improved closure expression validation and IDE support for IntelliJ >= 12.1 and GGTS >= 3.2.0.

Issue Overview

• #42 Improved compilation error messages
• #41 Fix copyright text
• #40 Provide GDSL and DSLD files for improved IDE support Feature
• #39 @Grab with GContracts fails in groovyConsole and @CompileStatic Bug
• #38 ContractClosureWriter should generate final classes

GContracts is available in the central Maven repository [0] and at Github [1].

[0] GContracts @ Maven repo
[1] GContracts @ Github

Here is a short preview for the upcoming 1.2.11 release.

In the very beginning, GContracts was based on a “hidden” feature in Groovy 1.7: closure annotation parameters. As this was kind of a hidden trick, there was only accidental support for this feature in IDEs. This changed with the release of Groovy 1.8, which officially released the feature of closure annotation parameters.

Another missing piece besides supporting closure annotation parameters was the possibility to let the IDE know about implicit variables added by GContracts during compile-time. This was especially needed for the @Ensures annotation’s result and old variables.

With the ongoing support for custom DSLs, I am happy to announce improved support in this area for the Eclipse Groovy/Grails Toolsuite (GGTS) and Intellij 12.1 [1] and upwards.

Unresolved Variables EVERYWHERE

As of today, GContracts provides only a small – yet powerful – set of annotations: @Requires, @Ensures and @Invariant

@Ensures – the annotation to define postconditions – is a special case. It adds two implicit variables to the closure code block: old and result. result is available in the case the target method is a non-void instance method and resembles the method’s return value. old is a map and resembles all parameter and property values before a method call.

The problem with implicitly introduced variable names in DSLs is their support in IDEs. Up to now, neither IntelliJ nor Eclipse did recognize the old and result variables.

With the upcoming 1.2.11 release, GContracts comes with bundled GDSL and DSDL files, to extend the IDE inference mechanisms:

Note, the inferred result variable is typed with the declared return type of the corresponding method. In the case of a void method, the variable is not available in the auto-completion dialog.

At time of writing, the old variable is simply typed as being of type java.util.Map. I will try to add some more logic to provide this variable only when it makes sense in the current context.

And now?

I am looking forward to release 1.2.11 until the next couple of days. There is “only” one bug pending being a class-loading issue, d’oh

[0] GContracts – Programming by Contract for Groovy
[1] IntelliJ YouTrack – IDEA 98773

Compiler Configuration Script with –configscript

The --configscript option can be used to specify a compiler configuration script. Before 2.1, the CompilerConfiguration class could be used to change certain configuration settings:

def configuration = new CompilerConfiguration()
// apply some configuration settings ...

def shell = new GroovyShell(configuration)

Although we could set the CompilerConfiguration for a given GroovyShell, there was no way to do so for the Groovy compiler groovyc. As of Groovy 2.1, --configscript can be used to point to an external Groovy DSL script that has access to an implicit configuration variable of type CompilerConfiguration.

In order to specify a Groovy configuration file we need to create a configuration Groovy script, let’s call it config.groovy:

import org.codehaus.groovy.control.customizers.ImportCustomizer

def imports = new ImportCustomizer()
imports.addImports('org.some.*')

configuration.addCompilationCustomizers(imports)

The script above adds package org.some.* to the default imports. As you can see, Groovy adds an implicit variable called configuration. At runtime, this is the actual compiler configuration our DSL script needs to interact with.

A New Builder: CompilerCustomizationBuilder

Groovy 2.1 comes even with a new DSL for the --configscript configuration file. The builder in the background is CompilerCustomizationBuilder. For the star import example given above, with the builder the configuration file would look like this:

import org.codehaus.groovy.control.customizers.ImportCustomizer
import org.codehaus.groovy.control.customizers.builder.CompilerCustomizationBuilder

CompilerCustomizationBuilder.withConfig(configuration) {
    new ImportCustomizer().addImports('org.some.*')
}

or we could – due to the fact that Groovy already adds a star import for import static CompilerCustomizationBuilder.* – reduce our code to:

// implicitly added ...
// import static org.codehaus.groovy.control.customizers.builder.CompilerCustomizationBuilder.*

import org.codehaus.groovy.control.customizers.ImportCustomizer

withConfig(configuration) {
    new ImportCustomizer().addImports('org.some.*')
}

The compiler customization is not restricted to adding CompilerCustomizer implementations. It can be used to add AST transformations on every artifact that is compiled with the -configscript option. Let’s say we wanted to apply the newly introduced static compilation feature with @CompileStatic to every class in our project. The compiler configuration script can look like this:

// implicitly added ...
// import static org.codehaus.groovy.control.customizers.builder.CompilerCustomizationBuilder.*

withConfig(configuration)  {
    ast(groovy.transform.CompileStatic)
}

We can even go further. In addition, CompilerCustomizationBuilder provides a way to register certain source files with AST transformations.

Let’s say we wanted to couple all files with a *.sgroovy extension to the @StaticCompile annotation. This could be done in the configuration script using a SourceAwareCustomizerFactory:

withConfig(configuration) {
    source(extension: 'sgroovy') {
        ast(groovy.transform.CompileStatic)
    }
}

When running e.g. groovyc with this configuration script and a *.sgroovy file we have @StaticCompile automatically applied on all newly compiled classes.

There are even more features that can be used with this builder. As a starting point, take a look at the registerFactories method in CompilerCustomizationBuilder:

registerFactory("ast", new ASTTransformationCustomizerFactory())
registerFactory("customizers", new CustomizersFactory())
registerFactory("imports", new ImportCustomizerFactory())
registerFactory("inline", new InlinedASTCustomizerFactory())
registerFactory("secureAst", new SecureASTCustomizerFactory())
registerFactory("source", new SourceAwareCustomizerFactory())

As you can see, there is even a ImportCustomizerFactory predefined. A look at the documentation shows how to use it in the compiler configuration DSL:

import org.codehaus.groovy.control.customizers.builder.CompilerCustomizationBuilder

def builder = new CompilerCustomizationBuilder()
builder.imports {
    star 'org.some'
}

Conclusion

Groovy 2.1 comes with a new Groovy compiler configuration parameter: -configscript. In conjunction with the new CompilerCustomizationBuilder it can be used to specify a Groovy script holding the compiler configuration DSL code as supported by the builder. This is good news for AST transformation authors as the hook can be used for embedding AST transformations or registering AST transformations on specific source files.

[0] Groovy 2.1 Relase Notes

The Delegate and The Closure

Groovy supports the concept of closures [1]. One closure feature is to being able to modifiy the closure code delegation mechanism. Once a closure is defined, its delegate object can be changed by setting the delegate property:

def me = 'André'
def closure = { greet me }

closure.delegate = new Greeter()

closure()

In the code sample above, we change the delegate to an instance of Greeter.

class Greeter {
    void greet(def another)  {
        println "Hello, $another"
    }
}

When executing the code in groovConsole [2], it prints

No signature of method: ConsoleScript1.greet() is applicable for argument types: (java.lang.String) values: [André]

Ups, obviously we did forget one little thing: the resolve strategy. By setting the resolve strategy of a single groovy.lang.Closure instance, we can chose between the following types:

• OWNER_ONLY: delegate method calls to the owner of the closure (e.g. the instance creating the closure instance)
• DELEGATE_ONLY: delegate method calls to the delegate of the closure
• OWNER_FIRST: delegate to the owner first, then the delegate
• DELEGATE_FIRST: delegate to the delegate first, then the owner
• SELF_ONLY: method calls are resolved against the closure instance only

In our example the resolve strategy should be set to DELEGATE_FIRST or OWNER_FIRST, as we call Greeter#greet and have a reference to the script variable me.

def me = 'André'
def closure = { greet me }

closure.delegate = new Greeter()
closure.resolveStrategy = Closure.DELEGATE_FIRST

closure()

What’s the deal?

Modifying the closure resolving strategy is a powerful technuique for DSL and Groovy library authors. For example, take a look at GContracts [3], a Design by Contract extension for Groovy, that uses closure annotations to specify contracts on methods and classes:

@Invariant({ elements != null })
class Stack {

    List elements

    @Ensures({ is_empty() })
    def Stack()  {
        elements = []
    }

    // ...

    @Ensures({ last_item() == item })
    def push(T item)  {
       elements.add(item)
    }

    @Requires({ !is_empty() })
    @Ensures({ last_item() == item })
    def replace(T item)  {
        remove()
        elements.add(item)
    }

    @Requires({ !is_empty() })
    @Ensures({ result != null })
    T remove()  {
        elements.remove(count() - 1)
    }

    String toString() { elements.toString() }
}

def stack = new Stack()

Another example is definitely Gradle [4], the Groovy-based build automation framework:

task hello << {
    println 'Hello Earth'
}
hello.doFirst {
    println 'Hello Venus'
}
hello.doLast {
    println 'Hello Mars'
}
hello << {
    println 'Hello Jupiter'
}

When working with one of these libraries in IntelliJ or Eclipse, one shortage becomes immediately apparent: whenever a custom delegate object is set, IntelliJ or Eclipse do not provide code completion for closure code, except the IDE of choice comes with specific framework support.

@DelegatesTo comes into play

As of version 2.1, Groovy provides a way for DSL, library and framework authors to hint IDEs in the right direction: the @DelegatesTo annotation. In its simplest application, @DelegatesTo has only a single default argument of type java.lang.Class. Back to our previous example, we have to introduce an indirection as @DelegatesTo can only be applied on parameters:

class Greeter {
    void greet(def another)  {
        println "Hello, $another"
    }
}

class Marketplace {

    void interactions(@DelegatesTo(Greeter) Closure closure) {
        closure.delegate = new Greeter()
        closure.resolveStrategy = Closure.DELEGATE_FIRST
        closure()
    }
}

def marketplace = new Marketplace()

def me = 'André'
marketplace.interactions{
    greet me
}

We can even provide more meta-data by specifying the strategy attribute:

// ...
void interactions(@DelegatesTo(strategy = Closure.DELEGATE_FIRST, value = Greeter) Closure closure) {
// ...

The DelegatesTo.Target Annotation

@DelegatesTo has one last additional meta-data that can be applied on method paramters: the @DelegatesTo.Target annotation.

Whenever an actual parameter will be set as the closure’s delegate object, the Target can be used to document this circumstance:

// ...
void interactions(@DelegatesTo.Target Greeter greeter, @DelegatesTo(Greeter) Closure closure) {
    closure.delegate = greeter // <-- the argument will be set as closure delegate
    // ....
}

// ...

For the special case of having multiple parameters of the same type, there is a target annotation element type that allows for specifying unique String ids.

// ...
void interactions(@DelegatesTo.Target('id') Greeter greeter, @DelegatesTo(target = 'id') Closure closure) {
    closure.delegate = greeter // <-- the argument will be set as closure delegate
    // ....
}

// ...

Note, in the example above we did not specify a class for the closure parameter. This can be omitted since the type will be inferred from the greeter parameter.

IDE Support

Besides supporting IDEs the @DelegatesTo information is evaluated by @TypeChecked and @StaticCompile.

As of writing, neither IntelliJ nor the Groovy Eclipse plugin comes with support for @DelegatesTo, but it is expected to become supported in the near future:

Conclusion

DSL, library and Groovy framework authors should definitely consider adding @DelegatesTo to their method meta-data. Besides the benefit of better IDE support (think of code completion), additional meta-data is utilized by Groovy 2.0′s @TypeChecked and @StaticCompile to catch even more typing errors.

It’s a small step for third party authors, but a big step for Groovy IDE support.

Update

As announced today (2013-02-07), @DelegatesTo is supported by the Groovy-Eclipse plugin. Snapshot builds are available at http://docs.codehaus.org/display/GROOVY/Eclipse+Plugin#EclipsePlugin-DevelopmentBuilds

[0] GROOVY-5714: @DelegatesTo annotation for IDEs/TypeChecker
[1] Wikipedia: Closure
[2] grooovyConsole
[3] GContracts
[4] Gradle – Build Automation Framework

X Annotations -> 1 Annotation

The use case for the annotation collector is simple: we want to define a meta-annotation that includes a handful of other annotations. By the way, it’s not just “other annotations” but we also want to include AST transformation annotations like @ToString, @EqualsAndHashCode, @Immutable etc. (for an introduction to Groovy’s AST transformation annotations, you might want to start here [1]).

Let’s say we have the use case to apply @ToString and @Immutable to several classes in our project. With Groovy 2.1 we can use @AnnotationCollector to avoid code duplication and create a single annotation alias:

@AnnotationCollector([ToString, Immutable])
@interface ValueObject {}

Our self-defined @ValueObject can now be applied on Groovy classes:

@ValueObject
class UpperLimit {}

What happens during compile-time is, the @ValueObject is detected to be an @AnnotationCollector annotation, thus it is replaced by its meta annotations:

@ValueObject
class UpperLimit {}

becomes

@ToString
@Immutable
class UpperLimit {}

One last thing: @AnnotationCollector provides a way to specify annotation type element values. For example, the @ToString annotation comes with various attributes to configure the toString() output:

public @interface ToString {

    String[] excludes() default {};
    // ...
    String[] includes() default {};
    // ...
}

Let’s say we want to ignore all id properties on our value objects. Although our @ValueObject has no attributes defined, we can ignore that fact as the @AnnotationCollector AST transformation modifies the custom annotation accordingly:

@ValueObject(excludes = ['id'])
class UpperLimit {}

One special case is when multiple annotation elements have different types and the same names, or just the same names. If they have different types, compilation will fail. Otherwise, the last annotation collect by @AnnotationCollector will deemed as appropriate while others being ignored.

Advanced Features

@AnnotatioCollector even supports adding custom AST transformation code by specifying its processor annotation element. A custom annotation collector must inherit from org.codehaus.groovy.transform.AnnotationCollectorTransform and override the visit() method.

A complete example by Guillaume Laforge can be found at Github [2].

Conclusion

The new @AnnotationCollector annotation can be used to group several (AST xform) annotations to a single annotation. Further, its functionality can be extended by custom AST transformation code.

[0] GROOVY-5821: Provide a way to assemble an annoation consisting of several other
[1] Compile-time Metaprogramming – AST Transformations
[2] Github AnnotationCollectorTransform Example by Guillaume Laforge

Type checking helps us identify typing errors, or references to undeclared methods as shown in the following code example:

@groovy.transform.TypeChecked
class Greeter {
    void greet(String other)  {
        println "Hello, $oher".toUppercase()
    }
}

With @TypeChecked we get the following errors during compile-time:

[Static type checking] - The variable [oher] is undeclared.
 at line: 4, column: 26

[Static type checking] - Cannot find matching method groovy.lang.GString#toUppercase(). Please check if the declared type is right and if the method exists.
 at line: 4, column: 17

If you ever had the case where a typing error caused serious errors on your Grails production system, you will surely value the use of this annotation.

Custom Type Checking Extensions

Groovy 2.1 takes the conecpt of type checking even further and introduces a way to add custom type checking extensions. Custom type checking extensions are a great way to add compile-time checks that go beyond standard compile validations.

As an example, let’s assume we have a type checked Sql utility class to access our relational database. The Sql class has a method named eachRow receiving a SQL query of type String as first argument:

sql.eachRow( 'select * from tableName' ) { println "$it.id -- ${it.firstName} --" }

As you can see in the code above, the SQL query is of type String. Syntactical errors we only occur at runtime.

With a custom type checking extension we can evaluate the specified SQL query at compile-time. The first step is to add a Groovy script to our class-path, let’s call it SqlExtension.groovy. Groovy 2.1 comes with a custom type checking DSL that can be used within these scripts.

Let’s see how a SQL parsing type checking extension could look like:

@Grab(group='net.sf.jsqlparser', module='jsqlparser', version='0.8.0')
import net.sf.jsqlparser.parser.CCJSqlParserManager

afterMethodCall { mc ->
  def receiver = mc.receiver
  if (!isVariableExpression(receiver)) return

  def method = getTargetMethod(mc)

  if (classNodeFor(groovy.sql.Sql) == getType(receiver) && method.name == 'eachRow') {
    def argList = getArguments(mc)
    if (argList && isConstantExpression(argList[0])) {
        def pm = new CCJSqlParserManager();
        def sqlQuery = argList[0].text

        try {
            pm.parse(new StringReader(sqlQuery))
            } catch (e) {
                addStaticTypeError("SQL query is not valid: " + e, argList[0])
            }
        }
    }
}

And that’s it. It has to be noted that the @Grab annotation can be used inside type checking extension scripts.

The example above uses the JSQLParser [2] library but we could of course use any other third party library.

The afterMethodCall is one of the event hooks that can be used in a type checking extension. As can be seen, its only argument is an instance of MethodCall which we use to retrieve the target method’s name and the methods receiver type. Once we’re sure that it’s a call to Sql#eachRow(...), we can check the first argument for being a constant expression (ie. a constant String). After we retrieved the constant, we can fire up our SQL parser and see if the statement is syntactically correct. Let’s add the SqlExtension.groovy on a test class:

import groovy.sql.Sql

@groovy.transform.TypeChecked(extensions = ['SqlExtension.groovy'])
class SqlTest {

    def test() {
    	def db = [url:'jdbc:hsqldb:mem:testDB', user:'sa', password:'', driver:'org.hsqldb.jdbc.JDBCDriver']
 	def sql = Sql.newInstance(db.url, db.user, db.password, db.driver)

 	sql.eachRow('select * frm PROJECT') { row ->
	    println row
	}
    }
}

Obviously, the specified SQL argument string is syntactically not correct. Let’s see if we get a compile error when compiling this class:

org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
SqlTest.groovy: 10: [Static type checking] - SQL query is not valid: net.sf.jsqlparser.JSQLParserException
 @ line 10, column 16.
    		sql.eachRow('select * frm PROJECT') { row ->
                  ^

It worked! We have our first custom type checking extension that checks SQL statements for their syntactical correctness. Cool, isn’t it?

GTCES

GroovyTypeCheckingExtensionSupport [3] is the class that handles type extension script and therefore defines all available event hooks. During its initialization phase, GTCES adds a custom script base class to our extension script and adds some default imports:

CompilerConfiguration config = new CompilerConfiguration();
config.setScriptBaseClass("org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport.TypeCheckingDSL");

ImportCustomizer ic = new ImportCustomizer();
ic.addStarImports("org.codehaus.groovy.ast.expr");
ic.addStaticStars("org.codehaus.groovy.ast.ClassHelper");
ic.addStaticStars("org.codehaus.groovy.transform.stc.StaticTypeCheckingSupport");

config.addCompilationCustomizers(ic);

The METHOD_ALIASES constant show all event hooks currently available:

private final static Map METHOD_ALIASES = Collections.unmodifiableMap(
            new HashMap() {{
                put("onMethodSelection", "onMethodSelection");
                put("afterMethodCall", "afterMethodCall");
                put("beforeMethodCall", "beforeMethodCall");
                put("unresolvedVariable", "handleUnresolvedVariableExpression");
                put("unresolvedProperty", "handleUnresolvedProperty");
                put("unresolvedAttribute", "handleUnresolvedAttribute");
                put("methodNotFound", "handleMissingMethod");
                put("afterVisitMethod", "afterVisitMethod");
                put("beforeVisitMethod", "beforeVisitMethod");
                put("afterVisitClass", "afterVisitClass");
                put("beforeVisitClass", "beforeVisitClass");
                put("incompatibleAssignment", "handleIncompatibleAssignment");
                put("setup","setup");
                put("finish", "finish");
            }}
    );

If you seek to implement custom type checking extensions, you should have a closer look at GCTES as this is starting point for the extension DSL.

Conclusion

Groovy 2.1 adds custom type checking extensions to its @TypeChecked annotation. Type checking extensions can be used for additional type checks that go beyond standard compiler validations and offer a great way to perform domain-specific compile-time checks in DSLs or, more general, Groovy code!

UPDATE

Cédric Champeau released the type checking extensions documentation. If you want to implement a type checking extension, this is the place where to get a deeper insight into that topic.

[0] groovy.transform.CompileStatic
[1] groovy.transform.TypeChecked
[2] JSQLParser Library @ Sourceforge
[3] org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport

Groovy 2.1.0 has been released today. This release comes with important additions for DSL authors, third party libraries and improved IDE support. Here are the changes as announced at Greach by Guillaume Laforge today [0]:

• complete invoke dynamic support when running with the “indy” JAR on JDK 7
• @DelegatesTo annotation: to help IDEs and the static type checker and compiler to know that method calls in a method parameter closure are delegated to another parameter of the method — nice for DSLs like in Gradle build files
• custom type checking extensions: so you can type check your DSLs at compile-time with your own logic
• a meta-annotation system: which allows you to define a new annotation actually combining several others — which also means being able to apply several AST transformations with a single custom annotation
• compiler configuration script: to let you define various configuration options for the Groovy compiler, like specifying custom file extensions, various compilation customizers to apply, etc.
  compilation customizer builder: a special builder for specifying compilation customizers

I’ve decided to cover the most important features in separate blog posts:

Groovy 2.1: Type Checking Extensions
Groovy 2.1: The @AnnotationCollector Annotation
Groovy 2.1: groovyc -configscript
Groovy 2.1: The @DelegatesTo Annotation

If you wanna get in touch with 2.1 you can either download it at [1] or – and that is a way better alternative – use GVM, the Groovy enVironment Manager [2].

Keep on Groovying’

[0] Groovy 2.1 Release Notes
[1] Groovy 2.1.0 Download
[2] GVM – The Groovy enVironment Manager

Documentation excerpt:

Iterates through the given Collection, passing in the initial value to the 2-arg closure along with the first item. The result is passed back (injected) into the closure along with the second item. The new result is injected back into the closure along with the third item and so on until the entire collection has been used. Also known as foldLeft or reduce in functional parlance.

Let’s say we wanted to compute the sum of a list of numbers:

assert 28 == [1, 2, 3, 4, 5, 6, 7].inject(0, { sum, value -> sum + value })

The code above iterates over all list elements, and passes the current list element as the second actual argument to the given closure. The first argument resembles the intermediary result.

1. run: sum == 0 (initial value), value == 1
2. run: sum == 1, value == 2
3. run: sum == 3, value == 3
4. run: sum == 6, value == 4
// …

inject does not only work for scalar values, but for arbitrary data types:

assert [2, 4, 6, 8, 10, 12, 14] == [1, 2, 3, 4, 5, 6, 7].inject([], { list, value -> list << value * 2; list })

In fact, we could even simplify the code above to use the second inject without the initial value argument:

assert 28 == [1, 2, 3, 4, 5, 6, 7].inject { sum, value -> sum + value }

Conclusion

The Collection#inject default Groovy method (DGM) comes in handy whenever we need to iterate over a collection and pass some intermediary result from iteration to iteration. It can be used either be specifying an initial value and a closure, or with just a single closure as argument.

[0] DGM: Collection#inject

Printing the AST tree

I came accross this posting [0] by Cédric Champeau, himself one of the Groovy core comitters. In the mailing list Hamlet D’Arcy pointed to AstNodeToScriptAdapter [1], a class utilized by the AST browser to compile Groovy code to a given compile phase and decompile the result back to Groovy code.

One way to add logging the AST tree to the console with this class would be to introduce a compilation customizer [2] and simply pass the current ClassNode instance to the script adapter:

class LoggingCompilationCustomizer extends CompilationCustomizer {

  final PrintStream out

  LoggingCompilationCustomizer(CompilePhase compilePhase, PrintStream out) {
    super(compilePhase)
    this.out = out
  }

  void call(SourceUnit source, GeneratorContext context, ClassNode classNode) throws CompilationFailedException {

    StringWriter writer = new StringWriter()
    new AstNodeToScriptVisitor(writer).visitClass(classNode)

    out.println writer
  }
}

Once the customizer is defined it can be used by registering it with a GroovyShell object:

def config = new CompilerConfiguration()
config.addCompilationCustomizers(new LoggingCompilationCustomizer(CompilePhase.SEMANTIC_ANALYSIS, System.out))

shell = new GroovyShell(config)

Conclusion

The AstNodeToScriptVisitor is a class used by the Groovy AST browser to render Groovy code from a specific compile phase. When debugging AST transformations it can sometimes be an advantage to dump the actual AST source code to immediately see AST issues.

[0] Nabble: AST browser from code
[1] groovy.inspect.swingui.AstNodeToScriptAdapter
[2] org.codehaus.groovy.control.customizers.CompilationCustomizer

At the time of writing, GVM namely supports Groovy, Grails, Griffon, Gradle and Vert.x. GVM itself is a command-line tool based on the Bash shell, depending on curl and unzip to be pre-installed on target systems only.

Get it while its hot

The installation is actually a single curl command-line call. Open your command-line and type the following line:

curl -s get.gvmtool.net | bash

the following output should indicate a successful installation

Thanks for using                                                     

_____/\\\\\\\\\\\\__/\\\________/\\\__/\\\\____________/\\\\_
 ___/\\\//////////__\/\\\_______\/\\\_\/\\\\\\________/\\\\\\_
  __/\\\_____________\//\\\______/\\\__\/\\\//\\\____/\\\//\\\_
   _\/\\\____/\\\\\\\__\//\\\____/\\\___\/\\\\///\\\/\\\/_\/\\\_
    _\/\\\___\/////\\\___\//\\\__/\\\____\/\\\__\///\\\/___\/\\\_
     _\/\\\_______\/\\\____\//\\\/\\\_____\/\\\____\///_____\/\\\_
      _\/\\\_______\/\\\_____\//\\\\\______\/\\\_____________\/\\\_
       _\//\\\\\\\\\\\\/_______\//\\\_______\/\\\_____________\/\\\_
        __\////////////__________\///________\///______________\///__

                                       Will now attempt installing...

Looking for a previous installation of GVM...
Looking for JAVA_HOME...
Validating JAVA_HOME...
Looking for unzip...
Looking for curl...
Installing gvm scripts...
Creating candidate directories...
Attempting to update bash profile...
All done!

Once this is done and you restart the terminal, the gvm script should be available in your path.

Installing and Switching Between Multiple Groovy Versions (<= awesome)

Once the gvm command is available, we can call gvm help to see an overview of the supported commands and arguments:

Usage: gvm <command> <candidate> [version]

   command    :  install, uninstall, list, use, current, version, default, selfupdate, broadcast or help
   candidate  :  groovy, grails, griffon, gradle, vert.x
   version    :  optional, defaults to latest stable if not provided

Now let’s say we wanted to install multiple Groovy versions. With GVM this ain’t no rocket science anymore. To install the most current version of Groovy (or one of the other supported software kits), you have to execute

gvm install groovy

Downloading: groovy 2.0.5

[...]

Installing: groovy 2.0.5
Done installing!

Do you want to use groovy 2.0.5 now? (Y/n): Y

groovy -version
Groovy Version: 2.0.5 JVM: 1.6.0_37 Vendor: Apple Inc. OS: Mac OS X

To install another version of the Groovy programming language, we just have to append the appropriate version number:

gvm install groovy 1.8.8

And now comes the crux: switching between Groovy, Grails, Griffon, Gradle or Vert.x versions is done with a single line in the command-line:

gvm use groovy 1.8.8

groovy -version
Groovy Version: 1.8.8 JVM: 1.6.0_37 Vendor: Apple Inc. OS: Mac OS X

Conclusion

Switching between different development branches with different framework versions (e.g. of Grails) has been with some pain until now. GVM as a great tool for easily keeping track of and switching between multiple software kit versions.

[0] Marco Vermeulen @ Twitter
[1] GVM – Project Homepage