This page describes how to use Artifactory and the Holy Gradle for the first time.

System Requirements

Artifactory runs as a web service which can be accessed through any modern browser or with tools such as the Holy Gradle. The easiest way to use it is through such tools. The web interface is mainly useful for investigating problems.

The Holy Gradle is a set of plugins for the Gradle tool, which is a Java application. They have only been tested on the following platforms.

  • Windows 7 (and Windows Server 2008 R2), Windows 8.1, Windows 10

  • Java 7 (JRE or JDK)

Preparation

Windows

Holy Gradle before 7.8.0

If you are using a version of the Holy Gradle before 7.8.0 and you are a local Administrator on your system, then you need to turn User Account Control off. This is because the Holy Gradle plugins create symbolic links, and Windows disables this by default for Administrator accounts. On Windows 8.1 and above you also need to run the Holy Gradle with Administrator priveleges — that means, from an Administrator Command Prompt.

From version 7.8.0 the Holy Gradle creates directory junctions instead, which do not have these permission problems.

Java

Install Java 7 on your system if it is not already installed—usually under C:\Program Files\Java. This can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase7-521261.html. Most projects will only need the JRE; you only need the JDK if your project uses custom pre-buikt code in a buildSrc folder, as described at http://gradle.org/docs/1.4/userguide/organizing_build_logic.html#sec:build_sources. Windows 7 comes with an older version of Java pre-installed, usually at C:\Windows\System32\java.exe. To make sure that Gradle uses the correct version, do one of the following things.

  1. Set the JAVA_HOME environment variable to the root folder of your Java 7 installation, for example, C:\Program Files\Java\jre7 or C:\Program Files\Java\jdk1.7.0_55. If the Holy Gradle needs to co-exist with other applications that use the JAVA_HOME variable and a different version of Java you can set HOLY_GRADLE_JAVA_HOME instead.

  2. Make sure that the bin folder in your Java install location is first on your PATH. To check the versions of java.exe on your path you can run where java, which lists them in order; for example: 

    C:\Users\hughg>where java
C:\Program Files\Java\jre7\bin\java.exe
C:\Windows\System32\java.exe
Note
If you are setting up a continuous integration (or "autobuild") server, the version of Java used by the autobuild service (for example, Jenkins) may not be the same as the one used when you log on as a normal user. Also, if the service is written in Java and launches more Java processes, those may use a different Java installation. To check or change the version in use, consult the autobuild software documentation. A tool such as SysInternals Process Explorer can also be useful to check which Java executable a process is running.

Accessing Artifactory

For versions of the Holy Gradle’s Gradle wrapper before 7.5.0, you must manually set up an environment variable pointing to an organisation-specific server where the plugins can be downloaded. (From 7.5.0 this can be committed with your project’s source code — see Setting up a Gradle Wrapper for details.)

For manual setup, first find the web address of your local Artifactory server. With a default Artifactory installation, the base URL will have the server name followed by /artifactory/. Browsing to this URL will show you any publicly available modules, and allow you to log in.

You should then set the environment variable HOLY_GRADLE_REPOSITORY_BASE_URL to this same, site-specific URL, as described at Plugin Base URL.

You must contact your site administrator to get login details and set up permissions.

Running the Holy Gradle

Gradle Setup

Gradle automatically downloads files for you and stores them in a cache in the Gradle User Home directory. This defaults to .gradle in your home directory, but you can override the location by setting the GRADLE_USER_HOME environment variable. You may wish to move this if your home directory is on a small or slow drive. Also, Gradle never clears out this cache: you must do so manually, from time to time.

Setting up a Gradle Wrapper

Although Gradle can be installed system-wide, usually you will add some "bootstrap" files to your project, known as a Gradle wrapper. The wrapper includes a batch file which will download a Gradle distribution if necessary, then run it using that download location, so you do not need to modify your PATH. The wrapper files should be committed to the source control repository for each project which uses Gradle. When you run the wrapper, it generates configuration files which should not be added to source control, so you should

  • download a wrapper,

  • unzip it in the root folder of your working copy,

  • add and commit the unzipped files to source control,

  • then run the wrapper for the first time.

The Gradle distribution, plus the dependencies for all your projects, are stored in the Gradle User Home directory.

There are no publicly available pre-built releases of the Holy Gradle, or custom Gradle wrappers. The source code contains a separate wrapper-starter-kit project in a sub-folder, which can build such a custom Gradle wrapper.

If you want to experiment with Gradle without adding it to an existing project, you can just unzip the wrapper and run gw.bat from inside it.

Note

If you access the Internet through a proxy then you will need to pass the -Dhttp.proxyHost=server -Dhttp.proxyPort=port arguments the first time you run gw.bat on your machine, so it can download the standard Gradle distribution. If you do not, you may see an error such as the following.

Exception in thread "main" java.net.ConnectException:
Connection refused: connect

You will also need to do this if you ever delete the folder %GRADLE_USER_HOME%\wrapper\dists, which holds the downloaded distributions of Gradle.

Running Gradle

Once you have the wrapper unzipped in your project folder, you can run the following to see the command-line options for Gradle.

gw --help

Or run this to see the default list of tasks for Gradle.

gw tasks

You will not be able to use Holy Gradle features until you have a build.gradle file which applies the plugins.

Note
The Holy Gradle only supports running from within the usual Windows Command Prompt. Using other shells such as PowerShell, or Unix-style shells from Cygwin etc., is not supported.

A Minimal Holy Gradle Build File

In the folder where you unzipped the wrapper, create a build.gradle file with the following content. (Of course, you can use a different plugin version number if you want.)

buildscript {
    def ver = "7.2.4"
    gplugins.use "intrepid:${ver}"
    gplugins.use "my-credentials:${ver}"
}
gplugins.apply()

Now when you run gw tasks you should see additional tasks listed.

Editing Gradle Files

Gradle is controlled by several text files in the folder where you run it.

  • build.gradle contains the main configuration for your project. Many projects only need this file.

  • settings.gradle is used when you have multiple projects, to tell Gradle where to find them, relative to the root project. The Holy Gradle will generate this for you based on sourceDependencies in your build.gradle.

  • gradle.properties is a file in the Java properties format which is useful if you need to share simple values across multiple projects.

You can edit these files with any text editor. If your editor supports syntax highlighting for the Groovy language, you can also apply that to .gradle files.

Note

For Notepad++ you can use the following steps to install syntax highlighting.

  1. Download and unzip this user-defined language file.

  2. In Notepad++ go to "Language → Define your language…" and "Import…" the XML file.

  3. Re-open any Gradle files and you should see them highlighted. If not choose "Groovy" from the bottom of the "Language" menu.

Future versions of this page will include instructions for editing Gradle files using IntelliJ IDEA, to get pop-up help and type-checking.

Next Steps

Once you have this working, you may want to read the Overview and/or the page on Workflow With Gradle and Artifactory.