Gradle

Owned by Duncan Calvert
Last updated: Sept 11, 2024 by Dexton Anderson
6 min read

Gradle is an open-source build automation tool focused on flexibility and performance. Gradle build scripts are written using a Groovy or Kotlin DSL. Read about Gradle features to learn what is possible with Gradle.

The ihmc-build plugin configures Gradle in a unique way in order to address lab specific needs. It is required to read the IHMC Build Plugin README to become familiar with its structure.

Gradle official documentation: https://docs.gradle.org/current/userguide/userguide.html

This guide assumes you have installed Java.

It is required to read and at least partially understand the Gradle official documentation on its Build Environment.


Contents

Installation

Gradle does not have any official installers. There are many community (package manager) based installation methods, or you can install it manually.

Gradle installation helper scripts

We maintain some helper scripts to install Gradle system-wide for both Ubuntu and Windows. These live in the repository-group repository. There are instructions here.

Configuration

If you have not yet read the Gradle official documentation on the Build Environment, please do so now. This section will mostly contain the important highlights of that document. Gradle properties files are .properties files.

User home gradle.properties file

  • Navigate to your user home directory.
  • Show hidden files.
  • Ensure the existence of the file ~/.gradle/gradle.properties on Ubuntu or C:/Users/<user>/.gradle/gradle.properties on Windows.
  • If it is not there, create it manually. This file's settings will override project and system level settings.

Nexus credentials

Though most IHMC software is freely available, the proprietary parts will require an IHMC Crowd account. To authenticate, the ihmc-build plugin loads these credentials as Gradle properties. Set them:

nexusUsername=robotlab-devs
nexusPassword=<password>

You can retrieve the nexus password from 1Password.

Optimizing JVM memory for better performance

Large workspaces require setting "Xmx" to 2 or 3 gigabytes.

The org.gradle.jvmargs Gradle property controls the VM running the build. See Configuring JVM Memory.

Typical options:

  • "-Xms" - The initial memory allocated, increasing this can improve startup times, but if running many builds at once, is bad
  • "-Xmx" - Max memory allowed, increasing this can allow larger caches and less garbage collects, increasing performance
  • "-Dfile.encoding" - Set to UTF-8 to unify experince over multiple platforms
  • "-Dpython.console.encoding=UTF-8" - On Windows, fixes error

Working examples:

Windows:

IHMC Employees:
gradle.properties
nexusUsername=robotlab-devs
nexusPassword=<password>
org.gradle.jvmargs=-Xmx4g
Open Source Only:
gradle.properties
org.gradle.jvmargs=-Xmx4g

Ubuntu:

IHMC Employees:
gradle.properties
nexusUsername=robotlab-devs
nexusPassword=<password>
org.gradle.jvmargs=-Xmx4g
Open Source Only:
gradle.properties
org.gradle.jvmargs=-Xmx4g

Working with Gradle

Running Gradle on the command line

It is extremely handy to be prepared to run Gradle from the command line. This requires a Gradle installation. You should be able to, at the very least run

gradle --version

See the official documentation on the Gradle Command-Line Interface and the IHMC Build Plugin README for details.

The most common debugging strategy is to simply configure the build with --info and --stacktrace enabled. This strategy can be used to isolate problems from your IDE.

~/dev/repository-group $ gradle --info --stacktrace

Knowing if the above command results in "BUILD SUCCESSFUL" or "BUILD FAILED" greatly shrinks the scope of search for a Gradle problem.

Importing into an IDE

Importing Gradle projects into an IDE is very similar to running Gradle on the command line. When you import a Gradle project you are entering the Gradle Build Environment. When you import a Gradle project, the IDE is analyzing the Java build structure that Gradle comes up with and copying that configuration into it's own data structures as if you had painstakingly configured a new Java project manually.

Refreshing IDE configuration

