When to use gradle.properties vs. settings.gradle?

Question

A gradle build has three files

• build.gradle that defines the build configuration scripts
• gradle.properties
• settings.gradle

Questions

• What are differences between settings.gradle & gradle.properties?
• When should a settings be put in settings.gradle vs. gradle.properties?

Answer 1

The settings.gradle file is, just like the build.gradle file, a Groovy script. Only one settings.gradle script will be executed in each build (in comparison to the build.gradle script in multi-project builds). It will be executed before any build.gradle and even before the Project instances are created. Therefore, it is evaluated against a Settings object. With this Settings object, you can add subprojects to your build, modify the parameters from the command line (StartParameter) and access the Gradle object to register lifecycle handlers. Use the file, if your settings are build-related and not necessarily project-related or require logic before possible subprojects are included.

The gradle.properties file is a simple Java Properties file, that only gains it special role by being automatically included into the scope of the Project object (as so-called project properties). It's a simple key-value store, that only allows string values (so you need to split lists or arrays by yourself). You can put gradle.properties files to these locations:

• directly in the project directory (for project-related values)
• in the user home .gradle directory (for user- or environment-related values)

Answer 2

A multi-module project has one main module and many submodules. It has this layout:

(root)
  +- settings.gradle       
  +- build.gradle
  +- gradle.properties     # optional
  +-- buildSrc/            # optional
  |     +- build.gradle    # optional
  |     +-- src/           # optional
  |     +-- test/          # optional
  +-- gradle/              # optional
  |     +- utils.gradle    # optional
  +-- sub-a/
  |     +- build.gradle
  |     +- src/
  +-- sub-b/
        +- build.gradle
        +- src/

submodules can also be located deeper in subfolders, but without modifying code in settings.gradle, their name will include the name of such folders.

settings.gradle

The main role of settings.gradle is to define all included submodules and to mark the directory root of a tree of modules, so you can only have one settings.gradle file in a multi-module project.

rootProject.name = 'project-x'

include 'sub-a', 'sub-b'

The settings file is also written in groovy, and submodule lookup can be adapted alot.

build.gradle

There is one such file per module, it contains the build logic for this module.

In the build.gradle file of the main module, you can use allprojects {} or subprojects {} to define settings for all other modules.

In the build.gradle file of the submodules, you can use compile project(':sub-a') to make one submodule depend on the other.

gradle.properties

This is optional, it's main purpose is to provide startup options to use for running gradle itself, e.g.

org.gradle.jvmargs=-Dfile.encoding=UTF-8 ...
org.gradle.configureondemand=true

gradle/utils.gradle

(Any name of folder or file is possible.) You can define additional custom gradle files to reuse definitions, and include them in other gradle files via

apply from: "$rootDir/gradle/utils.gradle"

buildSrc/...

This folder is special, it is like a separate gradle project in itself. It is build before doing anything else, and can provide function to use in any other gradle file. You can define complex custom build logic in java, groovy or kotlin, instead of writing and deploying a plugin. This is also useful for unit-testing your custom build code, as you can have unit tests.