========

 Gradle

========

.. contents::

   :local:

Getting help

============

::

  $ gradle --help

Working with subprojects

========================

Getting list of subprojects::

  $ gradle projects

Running build on specific subproject::

  $ gradle :$SUB:clean

  $ gradle -p $SUB clean

If subproject lies in hierarchy::

  $ gradle :$SUB/$SUBSUB:clean

  $ gradle -p $SUB/$SUBSUB clean

Skip building dependent modules, build just current module::

  $ gradle -a build

  $ gradle --no-rebuild build

  $ gradle -a :client:build

Creating multilevel project::

  $ mkdir $PRJROOT

  $ cd $PRJROOT

  $ mkdir lvl1 lvl1/lvl2

  $ touch build.gradle lvl1/build.gradle lvl1/lvl2/build.gradle

  $ { echo include "'lvl1'"; echo include "'lvl1/lvl2'"; } >settings.gradle

  $ gradle projects

``settings.gradle`` can include per line or a list of subprojects::

  include 'sub1', 'sub2', 'sub2'

  include 'lvl1'

  include 'lvl1/lvl2'

https://docs.gradle.org/current/userguide/intro_multi_project_builds.html

http://stackoverflow.com/questions/16976214/gradle-build-only-one-module

Running completely isolated build

=================================

To avoid using global cache and for really clean build use::

  $ gradle --no-daemon --gradle-user-home ./.gradle.local

Managing tasks

==============

List tasks::

  $ gradle tasks

Getting list of supported tasks in each subproject::

  $ gradle tasks --all

Getting help on task::

  $ gradle help --task build

  $ gradle -q help --task build

Similar but to each task::

  $ gradle model

Skip task during build with ``-x`` option::

  $ gradle -x test build

  $ gradle -x :core:build :client:build

Build sources

=============

::

  $ gradle compileJava

  $ gradle compileTestJava

Build with additional options and checks::

  compileJava {

    options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

  }

  compileTestJava {

    options.encoding = 'UTF-8'

    options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

  }

To apply change recursively to subprojects::

  subprojects {

      tasks.withType(JavaCompile) {

          options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

      }

  }

Run main class

==============

::

  $ gradle run

Run tests

=========

To run test::

  $ gradle test

To skip tests in build::

  $ gradle -x test build

Better solution involves passing system property with ``build.gradle``::

  test.onlyIf { ! Boolean.getBoolean('skip.tests') }

To run tests with additional registered checks::

  $ gradle check

.. note::

   ``--rerun-tasks`` option *specifies that any task optimization is ignored*.

   In that way you may rerun tests even if there are no changed files::

     $ gradle test --rerun-tasks

By default ``System.out`` and ``Sysyem.err`` redirected so you wouldn't see

anything about test on console.

Quick way to see test output is::

  $ gradle test -i

Alternatively configure ``test`` task::

  test {

    testLogging {

      events "passed", "skipped", "failed" //, "standardOut", "standardError"

      showExceptions true

      exceptionFormat "full"

      showCauses true

      showStackTraces true

      showStandardStreams = false

    }

  }

Stopping server

===============

::

  $ gradle --stop

List project dependencies

=========================

List of project execution dependencies (it also download dependencies)::

  $ gradle dependencies

  $ gradle dependencies --configuration compile

  $ gradle dependencies -p $SUBPROJ

  $ gradle :$SUBPROJ:dependencies

  $ gradle :$SUBPROJ:dependencies --configuration testCompile

List of project plugin dependencies::

  $ gradle buildEnvironment

  $ gradle buildEnvironment -p $SUBPROJ

  $ gradle :$SUBPROJ:buildEnvironment

Paths to dependencies can be printed via task::

  task printDepPaths {

    doLast { configurations.runtime.each { println it } }

  }

All dependencies can be copied to single directory via task::

  task copyRuntimeLibs(type: Copy) {

    into "lib"

    from configurations.runtime

    // from configurations.testRuntime - configurations.runtime

  }

List project properties

=======================

::

  $ gradle properties

  $ gradle :$SUBPROJ:properties

  $ gradle properties -p $SUBPROJ

Dry tun

=======

``-m`` option allow parsing build scripts without actually executing them::

  $ gradle -m clean compile

Bootstrap project structure

===========================

This creates simple project with Gradle boilerplate files::

  $ gradle init --type java-library

To convert Maven project (with ``pom.xml`` file) to Gradle project use::

  $ gradle init --type pom

https://docs.gradle.org/current/userguide/build_init_plugin.html

  Official docs on ``init`` plugin.

Gradle wrapper

==============

With Gradle v2.4 and above::

  $ cd $PROJ

  $ gradle wrapper --gradle-version 3.5

It will add ``gradle/wrapper/gradle-wrapper.jar`` to project root and next call

to ``./gradlew`` download Gradle distribution from ``distributionUrl`` parameter

from ``gradle/wrapper/gradle-wrapper.properties`` file. Dictribution will be

cached in ``~/.gradle/wrapper/dists.gradle/wrapper/dists`` directory so next

calls won't require download.

Alternatively define task::

  task wrapper(type: Wrapper) {

      gradleVersion = '2.0'

  }

For increase security add ``distributionSha256Sum`` parameter to

``gradle-wrapper.properties`` file. Distribution SHA-256 sum can be obtained via

``shasum`` utility.

https://docs.gradle.org/current/userguide/gradle_wrapper.html

  Official docs.

Managing Gradle cache

=====================

Work in offline mode with ``--offline`` option.

Invalidate cache (force re-downloading dependencies) with

``--refresh-dependencies`` option.

Alternatively remove ``~/.m2/repository/`` and ``~/.gradle/caches`` directories.

Gradle cached modules declared as *changing*::

  dependencies {

    compile("com.evil:evil-api:1.0.1-SNAPSHOT") { changing=true }

  }

Default timeout is 24 hours and can be reset/changed via::

  configurations.all {

      resolutionStrategy.cacheChangingModulesFor 0, 'seconds'

  }

Download sources and javadoc of dependencies

============================================

To download sources and javadoc of dependencies to local ``~/.gradle`` cache add

``idea`` plugin to your ``build.gradle``::

  apply plugin: 'idea'

  idea.module.downloadJavadoc = true

  idea.module.downloadSources = true

and invoke plugin::

  $ gradle idea

To wipe out Idea projects file after plug-in run::

  $ gradle cleanIdea