Gradle Project Coordinates, State and Configured Properties
Internal
Overview
Project-identifying information such as name, group, version, description and 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 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. More details are provided in their corresponding section.
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.
Coordinates
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.
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 org.gradle.api.initialization.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:
Group
The project group defaults to the path with dots as separators. For a simple project, the group is "", 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 org.gradle.api.initialization.ProjectDescriptor interface does not expose a group mutator.
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 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 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".
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.
Description
Path
Project Directory
TODO
- Verify that name, group and version can be set in settings.gradle. How? Via the ProjectDescriptor interface.