// Copyright 2017 the original author or authors.
//
// Licensed 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.

[[installation]]
= Installing Gradle

You can install the Gradle build tool on Linux, macOS, or Windows.
This document covers installing using a package manager like SDKMAN! or Homebrew, as well as manual installation.

Use of the <<gradle_wrapper.adoc#sec:upgrading_wrapper,Gradle Wrapper>> is the recommended way to upgrade Gradle.

You can find all releases and their checksums on the link:{website}/releases[releases page].

[[sec:prerequisites]]
== Prerequisites
Gradle runs on all major operating systems and requires only a link:{jdkDownloadUrl}[Java Development Kit] version {minJdkVersion} or higher to run. To check, run `java -version`. You should see something like this:

----
❯ java -version
java version "1.8.0_151"
Java(TM) SE Runtime Environment (build 1.8.0_151-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.151-b12, mixed mode)
----

Gradle ships with its own Groovy library, therefore Groovy does not need to be installed. Any existing Groovy installation is ignored by Gradle.

Gradle uses whatever JDK it finds in your path. Alternatively, you can set the `JAVA_HOME` environment variable to point to the installation directory of the desired JDK.

== Installing with a package manager

link:http://sdkman.io[SDKMAN!] is a tool for managing parallel versions of multiple Software Development Kits on most Unix-like systems (macOS, Linux, Cygwin, Solaris and FreeBSD). We deploy and maintain the versions available from SDKMAN!.

----
❯ sdk install gradle
----

link:http://brew.sh[Homebrew] is "the missing package manager for macOS".

----
❯ brew install gradle
----

Other package managers are available, but the version of Gradle distributed by them is not controlled by Gradle, Inc. Linux package managers may distribute a modified version of Gradle that is incompatible or incomplete when compared to the official version (available from SDKMAN! or below).

<<#sec:installation_next_steps,↓ Proceed to next steps>>


== Installing manually

=== Step 1. link:{website}/releases[Download] the latest Gradle distribution

The distribution ZIP file comes in two flavors:

 - Binary-only (bin)
 - Complete (all) with docs and sources

Need to work with an older version? See the link:{website}/releases[releases page].

=== Step 2. Unpack the distribution

==== Linux & MacOS users

Unzip the distribution zip file in the directory of your choosing, e.g.:

[subs="attributes"]
----
❯ mkdir /opt/gradle
❯ unzip -d /opt/gradle gradle-{gradleVersion}-bin.zip
❯ ls /opt/gradle/gradle-{gradleVersion}
LICENSE  NOTICE  bin  getting-started.html  init.d  lib  media
----

==== Microsoft Windows users

Create a new directory `C:\Gradle` with **File Explorer**.

Open a second **File Explorer** window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content. Drag the content folder `gradle-{gradleVersion}` to your newly created `C:\Gradle` folder.

Alternatively, you can unpack the Gradle distribution ZIP into `C:\Gradle` using an archiver tool of your choice.

=== Step 3. Configure your system environment

To run Gradle, the path to the unpacked files from the Gradle website need to be on your terminal's path. The steps to do this are different for each operating system.

==== Linux & MacOS users

Configure your `PATH` environment variable to include the `bin` directory of the unzipped distribution, e.g.:

[subs="attributes"]
----
❯ export PATH=$PATH:/opt/gradle/gradle-{gradleVersion}/bin
----

Alternatively, you could also add the environment variable `GRADLE_HOME` and point this to the unzipped distribution.  Instead of adding a specific version of Gradle to your `PATH`, you can add `__$GRADLE_HOME__/bin` to your `PATH`.  When upgrading to a different version of Gradle, just change the `GRADLE_HOME` environment variable. 

==== Microsoft Windows users

In **File Explorer** right-click on the `This PC` (or `Computer`) icon, then click `Properties` -> `Advanced System Settings` -> `Environmental Variables`.

Under `System Variables` select `Path`, then click `Edit`. Add an entry for `C:\Gradle\gradle-{gradleVersion}\bin`. Click OK to save.

Alternatively, you could also add the environment variable `GRADLE_HOME` and point this to the unzipped distribution.  Instead of adding a specific version of Gradle to your `Path`, you can add `__%GRADLE_HOME%__/bin` to your `Path`.  When upgrading to a different version of Gradle, just change the `GRADLE_HOME` environment variable. 

<<#sec:installation_next_steps,↓ Proceed to next steps>>


[[sec:running_and_testing_your_installation]]
== Verifying installation

Open a console (or a Windows command prompt) and run `gradle -v` to run gradle and display the version, e.g.:

[subs="attributes"]
----
❯ gradle -v

------------------------------------------------------------
Gradle {gradleVersion}
------------------------------------------------------------

(environment specific information)

----

If you run into any trouble, see the <<troubleshooting.adoc#sec:troubleshooting_installation,section on troubleshooting installation>>.

You can verify the integrity of the Gradle distribution by downloading the SHA-256 file (available from the link:{website}/releases[releases page]) and following these <<gradle_wrapper.adoc#sec:verification,verification instructions>>.

[[sec:installation_next_steps]]
== Next steps

Now that you have Gradle installed, use these resources for getting started:

 * Create your first Gradle project by following the link:https://guides.gradle.org/creating-new-gradle-builds/[Creating New Gradle Builds] tutorial.
 * Sign up for a link:{website}/training/intro-to-gradle/[live introductory Gradle training] with a core engineer.
 * Learn how to achieve common tasks through the <<command_line_interface.adoc#command_line_interface,command-line interface>>.
 * <<build_environment.adoc#build_environment,Configure Gradle execution>>, such as use of an HTTP proxy for downloading dependencies.
 * Subscribe to the link:https://newsletter.gradle.com/[Gradle Newsletter] for monthly release and community updates.
