Gradle Variables and Properties: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
(Replaced content with "=External= * https://docs.gradle.org/current/userguide/build_environment.html =TODO= {{Internal|Tmp|tmp}}")
Line 1: Line 1:
=External=
=External=


* https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties
* https://docs.gradle.org/current/userguide/build_environment.html


=Internal=
=TODO=


* [[Gradle_Concepts#Variables_and_Properties|Gradle Concepts]]
{{Internal|Tmp|tmp}}
* [[Gradle_Project_and_Build_Script#Variables_and_Properties|Project and Build Script]]
* [[Gradle.properties#Overview|gradle.properties]]
 
=Overview=
 
<br>
<br>
<br>
<font color=darkgray>NEEDS REFACTORING.</font>
<br>
<br>
<br>
 
Configuration scripts can declare variables during the [[Gradle_Concepts#Initialization|initialization]] and [[Gradle_Concepts#Configuration|configuration]] phases, and the values of those variables can be accessed and updated during the [[Gradle_Concepts#Execution|execution]] phase and used to drive build logic. There are two types of variables that can be declared: [[#Local_Variables|local variables]] and [[#Extra_Properties|extra properties]].
 
Properties can be displayed with:
 
[[Gradle_Operations#properties|gradle properties]]
 
The command displays project properties, and the properties added by various plugins.
 
=<span id='Properties'></span>Gradle Properties=
 
Also see: {{Internal|Gradle.properties#Overview|gradle.properties}}
 
=System Properties=
 
=<span id='Local_Variable'></span>Local Variables=
 
Local variables, which are a feature of the underlying Groovy language, are declared with the "def" keyword. They are only visible in the scope where they have been declared. The scope include all closures declared in scope.
 
<syntaxhighlight lang='groovy'>
def myVariable = "something"
...
println myVariable
</syntaxhighlight>
 
=Extra Properties=
 
An ''extra property'' is a property that can be declared on most model object instances available to the closure being executed. In case of a settings script, the available model objects are Settings, Gradle, ProjectDescriptor, etc., but of those ProjectDescriptor does not allow defining extra properties, and Settings, even if allows defining extra properties, cannot be easily accessed at configuration and execution phase, so the best candidate for defining extra properties is Gradle. For build scripts, extra properties can be defined on any available object model instances. They can be declared with a special syntax described below. Once the properties have been added, they can be read and set like predefined properties. Extra properties can be accessed from anywhere their owning object can be accessed, giving them a wider scope than [[#Local_Variable|local variables]]. Extra properties on a project are visible from its sub-projects.
 
By requiring special syntax for adding a property, Gradle can fail fast when an attempt is made to set a [[#Predefined_Properties|predefined]] or [[#Extra_Properties|extra property]] but the property is misspelled or does not exist.
 
==Declaring and Using Extra Properties==
 
The extra properties are declared using the "ext" DSL keyword, applied to the model object we intend to declare extra properties for. However, "ext" is not necessary to access the property once declared, as shown in the examples below:
 
===Initialization Phase===
 
The property is defined in settings.gradle:
 
<syntaxhighlight lang='groovy'>
...
gradle.ext.color = "blue"
...
</syntaxhighlight>
 
The property can be accessed anywhere in a build or settings script:
 
<syntaxhighlight lang='groovy'>
println "gradle is $gradle.color"
</syntaxhighlight>
 
===Extra Properties and Multi-Project Builds===
 
The extra properties are not available and throw an execution error if they are accessed before are defined. That is why a multi-project build that declares extra properties in sub-projects' build.gradle and attempts to use them in the root project build.gradle will fail at the configuration phase:
 
BUILD FAILED in 3s
...
* <font color=red>Where</font>:
Build file '.../<font color=red>root-project/build.gradle</font>' line: 17
* What went wrong:
A problem occurred <font color=red>evaluating root project 'root-project'</font>.
> Could not get unknown property 'blah' <font color=red>for project ':sub-project-A'</font> of type org.gradle.api.Project.
 
The error occurs even "blah" was declared in sub-project-A's build.gradle, because the build file was not evaluated at the time the root project file is executed. If we log build.gradle evaluation, we get something like:
 
exiting root project build.gradle ....
entering sub-project-A build.gradle ....
exiting sub-project-A build.gradle ....
 
which shows that the sub-project build script is executed after the root project build script is executed.
 
===At Configuration Phase===
 
The property can be declared in a build script as follows:
 
<syntaxhighlight lang='groovy'>
project.ext.isApi = true
</syntaxhighlight>
 
The property can be accessed anywhere in a build script:
 
<syntaxhighlight lang='groovy'>
println isApi
</syntaxhighlight>
 
Declaring multiple extra properties in a closure:
 
<syntaxhighlight lang='groovy'>
...
ext {
    log4jVersion = "2.1.7"
    emailNotification = "build@example.com"
}
...
</syntaxhighlight>
 
=Auto-Delegation=
 
Properties not defined in the build script are auto-delegating to the Project instance. For example:
 
name
 
and
 
project.name
 
are equivalent. Normally, using "name" is sufficient. In case you define a property or a method which has the same name as a member of the Project object, you will need to use the <tt>project</tt> property.
 
=Predefined Properties=
 
==Project Coordinates==
 
===name===
 
A String containing the name of the project directory. It automatically becomes the project's [[Gradle_Project_and_Build_Script#Project_Name.2C_artifactId|name]] coordinate. See [[Gradle_Project_and_Build_Script#Project_Coordinates|Gradle Project Coordinates]].
 
===group===
 
See [[Gradle_Project_and_Build_Script#Group.2C_groupId|Gradle Project Coordinates - Group]].
 
===version===
 
See [[Gradle_Project_and_Build_Script#Version|Gradle Project Coordinates - Version]].
 
===parent===
 
==Other Properties==
 
===project===
 
The Project instance.
 
===projectDir===
 
The File instance corresponding to the directory containing the build script.
 
===path===
 
A String containing the absolute path of the project. The path of the root project is ":"
 
===description===
 
A String containing the description for the project.
 
===displayName===
 
===buildDir===
 
A File representing <''projectDir''>/build.
 
===buildFile===
 
===rootDir===
 
===rootProject===
 
====rootProject.name====
 
===state===
 
===status===
 
=Plugin Properties=
 
Plugins add specific properties. For a list of properties added by various plugins, consult the [[Gradle_Plugins#Plugin_List|plugin pages]].

Revision as of 16:22, 23 May 2018

External

TODO

tmp
Retrieved from "https://kb.novaordis.com/index.php?title=Gradle_Variables_and_Properties&oldid=44627"