Gradle Project Coordinates, State and Configured Properties: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(81 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Internal=
* [[Gradle Properties - Runtime and Project Configuration#Project_State|Gradle Properties - Runtime and Project Configuration]]
* [[Maven_Concepts#Maven_Coordinates|Maven Project Coordinates]]
* [[Gradle_Project#Project_Coordinates_1|Gradle Project]]
* [[Gradle_Project#Project_Coordinates_1|Gradle Project]]
* [[Maven_Concepts#Maven_Coordinates|Maven Project Coordinates]]


=Overview=
=Overview=


Project-identifying information such as [[#Name|name]], [[#Group|group]], [[#Version|version]], [[#Description|description]] and [[#Path|path]] are referred to as "project coordinates". The terminology comes from Maven, where a project name, group and version uniquely identify a project artifact. Gradle project coordinates map onto Maven project coordinates, as described in the [[#Compatibility_with_Maven_Project_Coordinates|Compatibility with Maven Project Coordinates]] section.
Project-identifying information such as [[#Name|name]], [[#Group|group]] and [[#Version|version]] are referred to as [[#Coordinates|project coordinates]]. The project uses and exposes different other kinds of project properties: [[#Other_Properties|state properties]], [[#Extra_Properties|extra properties]], externally-configured project properties that come from [[#gradle.properties_Project_Properties|gradle.properties file hierarchy]] or from [[#-P_Command-Line_Options|-P command-line options]].


Different project coordinates can be set in different locations. The project [[#Name|name]] can only be set in [[settings.gradle]], while the [[#Group|group]], [[#Version|version]], [[#Description|description]] can only be set and read in [[build.gradle]]. More details are provided in their corresponding section.  
=Coordinates=
"Project coordinates" terminology comes from Maven, where a project name, group and version uniquely identify a project artifact. Gradle project coordinates map onto Maven project coordinates, as described in the [[#Compatibility_with_Maven_Project_Coordinates|Compatibility with Maven Project Coordinates]] section. Different project coordinates can be set in different locations. The project [[#Name|name]] can only be set in [[settings.gradle]], while the [[#Group|group]], [[#Version|version]], [[#Description|description]] can only be set and read in [[build.gradle]]. The coordinates are available as values of DSL variables and programmatically via the Project API.


The coordinates are available as values of DSL variables and programmatically via the Project API.
==Compatibility with Maven Project Coordinates==
Gradle produces by default artifacts that are compatible with Maven repositories, so Gradle translates its project coordinates into [[Maven_Concepts#Maven_Coordinates|Maven project coordinates]]. The translation rules are described in the [[#Name|name]], [[#Group|group]] and [[#Version|version]] sections: the project name becomes [[#Maven_artifactId|artifactId]], the group name becomes [[#Maven_groupId|groupId]] and the version becomes [[#Maven_version|Maven version]].


=Compatibility with Maven Project Coordinates=
Gradle produces by default artifacts that are compatible with Maven repositories, so Gradle translates its project coordinates into [[Maven_Concepts#Maven_Coordinates|Maven project coordinates]]. The translation rules are described in the [[#Name|name]], [[#Group|group]] and [[#Version|version]] sections: the project name becomes [[#Maven_artifactId|artifactId]],
=Coordinates=
==Name==
==Name==
The project name is a string that identifies the project. The project name is initialized by default with the name of the directory that contains the project's [[build.gradle]]. The name is not necessarily unique within a project hierarchy, the unique identifier for the project in a hierarchy is its [[#Path|path]].  
The project name is a string that identifies the project. The project name is initialized by default with the name of its top-level directory, as specified in [[settings.gradle]]. Usually, that directory contains the project's [[build.gradle]]. The name is not necessarily unique within a project hierarchy, the unique identifier for the project in a hierarchy is its [[#Path|path]].  


If the project name must be set to a value different from its directory, it can be set in [[settings.gradle]], for both a simple project and multi-project.
If the project name must be set to a value different from the name of its directory, it can only be set in the [[Gradle_Concepts#Build_Initialization_Phase|build initialization phase]], in [[settings.gradle]], using the [[Gradle_ProjectDescriptor|ProjectDescriptor]] interface, for both simple projects and multi-projects. An attempt to set the project name in the [[Gradle_Concepts#Build_Configuration_Phase|configuration phase]] or [[Gradle_Concepts#Build_Execution_Phase|execution phase]] via the Project interface, for both single, root or sub-project will trigger a Gradle execution error.  


For a simple project, <code>rootProject</code> and <code>project(':')</code> are the same, so the following assignments are equivalent::
For a simple project, <code>rootProject</code> and <code>project(':')</code> are the same, so the following assignments are equivalent::
Line 40: Line 38:
The project name can be also obtained programmatically during the build with [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#getName-- Project.getName()].
The project name can be also obtained programmatically during the build with [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#getName-- Project.getName()].
===Maven artifactId===
===Maven artifactId===
The project [[#Name|name]] automatically becomes the Maven project name coordinate, artifactId.
The project [[#Name|name]] automatically becomes the Maven project name coordinate 'artifactId'. If a Maven-compliant artifact is to be generated by the project, the name should be a valid Maven identifier ([A-Za-z0-9_\-.]+). Alternatively, a non-conforming project name can be used, but artifactId must be overridden in the [[Gradle_Maven_Publish_Plugin#Maven_Project_Coordinates|Maven publishing plugin configuration]]. More details about Maven artifactId: {{Internal|Maven_Concepts#Artifact_ID|Maven artifactId}}
 
==Group==
 
The project group defaults to the [[#Path|path]] with dots as separators. For a simple project, the group is the empty string, and this has implications on [[#Maven_groupId|Maven artifact publication]].


More details about artifactId: {{Internal|Maven_Concepts#Artifact_ID|Maven artifactId}}
The group can only be set in the build [[Gradle_Concepts#Build_Configuration_Phase|configuration phase]], by assigning the desired value to the "group" DSL element in [[build.gradle]]. The group may not be set in the [[Gradle_Concepts#Build_Initialization_Phase|initialization phase]] because the [[Gradle_ProjectDescriptor|ProjectDescriptor]] interface does not expose a group mutator.
 
For a simple project, the following assignments are equivalent::
<syntaxhighlight lang='groovy'>
project.group = "io.example"
</syntaxhighlight>
<syntaxhighlight lang='groovy'>
group = "io.example"
</syntaxhighlight>
For a multi-project build, a group that is not explicitly set defaults to the parent's group. It can be set either in the sub-project's [[build.gradle]] or in the root project [[build.gradle]]:
<syntaxhighlight lang='groovy'>
project(':subproject-01').group = "io.example"
</syntaxhighlight>
If set in both places, the sub-project setting takes precedence. If all sub-projects should inherit root's group, this can be set up as follows:
<syntaxhighlight lang='groovy'>
subprojects {
  group = rootProject.group
}
</syntaxhighlight>
 
The project group can be read as value of the DSL element "group":
<syntaxhighlight lang='groovy'>
println "${group}"
println project.group
</syntaxhighlight>
The group can be also obtained programmatically during the build with [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#getGroup-- Project.getGroup()].


==Group==
===Maven groupId===
===Maven groupId===


The group information must be specified when generating a Maven artifact. If the group information is missing, [[Gradle_Maven_Publish_Plugin|Maven Publish plugin]] will complain that "groupId cannot be empty".
Gradle [[#Group|group]] automatically becomes the Maven project name coordinate 'groupId'. A non-empty group information must be specified when generating a Maven artifact. If the group information is missing, [[Gradle_Maven_Publish_Plugin|Maven Publish plugin]] will complain that "groupId cannot be empty". More details about Maven groupId: {{Internal|Maven_Concepts#Group_ID|Maven groupId}}


==Version==
==Version==
Gradle does not initialized version information by default, so if it is needed, it must be explicitly set in the [[Gradle_Concepts#Build_Configuration_Phase|configuration phase]], in [[build.gradle]]. It may not be set in the [[Gradle_Concepts#Build_Initialization_Phase|initialization phase]] in [[settings.gradle]]. For a simple project, the following assignments are equivalent:
<syntaxhighlight lang='groovy'>
project.version = '1.0'
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
version = '1.0'
</syntaxhighlight>
For a multi-project build sub-project, the version is undefined if not explicitly set. There is no default, and also there is no inheritance of the parent project version value, if the parent specifies its version. To set it, configure [[build.gradle]] as shown:
<syntaxhighlight lang='groovy'>
version = '2.0'
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
version = parent.version
</syntaxhighlight>
Alternatively, the version can be set in the root build.gradle:
<syntaxhighlight lang='groovy'>
project(':subproject-A').version = '2.0'
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
project(':subproject-A').version = version
</syntaxhighlight>
If set in both places, the sub-project [[build.gradle]] value takes precedence, as it is "closer" to the project.
If all sub-projects should inherit root's version, this can be set up in the root [[build.gradle]] as follows:
<syntaxhighlight lang='groovy'>
subprojects {
  version = rootProject.version;
}
</syntaxhighlight>
===Maven version===
===Maven version===
If the project does not configure a version, the corresponding Maven version will be empty - the artifact will not cary any version information.
Gradle [[#Version|version]] automatically becomes the Maven project name coordinate 'version'. If the project does not configure a version, which is the default behavior, the corresponding Maven version will be empty - the artifact will not cary any version information. More details about Maven version: {{Internal|Maven_Concepts#Version|Maven version}}
 
=<span id='Other_Properties'></span>Project State Properties=


==Description==
==Description==
Can be set in [[build.gradle]] with:
<syntaxhighlight lang='groovy'>
description = "This is an example project"
</syntaxhighlight>
==Path==
==Path==
The path is the fully qualified name of the project, where the elements are separated by ":". While the [[#Name|name]] may not be unique, the path is. For a simple project, the path is ":". It can be read with the "path" [[build.gradle]] DSL element or with [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#getPath-- Project.getPath()]. The path cannot be explicitly set, it is inferred.
==rootProject==
Maintains the reference to the root project. In case of a simple project, the project and the root project are the same.
==Project Directory==
==Build Directory==
The build directory is the path specified by the Project.getBuildDir() project property. The content of the build directory and the build directory itself is removed by the Base plugin [[Gradle_Base_Plugin#clean|clean]] task.
=Extra Properties=
{{Internal|Gradle Extra Properties#Overview|Gradle Extra Properties}}
=Externally-Configured Project Properties=
==<span id='gradle.properties_Properties'></span>gradle.properties Project Properties==
Properties declared in [[Gradle.properties#Projection|gradle.properties]] file hierarchy are flattened according set precedence ruled described [[Gradle.properties#Precedence_Rules|here]] and projected into the project object instance, where they can be accessed as project properties. See: {{Internal|gradle.properties|gradle.properties}}
==-P Command-Line Options==
Project properties can also be specified on [[Gradle_Command_Line#-P.3Cproperty-name.3E.3D.3Cproperty-value.3E_Project_Properties|command line]] by prefixing them with -P:
<syntaxhighlight lang='text'>
gradle -P<property-name>=<property-value> ...
</syntaxhighlight>
<syntaxhighlight lang='text'>
gradle -Pshape=square display
</syntaxhighlight>
The properties declared as such are available as project properties:
<syntaxhighlight lang='groovy'>
task display {
  doLast {
    // equivalent property references
    println project.shape
    println shape
  }
}
</syntaxhighlight>
If a property with the same name is specified in multiple locations, it is subject to [[#Project_Properties_Priority_Rules|priority rules]].
The project version can be overridden this way:
<syntaxhighlight lang='text'>
gradle -Pversion=1.0.0 build
</syntaxhighlight>


=Project Directory=
==Project Properties Priority Rules==
=TODO=
If a property with the same name is configured on command line with -P and in [[gradle.properties]], the command line value takes precendence.


* Verify that name, group and version can be set in settings.gradle. How? Via the [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjectDescriptor]] interface.
=TO DEPLETE=
{{Internal|Gradle Project Properties TODEPLETE|Gradle Project Properties TODEPLETE}}

Latest revision as of 04:55, 9 February 2022

Internal

Overview

Project-identifying information such as name, group and version are referred to as project coordinates. The project uses and exposes different other kinds of project properties: state properties, extra properties, externally-configured project properties that come from gradle.properties file hierarchy or from -P command-line options.

Coordinates

"Project coordinates" terminology comes from Maven, where a project name, group and version uniquely identify a project artifact. Gradle project coordinates map onto Maven project coordinates, as described in the Compatibility with Maven Project Coordinates section. Different project coordinates can be set in different locations. The project name can only be set in settings.gradle, while the group, version, description can only be set and read in build.gradle. The coordinates are available as values of DSL variables and programmatically via the Project API.

Compatibility with Maven Project Coordinates

Gradle produces by default artifacts that are compatible with Maven repositories, so Gradle translates its project coordinates into Maven project coordinates. The translation rules are described in the name, group and version sections: the project name becomes artifactId, the group name becomes groupId and the version becomes Maven version.

Name

The project name is a string that identifies the project. The project name is initialized by default with the name of its top-level directory, as specified in settings.gradle. Usually, that directory contains the project's build.gradle. The name is not necessarily unique within a project hierarchy, the unique identifier for the project in a hierarchy is its path.

If the project name must be set to a value different from the name of its directory, it can only be set in the build initialization phase, in settings.gradle, using the ProjectDescriptor interface, for both simple projects and multi-projects. An attempt to set the project name in the configuration phase or execution phase via the Project interface, for both single, root or sub-project will trigger a Gradle execution error.

For a simple project, rootProject and project(':') are the same, so the following assignments are equivalent::

rootProject.name = "blue"
project(':').name = "blue"

For a multi-project build, the name of the root project can be set as above, and the name of a sub-project can be set specifying its path:

project(':subproject-01').name = "green"

The project name can be read as value of the DSL element "name":

println "${name}"
println project.name

The project name can be also obtained programmatically during the build with Project.getName().

Maven artifactId

The project name automatically becomes the Maven project name coordinate 'artifactId'. If a Maven-compliant artifact is to be generated by the project, the name should be a valid Maven identifier ([A-Za-z0-9_\-.]+). Alternatively, a non-conforming project name can be used, but artifactId must be overridden in the Maven publishing plugin configuration. More details about Maven artifactId:

Maven artifactId

Group

The project group defaults to the path with dots as separators. For a simple project, the group is the empty string, and this has implications on Maven artifact publication.

The group can only be set in the build configuration phase, by assigning the desired value to the "group" DSL element in build.gradle. The group may not be set in the initialization phase because the ProjectDescriptor interface does not expose a group mutator.

For a simple project, the following assignments are equivalent::

project.group = "io.example"
group = "io.example"

For a multi-project build, a group that is not explicitly set defaults to the parent's group. It can be set either in the sub-project's build.gradle or in the root project build.gradle:

project(':subproject-01').group = "io.example"

If set in both places, the sub-project setting takes precedence. If all sub-projects should inherit root's group, this can be set up as follows:

subprojects {
  group = rootProject.group
}

The project group can be read as value of the DSL element "group":

println "${group}"
println project.group

The group can be also obtained programmatically during the build with Project.getGroup().

Maven groupId

Gradle group automatically becomes the Maven project name coordinate 'groupId'. A non-empty group information must be specified when generating a Maven artifact. If the group information is missing, Maven Publish plugin will complain that "groupId cannot be empty". More details about Maven groupId:

Maven groupId

Version

Gradle does not initialized version information by default, so if it is needed, it must be explicitly set in the configuration phase, in build.gradle. It may not be set in the initialization phase in settings.gradle. For a simple project, the following assignments are equivalent:

project.version = '1.0'

or

version = '1.0'

For a multi-project build sub-project, the version is undefined if not explicitly set. There is no default, and also there is no inheritance of the parent project version value, if the parent specifies its version. To set it, configure build.gradle as shown:

version = '2.0'

or

version = parent.version

Alternatively, the version can be set in the root build.gradle:

project(':subproject-A').version = '2.0'

or

project(':subproject-A').version = version

If set in both places, the sub-project build.gradle value takes precedence, as it is "closer" to the project.

If all sub-projects should inherit root's version, this can be set up in the root build.gradle as follows:

subprojects {
  version = rootProject.version;
}

Maven version

Gradle version automatically becomes the Maven project name coordinate 'version'. If the project does not configure a version, which is the default behavior, the corresponding Maven version will be empty - the artifact will not cary any version information. More details about Maven version:

Maven version

Project State Properties

Description

Can be set in build.gradle with:

description = "This is an example project"

Path

The path is the fully qualified name of the project, where the elements are separated by ":". While the name may not be unique, the path is. For a simple project, the path is ":". It can be read with the "path" build.gradle DSL element or with Project.getPath(). The path cannot be explicitly set, it is inferred.

rootProject

Maintains the reference to the root project. In case of a simple project, the project and the root project are the same.

Project Directory

Build Directory

The build directory is the path specified by the Project.getBuildDir() project property. The content of the build directory and the build directory itself is removed by the Base plugin clean task.

Extra Properties

Gradle Extra Properties

Externally-Configured Project Properties

gradle.properties Project Properties

Properties declared in gradle.properties file hierarchy are flattened according set precedence ruled described here and projected into the project object instance, where they can be accessed as project properties. See:

gradle.properties

-P Command-Line Options

Project properties can also be specified on command line by prefixing them with -P:

gradle -P<property-name>=<property-value> ...
gradle -Pshape=square display

The properties declared as such are available as project properties:

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

If a property with the same name is specified in multiple locations, it is subject to priority rules.

The project version can be overridden this way:

gradle -Pversion=1.0.0 build

Project Properties Priority Rules

If a property with the same name is configured on command line with -P and in gradle.properties, the command line value takes precendence.

TO DEPLETE

Gradle Project Properties TODEPLETE