Gradle Properties - Runtime and Project Configuration: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(27 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
=External=
* https://docs.gradle.org/current/userguide/groovy_build_script_primer.html#groovy:properties
* https://docs.gradle.org/current/userguide/build_environment.html
* https://docs.gradle.org/current/userguide/build_environment.html
=Internal=
=Internal=
* [[Gradle_Concepts#Properties|Gradle Concepts]]
* [[Gradle_Concepts#Properties|Gradle Concepts]]
=TODO=
Document the difference between properties and extra properties.
=Overview=
=Overview=


"Properties" in this context represent external configuration elements passed to a [[Gradle_Concepts#Build_Lifecycle|Gradle build]] to modify the behavior of the Gradle runtime itself, or the behavior of tasks being executed by various projects that are part of the build. Gradle supports many kinds of "properties": configuration can be passed as command line flags, system properties, Gradle properties, environment variables and project properties. All these configuration elements are provided externally and injected into the build.  
"Properties" in this context represent external configuration elements passed to a [[Gradle_Concepts#Build_Lifecycle|Gradle build]] to modify the behavior of the Gradle runtime itself, or the behavior of tasks being executed by various projects that are part of the build. Gradle supports many kinds of "properties": configuration can be passed as '''command line options''', '''system properties''', [[settings.gradle]] and [[build.gradle]] extra properties, [[gradle.properties]] file properties and '''environment variables'''. All these configuration elements are provided externally and injected into the build and various model object instances.  
{{Internal|Gradle Command Line#Command_Line_Flags|Gradle Command Line Flags}}
{{Internal|Gradle Command Line#Command_Line_Flags|Gradle Command Line Flags}}
{{Internal|Gradle System Properties|Gradle System Properties}}
{{Internal|Gradle System Properties|Gradle System Properties}}
{{Internal|Gradle Properties|Gradle Properties}}
{{Internal|Gradle Environment Variables|Gradle Environment Variables}}
{{Internal|Gradle Environment Variables|Gradle Environment Variables}}
{{Internal|Gradle Project Properties|Gradle Project Properties}}
<span id='Gradle_Extra_Properties'>It is also possible to define properties, referred to as '''extra properties''',  in [[settings.gradle]] and [[build.gradle]] scripts and pass configuration around between different elements of the build.
<span id='Gradle_Extra_Properties'>It is also possible to define properties in [[settings.gradle]] and [[build.gradle]] scripts and pass configuration around between different elements of the build. Those properties are named '''extra properties'''.  
{{Internal|Gradle Extra Properties|Gradle Extra Properties}}
{{Internal|Gradle Extra Properties|Gradle Extra Properties}}
<span id='Gradle_Local_Variables'></span>Since build scripts may include executable code, it is also possible to use local variables, which are a feature of the underlying Groovy language.
<span id='Gradle_Local_Variables'></span>Since build scripts may include executable code, it is also possible to use '''local variables''', which are a feature of the underlying Groovy language.
{{Internal|Gradle Local Variables|Gradle Local Variables}}
{{Internal|Gradle Local Variables|Gradle Local Variables}}
The external configuration and extra properties become part of the state of various objects of the build, such as projects or tasks. The state of build objects can be read from the build scripts via dedicated accessors.  
The external configuration and extra properties become part of the state of various objects of the build, such as projects or tasks. The state of build objects can be read from [[settings.gradle]] or [[build.gradle]] scripts via dedicated accessors.  


<span id='Project_State'></span>A project exposes coordinates such as [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Name|name]], [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Group|group]] and [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Version|version]], various other state elements such as the [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Description|description]], [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Path|path]], and externally configured properties that come from [[gradle.properties#Overview|gradle.properties]] file hierarchy or -P command line options. More details about accessing the state of the project is available in: {{Internal|Gradle_Project_Coordinates,_State_and_Configured_Properties|Gradle Project Coordinates, State and Configured Properties}}
<span id='Project_State'></span>A project exposes '''project properties''': coordinates such as [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Name|name]], [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Group|group]] and [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Version|version]], various other state properties such as the [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Description|description]], [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Path|path]], and '''externally-configured''' project properties that come from [[gradle.properties#Overview|gradle.properties]] file hierarchy or [[Gradle_Project_Coordinates,_State_and_Configured_Properties#-P_Command-Line_Options|-P command line options]]. More details about accessing the project state and externally-configured properties are available in: {{Internal|Gradle_Project_Coordinates,_State_and_Configured_Properties|Gradle Project Coordinates, State and Configured Properties}}


<span id='Task_State'></span>A task also exposes its state ([[Gradle_Task#Task_Name|name]], [[Gradle_Task#Description|description]], whether it is [[Gradle_Task#Enabled|enabled]] or not) through getters and DLS elements.
<span id='Task_State'></span>A task also exposes its state ([[Gradle_Task#Task_Name|name]], [[Gradle_Task#Description|description]], whether it is [[Gradle_Task#Enabled|enabled]] or not) through getters and DLS elements.
=Property Syntax=
==Property Names==
Property keys may contain dots or dashes, but if they do, special precautions should be taken. A property named "my.color" cannot be dereferenced using the simple format:
<syntaxhighlight lang='groovy'>
"color is ${project.my.color}"
</syntaxhighlight>
Gradle will throw the following error message:
<syntaxhighlight lang='text'>
Could not get unknown property 'my' for project ':test' of type org.gradle.api.Project.
</syntaxhighlight>
The property can still be retrieved, but only using project.property('...') method call:
<syntaxhighlight lang='groovy'>
"color is ${project.property('my.color')}"
</syntaxhighlight>
==Property Values==
Declare the value without simple or double quotation marks, it will be handled as a string:
<syntaxhighlight lang='groovy'>
color = red
</syntaxhighlight>
If simple or double quotation marks are used, they will be considered as part of the string and they will be used verbatim in ${...} dereferences:
<syntaxhighlight lang='groovy'>
"color ${color}"
</syntaxhighlight>
will be rendered:
<syntaxhighlight lang='groovy'>
"color 'red'"
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
"color \"red\""
</syntaxhighlight>


=TO DEPLETE=
=TO DEPLETE=
{{Internal|Gradle_Variables_and_Properties#Overview|Gradle_Variables_and_Properties}}
{{Internal|Gradle_Variables_and_Properties#Overview|Gradle_Variables_and_Properties}}
{{Internal|Gradle Configuration|Gradle Configuration}}
{{Internal|Gradle Configuration|Gradle Configuration}}

Latest revision as of 22:46, 10 November 2020

External

Internal

TODO

Document the difference between properties and extra properties.

Overview

"Properties" in this context represent external configuration elements passed to a Gradle build to modify the behavior of the Gradle runtime itself, or the behavior of tasks being executed by various projects that are part of the build. Gradle supports many kinds of "properties": configuration can be passed as command line options, system properties, settings.gradle and build.gradle extra properties, gradle.properties file properties and environment variables. All these configuration elements are provided externally and injected into the build and various model object instances.

Gradle Command Line Flags
Gradle System Properties
Gradle Environment Variables

It is also possible to define properties, referred to as extra properties, in settings.gradle and build.gradle scripts and pass configuration around between different elements of the build.

Gradle Extra Properties

Since build scripts may include executable code, it is also possible to use local variables, which are a feature of the underlying Groovy language.

Gradle Local Variables

The external configuration and extra properties become part of the state of various objects of the build, such as projects or tasks. The state of build objects can be read from settings.gradle or build.gradle scripts via dedicated accessors.

A project exposes project properties: coordinates such as name, group and version, various other state properties such as the description, path, and externally-configured project properties that come from gradle.properties file hierarchy or -P command line options. More details about accessing the project state and externally-configured properties are available in:

Gradle Project Coordinates, State and Configured Properties

A task also exposes its state (name, description, whether it is enabled or not) through getters and DLS elements.

Property Syntax

Property Names

Property keys may contain dots or dashes, but if they do, special precautions should be taken. A property named "my.color" cannot be dereferenced using the simple format:

"color is ${project.my.color}"

Gradle will throw the following error message:

Could not get unknown property 'my' for project ':test' of type org.gradle.api.Project.

The property can still be retrieved, but only using project.property('...') method call:

"color is ${project.property('my.color')}"

Property Values

Declare the value without simple or double quotation marks, it will be handled as a string:

color = red

If simple or double quotation marks are used, they will be considered as part of the string and they will be used verbatim in ${...} dereferences:

"color ${color}"

will be rendered:

"color 'red'"

or

"color \"red\""

TO DEPLETE

Gradle_Variables_and_Properties
Gradle Configuration