Gradle Project and Build Script
External
- https://docs.gradle.org/current/dsl/org.gradle.api.Project.html
- Build script structure https://docs.gradle.org/current/dsl/#N10060
- https://docs.gradle.org/current/userguide/writing_build_scripts.html
Internal
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'
Example
apply plugin: 'java'
group = "io.example.gradle"
version = "1.0"
repositories {
mavenLocal()
mavenCentral()
}
configurations.all {
resolutionStrategy.cacheChangingModulesFor 3600, 'seconds'
}
dependencies {
implementation 'org.slf4j:slf4j-api:1.7.12'
testImplementation 'junit:junit:4.+'
}
configurations {
testImplementation.exclude group: 'com.example'
}
compileJava {
options.compilerArgs += ['-Xlint']
}
javadoc {
options.charSet = 'UTF-8'
}
task runMain(type: JavaExec) {
classpath = sourceSets.main.runtimeClasspath
main = "io.novaordis.playground.gradle.java.Main"
}
Comments
// This is a comment
Project Coordinates
Gradle reads and builds artifacts that are compatible with Maven repositories, so they are described by Maven project coordinates. Project coordinates artifactId, groupId and version can be read or set in the settings configuration file via the ProjectDescriptor interface, or in the build configuration file, described by this article, via the Project interface. These details apply to single project builds and multi-project builds.
Project Name, artifactId
The Gradle project name is equivalent with Maven artifactId. The project name can only be set in the initialization phase, in the settings configuration file, via the ProjectDescriptor interface. 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. The default name is given by the directory name the project lives in. It can be changed as follows:
rootProject.name = 'something'
...
project(':subproject-A').name = "something else"
though it is probably a good idea to leave sub-projects to be named by their host sub-directories.
Group, groupId
The Gradle project group is equivalent with Maven groupId. The group may be set in the configuration phase, in the build configuration file, as shown below. It may not be set in the initialization phase in the settings configuration file, because ProjecteDescriptor does not expose a group.
project.group = 'io.example'
or
group = 'io.example'
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:
project(':subproject-A').group = "io.something"
If set in both places, the sub-project collocated build.gradle value takes precedence, as it is "closer" to the project.
If all sub-projects should inherit root's group, this can be set up in the root build.gradle as follows:
subprojects {
group = rootProject.group;
// group = parent.group;
}
Version
The version, equivalent to Maven's version may be set in the configuration phase, in the build configuration file, as shown below. It may not be set in the initialization phase in the settings configuration file, because ProjecteDescriptor does not expose a version.
project.version = '1.0'
or
version = '1.0'
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:
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 collocated build.gradle value takes precedence, as it is "closer" to the project.
f all sub-projects should inherit root's version, this can be set up in the root build.gradle as follows:
subprojects {
version = rootProject.version;
// version = parent.version;
}
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{}
Used to specify external plugins:
configurations{}
Configures the dependencies configurations of this project. More details available in:
dependencies{}
Declare the dependencies of the project. For more details see:
repositories{}
Used to declare and configure the repositories associated with this project. 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:
sourceSets{}
publishing{}
Variables
There are two kinds of variables that can be declared in a build script: local variables and extra properties.
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.
def myVariable = "something"
...
println myVariable
Extra Properties
Extra properties can be declared as follows:
...
ext {
log4jVersion = "2.1.7"
emailNotification = "build@example.com"
}
...
Project's Containers and Handlers
Multi-Project Builds
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"
}
}