##### Project Documentation

- About groovy
- Project Info
- Project Reports
  - Project License
  - PMD Report
  - Metrics
  - Source Xref
  - Test Xref
  - Unit Tests
  - FAQs
- Development Process

## Frequently Asked Questions

General

1. What is Groovy?
2. Why Groovy? Why don't you just use Jython, JRuby, bsh, rhino, pnuts, ...
3. What are the dependencies for Groovy?
4. What is the licence for Groovy?
5. How can I contribute to Groovy?

Using Groovy

1. How can I embed Groovy into my Java application
2. How can I compile Groovy to bytecode either at runtime or build time?
3. How can I run Groovy scripts?
4. I get errors when trying to run groovy, groovysh or groovyConsole. Whats wrong?
5. How can I add stuff to the classpath when running things in groovysh or groovy?

Questions about the Groovy language

1. Things work if I use Suns conventions and put { on the same line, but if I add a new line things break?

GDK (Groovy Development Kit)

1. What new methods are available on standard JDK classes?
2. What are Closures?
3. How does operator overloading work?

Groovy Developers FAQ

1. How do I build Groovy from the source code?
2. All the unit test cases take a while to run. Can I do a quicker build?
3. All the unit test cases take a while to run. Can I run just some of the tests?

Groovy Committers FAQ

1. I've just been given CVS commit access; what should I do now?
2. What are the development rules?
3. Where is the continuous integration build?
4. How do I use codehaus's CVS?

## General

General

What is Groovy?

  Groovy is a powerful high level language for the Java platform which compiles down to Java bytecode.

  Think of it as a Ruby or Python like language that is tightly integrated with the Java platform - allowing you the same powerful and concise coding syntax as Ruby or Pyton but allowing you to stay on the JVM and protect your investment in J2SE, J2EE and all the plethora of great useful Java code out there.

Why Groovy? Why don't you just use Jython, JRuby, bsh, rhino, pnuts, ...

  Firstly ports of existing languages like Python, Ruby, Smalltalk and JavaScript to the JVM are a good thing and we welcome them. If you already use and/or are fond of these languages please be our guests to use the Java-port of them.

  One of the main design goals of Groovy is to be a scripting language for Java developers to use. So we wanted to reuse both Java's semantics and the whole set of J2SE APIs rather than introduce a port of a different language with different semantics and APIs to learn and implement/maintain.

  e.g. in Groovy, java.lang.Object is the root of the object hierarchy, Object.equals(), Object.hashCode() and Comparable are used for comparions and lookups of objects, that java.util.List and java.util.Map are used for collections, Java Beans are fully supported and that Java and Groovy classes are interchangable inside the JVM. Groovy is built on top of the J2SE APIs, rather than having 2 parallel platforms etc.

  In other words we wanted the Groovy language to be very easy to pick up if you're already a Java developer and for there to be a very small number of new APIs to learn. By this statement we're not implying that Python / Ruby / JavaScript are hard to learn per se - its just there's more to know, things are more different and there's more APIs to learn.

  Think of Groovy as a Ruby or Python like language that is tightly integrated with the Java platform (as opposed to the Unix/Posix command shell and C-libraries) - allowing you the same powerful and concise coding syntax as Ruby or Pyton but allowing you to stay on the JVM and protect your investment in J2SE, J2EE and all the plethora of great useful Java code out there without any adapter layers or parallel API sets etc.

  There is a more detailed set of comparisions to other languages here

What are the dependencies for Groovy?

  As well as Java 1.4 and the Groovy jar we also depend at runtime on the ASM library

What is the licence for Groovy?

  Groovy is open source using a BSD / Apache style licence

How can I contribute to Groovy?

  There are many ways you can help and contribute to Groovy. Please read the contributing guide

## Using Groovy

Using Groovy

How can I embed Groovy into my Java application

  Please see this description of embedding Groovy

How can I compile Groovy to bytecode either at runtime or build time?

  Please see this description of compiling Groovy

How can I run Groovy scripts?

  Please see this description of running Groovy code

I get errors when trying to run groovy, groovysh or groovyConsole. Whats wrong?

  Groovy depends on JDK 1.4 or later. Common errors people have when trying to run Groovy is that there's an old groovy jar on the CLASSPATH somewhere (have you checked in java/lib/ext?) or that JAVA_HOME points to an old JDK before JDK 1.4.x.

  For more help please see this description of running Groovy code

How can I add stuff to the classpath when running things in groovysh or groovy?

  You can add things to your $CLASSPATH environment variable. Another popular option is to create a .groovy/lib directory in your home directory and add whatever jars you want to be available by default.

  e.g. if you wish to connect to your favourite JDBC database and do some scripting with it then add your JDBC driver to ~/.groovy/lib.

## Questions about the Groovy language

Questions about the Groovy language

Things work if I use Suns conventions and put { on the same line, but if I add a new line things break?

  When using closures with method calls we have some syntax sugar in Groovy which is sensitive to whitespace (newlines to be preceise). Please see this description in common gotchas for a full description

## GDK (Groovy Development Kit)

GDK (Groovy Development Kit)

What new methods are available on standard JDK classes?

  Please see this description of the Groovy JDK

What are Closures?

  Please see this description of closures

How does operator overloading work?

  Please see this description of operator overloading

## Groovy Developers FAQ

Groovy Developers FAQ

How do I build Groovy from the source code?

  We use Maven as the build tool for Groovy. From a source distribution, or CVS checkout you need to install Maven as per the instructions on Maven's website.

  Basically this involves setting the JAVA_HOME and MAVEN_HOME environment variables and adding JAVA_HOME/bin and MAVEN_HOME/bin to your path. Once you have installed Maven you can build Groovy and run all the unit tests by typing the following in a command line shell

      		maven

All the unit test cases take a while to run. Can I do a quicker build?

  You can do a full clean binary build without running the unit tests via..

      		maven rebuild

  If you want to run all the unit test cases inside the same JVM, which saves quite a bit of time although the output isn't as nice, you can use this command.

      	    maven groovy:test-quick

All the unit test cases take a while to run. Can I run just some of the tests?

  Or to run a specific test case you can do

      		maven test:single -Dtestcase=CharsetToolkitTest

  Where you pass in the name of a test case. If you want to run a single unit test case written in Groovy in a slightly faster way you can try this...

      		maven groovy:test-single -Dtest=src/test/groovy/SomeTest.groovy

  or to run tests matching a certain pattern...

      		maven test:match -Dtestmatch=Foo*Test.*

  There is more details on unit testing groovy scripts here

## Groovy Committers FAQ

Groovy Committers FAQ

I've just been given CVS commit access; what should I do now?

  If you've just been given CVS commit access see if you can do a commit. You'll need to do an SSH based CVS checkout. Once you've done this you should be able to edit the project.xml file and change yourself from being a committer to being a developer. Then try commit that and see if it works. If you need more help, please ask on IRC or email.

What are the development rules?

  Please try and write unit test cases for all new features, patches or fixes.

  Its considered very bad form to commit code that doesn't compile or breaks the unit tests. We run a continuous integration build (using DamageControl) to ensure that the build in CVS works and the tests pass.

  Its useful to subscribe to all 3 mail lists, especially groovy-scm which shows all CVS commits along with any continuous integration build failures and JIRA issue changes.

Where is the continuous integration build?

  We run DamageControl at codehaus. If a build fails a nag mail is sent to the groovy-scm mail list. You can watch DC do its stuff using your IRC client and joining #damagecontrol.

  You can also view the latest DC build logs or see the test case results

How do I use codehaus's CVS?

  Codehaus uses SSH for CVS access. So from the command line you'd type

      export CVS_RSH=ssh

  Or if you're using eclipse you might find this plugin handy. I use it with extssh2 and it works great!