Gradle Project and Build Script: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(84 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
=DEPLETE TO=
 
{{Internal|Gradle Project|Gradle Project}}
* https://docs.gradle.org/current/dsl/org.gradle.api.Project.html
* Build script structure https://docs.gradle.org/current/dsl/#N10060
 
=Internal=
 
* [[Gradle_Concepts#Build_Lifecycle_and_Gradle_Objects|Gradle Concepts]]


=Overview=
=Overview=


A Project is the main API to use to interact with Gradle. All top level statements within a "build.gradle" build script are delegated to the corresponding Project instance and when executed, modify its state.
A Project is the main API to use to interact with Gradle. All top level statements within a "build.gradle" build script are delegated to the corresponding Project instance and when executed, modify its state. The build.gradle configuration script is written in the Gradle DSL and it may contain any Groovy language element, [[#Variables|variable declarations]], [[#Top-Level_Script_Blocks|script blocks]], etc. [[Groovy]] single-quoted and double-quoted string literals can be used. The main difference is that double-quoted String literals support String interpolation.


In case of a [[#Multi-Project_Builds|multi-project build]], It is possible to configure a project build from another build script associated with any project in the hierarchy. This capability is called ''cross-project configuration''. Gradle implements cross-project configuration via ''configuration injection''. Configuration injection is the default way to define common behavior.
In case of a [[#Multi-Project_Builds|multi-project build]], It is possible to configure a project build from another build script associated with any project in the hierarchy. This capability is called ''cross-project configuration''. Gradle implements cross-project configuration via ''configuration injection''. Configuration injection is the default way to define common behavior.


=Project Coordinates=
build.gradle can be created automatically on project setup with [[Gradle_Operations#Start_a_Project|gradle init]]. To make build scripts more concise, Gradle automatically adds the set of default Gradle import statements to the script.


Gradle reads and builds artifacts that are compatible with Maven repositories, so they are described by [[Maven_Concepts#Maven_Coordinates|Maven project coordinates]]. Project coordinates [[#Project_Name.2C_artifactId|artifactId]], [[#Group.2C_groupId|groupId]] and [[#Version|version]] can be read or set in the [[Gradle_Settings_Script_and_Settings_Instance#Overview|settings configuration file]] via the [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjectDescriptor]] interface, or in the build configuration file, described by this article, via the [https://docs.gradle.org/current/dsl/org.gradle.api.Project.html Project] interface. These details apply to single project builds and [[#Multi-Project_Builds|multi-project builds]].
The default name of the build script is "build.gradle" and in most cases there is no need to change it. It can be changed, though, in [[Gradle_Settings_Script_and_Settings_Instance#Overview|settings.gradle]] by setting the "buildFileName" property of the [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjectDescriptor]] associated with the project whose build script name we want to change:
 
===Project Name, artifactId===
 
The project name can only be set in the [[Gradle_Concepts#Initialization|initialization phase]], in the [[Gradle_Settings_Script_and_Settings_Instance#Overview|settings configuration file]], via the [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjectDescriptor]] interface. An attempt to set the project name in the [[Gradle_Concepts#Configuration|configuration]] phase or [[Gradle_Concepts#Execution|execution]] phase via the Project interface, for both single, root or sub-project will trigger a Gradle execution error. The default is given by the directory name the project lives in. It can be changed as follows:


<syntaxhighlight lang='groovy'>
<syntaxhighlight lang='groovy'>
rootProject.name = 'something'
project(':projectA').buildFileName = 'projectA.gradle'
...
project(':subproject-A').name = "something else"
</syntaxhighlight>
</syntaxhighlight>


though it is probably a good idea to leave sub-projects to be named by their host sub-directories.
The project is a collection of [[Gradle Task#Overview|tasks]].


===Group, groupId===
=Top-Level Script Blocks=


The group may be set in the [[Gradle_Concepts#Configuration|configuration]] phase, in the build configuration file, as shown below. It may not be set in the [[Gradle_Concepts#Initialization|initialization]] phase in the settings configuration file, because [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjecteDescriptor]] does not expose a group.
==allprojects{}==


<syntaxhighlight lang='groovy'>
Applies the given configuration closure, in order, to the current project and all of its ''sub-projects''.
project.group = 'io.example'
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
group = 'io.example'
</syntaxhighlight>


For sub-project, the group that is not explicitly set defaults to the name of the parent and it can be set either in the sub-project's build.gradle as shown above, or in the root build.gradle as follows:
{{Internal|Gradle_Multi-Project_Builds#allprojects|allprojects{...} usage examples}}


<syntaxhighlight lang='groovy'>
==subprojects{}==
project(':subproject-A').group = "io.something"
 
</syntaxhighlight>
Applies the given configuration closure, in order, to all ''sub-projects'' of the current project.


If set in both places, the sub-project collocated build.gradle value takes precedence, as it is "closer" to the project.
{{Internal|Gradle_Multi-Project_Builds#subprojects|subprojects{...} usage examples}}


===Version===
==repositories{}==


The version may be set in the [[Gradle_Concepts#Configuration|configuration]] phase, in the build configuration file, as shown below. It may not be set in the [[Gradle_Concepts#Initialization|initialization]] phase in the settings configuration file, because [[Gradle_Settings_Script_and_Settings_Instance#ProjectDescriptor_-_Access_to_Projects_from_Settings|ProjecteDescriptor]] does not expose a version.
Used to declare and configure the repositories associated with this project. The repositories declared here will only be used to pull dependencies from, not publish against. For details on how to specify publishing repositories, see [[Gradle_Artifact_Publishing_Concepts#Overview|Gradle Artifact Publishing]]. This method executes the given configuration closure against the [https://docs.gradle.org/current/dsl/org.gradle.api.artifacts.dsl.RepositoryHandler.html RepositoryHandler] for this project, which is passed to the closure as the closure's delegate. More details on on repositories and how to configured them are available in: {{Internal|Gradle Repositories#Overview|Gradle Repositories}}


<syntaxhighlight lang='groovy'>
=Project's Containers and Handlers=
project.version = '1.0'
</syntaxhighlight>
or
<syntaxhighlight lang='groovy'>
version = '1.0'
</syntaxhighlight>


For sub-project, the version is undefined if not explicitly set as shown below. There is no default, and no inheritance of the parent project version value. To set it, the sub-project's build.gradle as shown:
{{External|https://docs.gradle.org/current/dsl/#N10272}}


<syntaxhighlight lang='groovy'>
* <span id='Repository_Handler'></span>[[Gradle_Repositories#Repository_Handler|Repository Handler]]
version = '2.0'
* <span id='Configuration_Container'></span>[[Gradle_Dependencies_and_Dependency_Configurations#Configuration_Container|Configuration Container]]
</syntaxhighlight>
* Publishing extension:
** <span id='Publications_Container'></span>[[Gradle_Maven_Publish_Plugin#Mechanics|Publications Container]]
** <span id='Publishing_Repository_Container'>[[Gradle_Maven_Publish_Plugin#Mechanics|Publishing Repository Container]]


or
=Reacting to Build Lifecycle Events=


<syntaxhighlight lang='groovy'>
A [[Gradle_Concepts#Build_Lifecycle|build lifecycle]] can be reacted to with code similar to the following examples.
version = parent.version
</syntaxhighlight>


Alternatively, the version can be set in the root build.gradle:
<font color=darkgray>More research necessary.</font>


<syntaxhighlight lang='groovy'>
<syntaxhighlight lang='groovy'>
project(':subproject-A').version = '2.0'
allprojects {
      afterEvaluate { project ->
          if (project.hasTests) {
              println "Adding test task to $project"
              project.task('test') {
                  doLast {
                        println "running tests for $project"
                  }
              }
          }
    }
}
</syntaxhighlight>
</syntaxhighlight>
or


<syntaxhighlight lang='groovy'>
<syntaxhighlight lang='groovy'>
project(':subproject-A').version = version
gradle.afterProject {project, projectState ->
      if (projectState.failure) {
          println "Evaluation of $project FAILED"
      }
      else {
          println "Evaluation of $project succeeded"
      }
}
</syntaxhighlight>
</syntaxhighlight>


If set in both places, the sub-project collocated build.gradle value takes precedence, as it is "closer" to the project.
=Text Execution Configuration=
 
=Top-Level Script Blocks=
 
==allprojects{}==
 
Applies the given configuration closure, in order, to the current project and all of its ''sub-projects''.
 
==subprojects{}==
 
Applies the given configuration closure, in order, to all ''sub-projects'' of the current project.
 
==artifacts{}==
 
==buildscript{}==
 
==configurations{}==
 
==dependencies{}==
 
==repositories{}==
 
==sourceSets{}==
 
==publishing{}==
 
=Multi-Project Builds=
 
==Root Project==
 
==Multi-Project Build Layout==
 
[[Gradle_Settings_Script_and_Settings_Instance#Project_Hierarchy|Project Hierarchy]]


===Sub-Project===
{{Internal|Testing_with_Gradle_Java_Plugin#Configuring_the_.22test.22_Task|Test Execution Configuration}}

Latest revision as of 09:51, 22 October 2020

DEPLETE TO

Gradle Project

Overview

A Project is the main API to use to interact with Gradle. All top level statements within a "build.gradle" build script are delegated to the corresponding Project instance and when executed, modify its state. The build.gradle configuration script is written in the Gradle DSL and it may contain any Groovy language element, variable declarations, script blocks, etc. Groovy single-quoted and double-quoted string literals can be used. The main difference is that double-quoted String literals support String interpolation.

In case of a multi-project build, It is possible to configure a project build from another build script associated with any project in the hierarchy. This capability is called cross-project configuration. Gradle implements cross-project configuration via configuration injection. Configuration injection is the default way to define common behavior.

build.gradle can be created automatically on project setup with gradle init. To make build scripts more concise, Gradle automatically adds the set of default Gradle import statements to the script.

The default name of the build script is "build.gradle" and in most cases there is no need to change it. It can be changed, though, in settings.gradle by setting the "buildFileName" property of the ProjectDescriptor associated with the project whose build script name we want to change:

project(':projectA').buildFileName = 'projectA.gradle'

The project is a collection of tasks.

Top-Level Script Blocks

allprojects{}

Applies the given configuration closure, in order, to the current project and all of its sub-projects.

allprojects{...} usage examples

subprojects{}

Applies the given configuration closure, in order, to all sub-projects of the current project.

subprojects{...} usage examples

repositories{}

Used to declare and configure the repositories associated with this project. The repositories declared here will only be used to pull dependencies from, not publish against. For details on how to specify publishing repositories, see Gradle Artifact Publishing. This method executes the given configuration closure against the RepositoryHandler for this project, which is passed to the closure as the closure's delegate. More details on on repositories and how to configured them are available in:

Gradle Repositories

Project's Containers and Handlers

https://docs.gradle.org/current/dsl/#N10272

Reacting to Build Lifecycle Events

A build lifecycle can be reacted to with code similar to the following examples.

More research necessary.

allprojects {
      afterEvaluate { project ->
          if (project.hasTests) {
              println "Adding test task to $project"
              project.task('test') {
                   doLast {
                         println "running tests for $project"
                   }
              }
          }
     }
}
gradle.afterProject {project, projectState ->
      if (projectState.failure) {
          println "Evaluation of $project FAILED"
      } 
      else {
          println "Evaluation of $project succeeded"
      }
}

Text Execution Configuration

Test Execution Configuration