When you refresh a Gradle project in an IDE, the IDE is analyzing the updated Java build structure that Gradle comes up with and copying that configuration into it's own data structures as if you had painstakingly configured the Java projects manually. To trigger a refresh:

  • In Eclipse - Right click any project in the Project Explorer that has the little elephant icon. "Right Click > Gradle > Refresh Gradle Project" will refresh the build that that project came from.
    • Keep in mind that in Eclipse, it is possible to import multiple Gradle builds. Once imported, there is no way to see the list of what you have imported. Therefore, you must keep track of this yourself to know which projects you mught right-click in order to refresh your entire workspace.
  • In IntelliJ - Click the refresh icon in the Gradle view.

Changing project dependencies

Project dependencies are contained in the dependencies block in the build.gradle file for that project.

When using the ihmc-build plugin, there is a dependencies block for each source set. i.e. mainDependencies, testDependencies, etc.

You can find new dependencies on Maven Central, JCenter, or Bintray. You can also depend on other IHMC software.

Refer to the IHMC Build Plugin README.

Difference between build.gradle and build.gradle.kts files

Gradle was originally written using Groovy but has now adopted the Kotlin language. Kotlin is preferred due to its strong typing system. Strong typing allows linking to source code, documentation, and auto-completing code.

Gradle files ending in .kts are written in Kotlin instead of Groovy. For more information, see the official Gradle Kotlin DSL Primer.

IntelliJ has much better support for editing Gradle files than Eclipse.

The ihmc-build plugin has experimental support for .kts files.

Troubleshooting

Debugging Gradle builds

First, read Running Gradle on the command line.

The first thing to find out is if Gradle configures without errors. Gradle configuration is invoked with the gradle command without any arguments. Adding --info and --stacktrace can give you necessary debugging information. The --debug option is extremely verbose and it mostly only helpful for plugin developers.

Logging output to a file

It is often helpful to log Gradle build output to a file. To do this, run

gradle --info --stacktrace &> log.txt     // simple way

gradle --info --stacktrace 2>&1 | tee ~/.ihmc/logs/$(date +%Y%m%d%k%M%S)_build.txt       // see the output on the console for monitoring and store the log in the logs folder

Windows users see Windows#Logtoafile(butalsotoconsole) to install the tee command.

Unresponsive Builds

If a build is hanging it may be necessary to stop the process with Ctrl+C  and stop all running Gradle daemons with gradle --stop . If that doesn't work, try running with --no-daemon.

Getting help

It is sometimes very difficult to understand why Gradle is failing. You can get help in the #help-desk Slack channel. Guidelines for help requests:

  • When there is an error in text, please copy the full error message into the chat instead of only providing a screenshot. This helps others search for help.
  • Upload a log.txt (see "Logging output to a file" section above).

Problems with ppa:cwchien/gradle

Though we no longer recommend using it, use of the cwchien PPA is still installed on many computers running IHMC software.

Using it, it is sometimes necessary to completely remove Gradle and reinstall in order to upgrade. In some cases, an apt autoremove might even be necessary.

Please remove it and reinstall.

Dependency Troubleshooting

(Note: On Windows, first install tee.exe)

Run the following command in your workspace directory. This would most likely be ~/dev/repository-group.

gradle --info compositeTask -PtaskName=dependencies 2>&1 | tee ~/.ihmc/logs/$(date +%Y%m%d%k%M%S)_dependencies.txt

gradle --info dependencies 2>&1 | tee ~/.ihmc/logs/$(date +%Y%m%d%k%M%S)_dependencies.txt    # if not using ihmc-build

Then use an interactive text editor such as Notepad++ to search for dependency occurrences.

Gradle's dependency resolution algorithm is explained in detail here.

Compile Error Troubleshooting

Test if Gradle can compile your workspace on the command line:

gradle --info compositeTask -PtaskName=compileJava

See more in the IHMC Build plugin README.

Exclude Modules in Main Dependencies

If you want to exclude a specific module from a main dependency, go to your build.gradle file and in your mainDependencies block, edit the dependency to have the following format.

api("SOME_MAIN_DEPENDENCY") {
	exclude("SOME_GROUP:SOME_MODULE")
}