Gradle.properties: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Internal=


* [[Gradle_Variables_and_Properties#.27gradle.properties.27_Files|Gradle Variables and Properties]]
* [[Gradle Properties - Runtime and Project Configuration|Gradle Properties - Runtime and Project Configuration]]
* [[Gradle Configuration#gradle.properties|Gradle Configuration]]


=Overview=
=Overview=


'gradle.properties' files are also used to define properties. There are two kinds of 'gradle.properties' files. If both files are present, their content is merged and the configuration that comes from the user home directory takes precedence over the configuration that comes from the project root directory. Form a security perspective, it makes sense to use the user home directory if the project is checked into a repository and we do not want to maintain sensitive information in that file. The project root gradle.properties is important because it can be stored in source control, so the entire team working on the project can share the same configuration.
<code>gradle.properties</code> files are used to define configuration [[Gradle Properties - Runtime and Project Configuration#Overview|properties]]. <code>gradle.properties</code> files can be present in two layers: the [[#Gradle_User_Home_gradle.properties|user home directory .gradle directory]] and the [[#Project_Root_gradle.properties|project root]]. Property keys must comply with the rules described here: [[Gradle Properties - Runtime and Project Configuration#Property_Keys|Property Keys]].


=Gradle User Home gradle.properties=
=Hierarchy=


This file is  stored in Gradle user home directory ~/.gradle/gradle.properties, conventionally referred to as GRADLE_USER_HOME.
==Gradle User Home <tt>gradle.properties</tt>==


=Project Root gradle.properties=
This file is  stored in Gradle user home directory <code>~/.gradle/gradle.properties</code>, conventionally referred to as <code>GRADLE_USER_HOME</code>. Any property declared in this file will be available to all user's Gradle projects.
 
==Project Root <tt>gradle.properties</tt>==


Conventionally, this is where the version of the project is stored:
Conventionally, this is where the version of the project is stored:
Line 18: Line 19:
<syntaxhighlight lang='text'>
<syntaxhighlight lang='text'>
version=1.0-SNAPSHOT
version=1.0-SNAPSHOT
</syntaxhighlight>
This file is important because it can be stored in source control, so the entire team working on the project can share the same configuration.
==Multi-Project Builds==
Each project of a multi-project build can maintain a gradle.properties file in its root.
==Precedence Rules==
If files from both layers are present, their content is merged and the configuration that comes from the user home directory takes precedence over the configuration that comes from the project root directory. This makes sense from a security perspective, as the user home directory is not checked in into a repository while the project is, and we need to store security sensitive configuration. When the same property is declared in both root project and a sub-project's gradle.properties files, the value coming from the sub-project takes precedence over the root project value.
=Projection=
The properties configured in gradle.properties files are flattened according the precedence rules described above and projected into the Project instance where they can be accessed as project properties, similarly to [[Gradle Extra Properties|extra properties]].
gradle.properties:
<syntaxhighlight lang='groovy'>
my.color=blue
</syntaxhighlight>
build.properties:
<syntaxhighlight lang='groovy'>
println project.my.color
</syntaxhighlight>
If gradle.properties declares:
<syntaxhighlight lang='groovy'>
shape = 'square'
</syntaxhighlight>
the configured value can be accessed from the project ([[build.gradle]]) simply using the property name:
<syntaxhighlight lang='groovy'>
task display {
  doLast {
    // equivalent property references
    println project.shape
    println shape
  }
}
</syntaxhighlight>
==Failed Projection and Alternatives==
Under some yet not clear circumstances, a multi-token property declared in gradle.properties cannot be retrieved by its name as described above.
<syntaxhighlight lang='groovy'>
println rootProject.a.b.c
</syntaxhighlight>
produces:
<syntaxhighlight lang='text'>
A problem occurred evaluating project ':some-project'.
> Could not get unknown property 'a' for root project 'some-root-project' of type org.gradle.api.Project.
</syntaxhighlight>
This alternative works:
<syntaxhighlight lang='groovy'>
println rootProject.getProperties().get("a.b.c")
</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 23:32, 7 February 2022

Internal

Overview

gradle.properties files are used to define configuration properties. gradle.properties files can be present in two layers: the user home directory .gradle directory and the project root. Property keys must comply with the rules described here: Property Keys.

Hierarchy

Gradle User Home gradle.properties

This file is stored in Gradle user home directory ~/.gradle/gradle.properties, conventionally referred to as GRADLE_USER_HOME. Any property declared in this file will be available to all user's Gradle projects.

Project Root gradle.properties

Conventionally, this is where the version of the project is stored:

version=1.0-SNAPSHOT

This file is important because it can be stored in source control, so the entire team working on the project can share the same configuration.

Multi-Project Builds

Each project of a multi-project build can maintain a gradle.properties file in its root.

Precedence Rules

If files from both layers are present, their content is merged and the configuration that comes from the user home directory takes precedence over the configuration that comes from the project root directory. This makes sense from a security perspective, as the user home directory is not checked in into a repository while the project is, and we need to store security sensitive configuration. When the same property is declared in both root project and a sub-project's gradle.properties files, the value coming from the sub-project takes precedence over the root project value.

Projection

The properties configured in gradle.properties files are flattened according the precedence rules described above and projected into the Project instance where they can be accessed as project properties, similarly to extra properties.

gradle.properties:

my.color=blue

build.properties:

println project.my.color

If gradle.properties declares:

shape = 'square'

the configured value can be accessed from the project (build.gradle) simply using the property name:

task display {
  doLast {
    // equivalent property references
    println project.shape 
    println shape
  }
}

Failed Projection and Alternatives

Under some yet not clear circumstances, a multi-token property declared in gradle.properties cannot be retrieved by its name as described above.

println rootProject.a.b.c

produces:

A problem occurred evaluating project ':some-project'.
> Could not get unknown property 'a' for root project 'some-root-project' of type org.gradle.api.Project.

This alternative works:

println rootProject.getProperties().get("a.b.c")