Overview

What is it?

The custom-gradle package is a custom Gradle distribution, based on Gradle 1.4, with an extra init script.

You won’t usually need to download this manually because if you use a Gradle wrapper then it should fetch it from your Artifactory server automatically.

The reasons for using a custom distribution of Gradle as opposed to using the original versions from the Gradle website are:

  • to include the custom init script which does several useful things;

  • to speed up downloads of Gradle by using an in-house repository.

How to use it

You need a Gradle wrapper whose properties file refers to a URL corresponding to a published version of custom-gradle. This would normally be published to an Artifactory server. See the First Steps page for an example of how to set this up.

Once you’re using a Gradle Wrapper that refers to custom-gradle then an init-script will automatically be applied. This adds a little bit of extra functionality to the standard Gradle distribution, described below.

Plugin Base URL

Since version 7.0.0, the Holy Gradle custom wrapper uses an environment variable to allow the same build script to be used at multiple sites, even if they do not share an Artifactory server.

The environment variable HOLY_GRADLE_REPOSITORY_BASE_URL must be set to the base URL of the Artifactory web service at your site (for example, https://artifact-server.example-corp.com/artifactory/). This URL is used to download the plugins, and can also be used as a base for URLs in the repositories section of your buld.gradle, to get your own projects dependencies.

Setup of Base URL

From version 7.5.0 of the Gradle wrapper, gw.bat will attempt to set this variable based on the file gradle/base-url-lookup.txt. You can add this file to your source code, or it may be available as part of a wrapper-starter-kit in your organisation — see Setting up a Gradle Wrapper for details. The file should be a text file with several lines of the format "DNS-suffix Base-URL ", for example as follows.

foo.com http://artifactory.foo.com/artifactory/
bar.com https://artifacts.internal.bar.com/artfactory/

The DNS suffix is taken from the output of ipconfig.exe.

For versions before 7.5.0, you must set this manually in your user environment settings. You should not need to change it unless your server name changes, or you are working at a different site.

Project Property for Base URL

From version 7.2.0, the property project.holyGradleRepositoryBase is automatically added to your project. This contains the value of the environment variable, guaranteed to end with a slash (/ ). See the Example build script for how this can be used.

Applying Holy Gradle Plugins

The gplugins DSL from the init script makes it easier to use the custom Gradle plugins such as intrepid-plugin and my-credentials-plugin. To use it put the following at the top of your build.gradle, with the plugin versions of your choice.

buildscript {
    gplugins.use "intrepid:7.2.5"
    gplugins.use "my-credentials:7.2.5"
}
gplugins.apply()

Note that the custom-gradle-core-plugin will automatically be applied whenever you use the gplugins DSL.

Caution
The gplugins DSL should only be used for Holy Gradle plugins. Using it for other plugins may result in unexpected side effects. Notably, if you are using snapshot versions of the Holy Gradle plugins you will need to make a matching snapshot of all plugins available. Other plugins should be applied using the standard Gradle Plugins API

user.gradle

One of features of the init script is to automatically load user.gradle files that are in the same directory as the build script. Simply create a Gradle script named user.gradle or build_script.user.gradle , where build_script is the name of the build script. For example, consider the following directory structure.

<workspace>
|   build.gradle
|   build.user.gradle
|   settings.gradle
+---framework
|   |   framework.gradle
|   |   framework.user.gradle
|   +---src
|   |   ...
|   +---libs
|       ...
+---my_app
    |   my_app.gradle
    |   user.gradle
    +---src
    |   ...
    +---libs
        ...

In the above example:

  • settings.gradle will be loaded and evaluated before any of the other build scripts. (See settings file.)

  • build.user.gradle will be loaded and evaluated immediately after build.gradle.

  • framework/framework.user.gradle will be loaded and evaluated immediately after framework/framework.gradle.

  • my_app/user.gradle will be loaded and evaluated immediately after my_app/my_app.gradle.

Build Script Names

Build scripts are normally called build.gradle. In this example we have some build scripts called framework.gradle and my_app.gradle. This is possible because settings.gradle is auto-generated by the intrepid-plugin and contains some code that allows sub-project build scripts to be named build.gradle or subproject.gradle where subproject is the name of the sub-project — that is, the name of the directory in which the build script lives.