//////////////////////////////////////////

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

//////////////////////////////////////////

= Apache Groovy
The Groovy development team
:revdate: 24-02-2014
:build-icon: http://ci.groovy-lang.org:8111/app/rest/builds/buildType:(id:Groovy_Jdk7Build)/statusIcon
:noheader:
:groovy-www: http://groovy-lang.org/
:groovy-ci: http://ci.groovy-lang.org?guest=1
:jdk: http://www.oracle.com/technetwork/java/javase/downloads
:bintray-latest-version-image: https://api.bintray.com/packages/groovy/maven/groovy/images/download.png
:bintray-latest-version-link: https://bintray.com/groovy/maven/groovy/_latestVersion
:bintray-watch-image: https://www.bintray.com/docs/images/bintray_badge_color.png
:bintray-watch-link: https://bintray.com/groovy/maven/groovy/view?source=watch

[.left.text-left]
image::https://raw.githubusercontent.com/groovy/artwork/master/medium.png[]
{groovy-www}[Groovy] is a powerful, optionally typed and dynamic language, with static-typing and static compilation capabilities, for the Java platform aimed at multiplying developers’ productivity thanks to a concise, familiar and easy to learn syntax.

It integrates smoothly with any Java program, and immediately delivers to your application powerful features, including scripting capabilities, Domain-Specific Language authoring, runtime and compile-time meta-programming and functional programming. 

== Downloading

Latest Groovy version is available on Bintray image:{bintray-latest-version-image}[Bintray latest version, link={bintray-latest-version-link}]

Binary distribution links are on the package page.

Maven, Gradle and Ivy dependency declaration snippets are available on specific files of a particular module.

image:{bintray-watch-image}[Get automatic notifications about new "groovy" versions link={bintray-watch-link}]

== Obtaining the Source

You don't need the source code to use Apache Groovy but if you wish to explore its inner workings or build it for yourself there are two ways to obtain the source files.

=== Checking out from Version Control

Apache Groovy uses Git. The official Git repository is at:

    https://git-wip-us.apache.org/repos/asf/groovy.git

And a mirror is hosted on Github:

    https://github.com/apache/groovy

The Github mirror is read-only and provides convenience to users and developers to explore the code and for the community to accept contributions via Github pull requests.

Simply `git clone` the repo (or the repo you forked via the github website) and you will have the complete source.

=== Unpacking the src distribution

Alternatively, you can download the source distribution and unpack it.

If obtaining the source from the source distribution and you intend to build from source,
you also need to https://gradle.org/downloads/[download] and install http://gradle.org/[Gradle] and
use the downloaded Gradle to execute one bootstrap step.

==== Bootstrapping Gradle

As mentioned in the previous paragraph, if you download the source distribution
you need to bootstrap Gradle. This isn't needed if you clone from the Github repo.

Each version of Groovy is built and tested using a specific version of Gradle.
That version is specified by the `gradle_version` property defined in the `gradle.properties`
file within the root directory. Luckily you shouldn't need to know that version and,
after bootstrapping, you should use the `gradlew` command which will ensure the
correct version is always used.

The version of Gradle used for the bootstrap step has some flexibility though in general
you might need to download a version similar to the version of Groovy the build is
expecting.

To bootstrap Gradle, at the top directory of your unpacked source, run the command:

    gradle -b wrapper.gradle wrapper

On Unix-like systems, use `./gradle`.
If the version of Gradle you have installed is close to the required version,
you might be able to get away without the `-b wrapper.gradle` above, but if in
doubt leave it in.

*NOTE*: At this point, the Gradle wrapper should be set up and from now on you should use
the `gradlew` command instead of `gradle`. (On Unix-like systems, use `./gradlew`).

== Building from Source

Build is image:{build-icon}[build status, link={groovy-ci}].

To build you will need:

* {jdk}[JDK 8+]

To build everything using Gradle, use the following command (`./gradlew` on Unix-like systems):

    gradlew clean dist

Note: The gradlew command automatically downloads the correct Gradle version if needed, you do not need to download it first.

This will generate a distribution similar to the zip you can download on the Groovy download page.

To build everything and launch unit tests, use:

    gradlew test

If you want to launch one unit test, use this. <TestClassName> is like `groovy.GroovyMethodsTest`.

    gradlew :test --tests <TestClassName>

To build from IntelliJ IDEA:

    gradlew jar idea

Then open the generated project in IDEA.

To build from Eclipse:

    gradlew jar eclipse

Then open the generated project and the generated subprojects in Eclipse. But be aware that Eclipse tends to be more limited in its ability to reproduce a Gradle build structure. The generated project files may contain a circular dependency which may or may not prevent Eclipse from using them. It depends on the Eclipse version, if this is an issue or not.

To build the documentation (Groovy Language Documentation):

    gradlew assembleAsciidoc

All code samples of the documentation guide are pulled from actual test cases. To run a single documentation test case, take for example `src/spec/test/semantics/PowerAssertTest.groovy`

    gradlew testSinglePowerAssertTest

(Note the omission of package name: class is `semantics.PowerAssertTest` but only `PowerAssertTest` is added to `testSingle`.)

== InvokeDynamic support

The Groovy build supports the JVM instruction `invokedynamic`. If you want to build Groovy with invokedynamic, you can use the project property `indy`:

    gradlew -Pindy=true clean test

Please note that the following Gradle tasks generate both indy and non indy variants of the jars, so you don't need to use the system property:

* dist
* install
* uploadArchives

== Continuous Integration Server

The official CI server runs {groovy-ci}[here] and is sponsored by http://www.jetbrains.com[JetBrains].

== License

Groovy is licensed under the terms of the http://www.apache.org/licenses/LICENSE-2.0.html[Apache License, Version 2.0]