Gradle Multi-Project Builds TODEPLETE: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
No edit summary
Line 11: Line 11:


=Overview=
=Overview=
A multi-project build is a build where more than one project is built during a single [[Gradle_Concepts#Execution|execution]] run.


=Root Project=
=Root Project=
=Sub-Project=


=Multi-Project Build Layout=
=Multi-Project Build Layout=
Line 18: Line 22:
[[Gradle_Settings_Script_and_Settings_Instance#Project_Hierarchy|Project Hierarchy]]
[[Gradle_Settings_Script_and_Settings_Instance#Project_Hierarchy|Project Hierarchy]]


=Sub-Project=
=To Deplete=
 
A multi-project build is a build where more than one project is built during a single [[#Execution|execution]] run. Multi-project builds are always represented by a tree with a single root. Each element in the tree represents a project. Usually, there is a direct mapping between project tree elements and directories, but this behavior is configurable. The hierarchy is described in the [[settings.gradle#Overview|settings.gradle]] file. This file is required for multi-project builds and must be present, by convention, in the root or "master" directory of the project. The root directory must also contain a  [[Gradle_Configuration#build.gradle|build.gradle]] file.
 
A project has a name, and a fully qualified path which uniquely identifies it in the hierarchy.
 
The [[#Project_Root|root project]] build file can be used to configure as much commonality as possible in the [[Build.gradle#allprojects|allprojects{...}]] block, leaving sub-projects to customize only what is necessary for subproject. There is a [[Build.gradle#subprojects |subprojects{...}]] block that can be used to provide configuration for subprojects only. Child directories may have their own [[settings.gradle#Overview|settings.gradle]] and [[Gradle_Configuration#build.gradle|build.gradle]] build files.
 
A sub-project is declared in [[settings.gradle]] of the root project, by specifying its directory name in the <tt>include</tt> clause:
 
<syntaxhighlight lang='groovy'>
include 'subproject1', 'subproject2:child'
</syntaxhighlight>
 
Note that including a subproject does not necessarily mean that anything will be built in that subproject. A [[build.gradle]] with the appropriate plugins - which in turn contribute the necessary tasks - must also be added to the subproject. Alternatively, the plugins may be applied in the root build.gradle with [[Build.gradle#allprojects|allprojects{...}]] or [[Build.gradle#subprojects|subprojects{...}]]. A build.gradle file is not necessary if the appropriate plugins are applied to subprojects from root. A subproject's tasks can always be listed with <tt>gradle :''subproject-name'':tasks</tt>.
 
<span id='Dependencies_Between_Subprojects'></span>Subprojects of a root projects are not automatically exposing their artifacts to other subprojects of the same root project. The dependencies between projects must be declared explicitly in the [[build.gradle#dependencies|dependencies]] section of the dependent subproject. If classes belonging to "subproject-B" depend on classes in "subproject-A", then in the [[build.gradle#dependencies|build.gradle]] of subproject-B we must add:
 
<syntaxhighlight lang='groovy'>
dependencies {
    ...
    implementation project(':subproject-A')
    ...
}
</syntaxhighlight>
 
The structure of a hierarchical project can be displayed with:
 
[[Gradle_Operations#projects|gradle projects]]
 
It is possible to run any task in any subproject with the following syntax:
 
  gradle :<''subproject-name''>:<''task-name''>
 
If you were to spend a lot of time working in one sub-project, changing to that directory and running the build from there is normal. Running a task from that subdirectory will trigger all necessary actions form its dependency projects, thanks to the Gradle task graph implementation.
 
====Project Filtering====
 
{{External|https://docs.gradle.org/4.7/userguide/multi_project_builds.html#sub:project_filtering}}
 
Sub-projects to apply specific configuration to can be selected dynamically with an expression. <tt>configure</tt> can be used with a predicate closure to allow for selective sub-projects to be configured.
 
<syntaxhighlight lang='groovy'>
configure(subprojects.findAll {it.name == 'subproject-A' || it.name == 'subproject-A'} ) {
 
    apply plugin : ...
 
    dependencies {
        ...
    }
}
</syntaxhighlight>
 
====Layout====
 
=====<span id='Hierarchical'></span>Hierarchical=====
 
The project path is assumed to be equal to the relative physical file system path. [[Settings.gradle#Overview|"include" method]] argument "project1:child2" is mapped onto a "project1/child2" directory, relative to the root directory of the project. "project1:child2:subchild3" implies three projects: "project1", "project1:child2" and "project1:child2:subchild3".
 
=====<span id='Flat'></span>Flat=====
 
A flat layout is introduced by the [[settings.gradle#Overview|"includeFlat" method]], which takes directory names are argument. These directories need to exist as samplings of the root project directory.

Revision as of 16:37, 19 May 2018

External

Internal

Overview

A multi-project build is a build where more than one project is built during a single execution run.

Root Project

Sub-Project

Multi-Project Build Layout

Project Hierarchy

To Deplete

A multi-project build is a build where more than one project is built during a single execution run. Multi-project builds are always represented by a tree with a single root. Each element in the tree represents a project. Usually, there is a direct mapping between project tree elements and directories, but this behavior is configurable. The hierarchy is described in the settings.gradle file. This file is required for multi-project builds and must be present, by convention, in the root or "master" directory of the project. The root directory must also contain a build.gradle file.

A project has a name, and a fully qualified path which uniquely identifies it in the hierarchy.

The root project build file can be used to configure as much commonality as possible in the allprojects{...} block, leaving sub-projects to customize only what is necessary for subproject. There is a subprojects{...} block that can be used to provide configuration for subprojects only. Child directories may have their own settings.gradle and build.gradle build files.

A sub-project is declared in settings.gradle of the root project, by specifying its directory name in the include clause:

include 'subproject1', 'subproject2:child'

Note that including a subproject does not necessarily mean that anything will be built in that subproject. A build.gradle with the appropriate plugins - which in turn contribute the necessary tasks - must also be added to the subproject. Alternatively, the plugins may be applied in the root build.gradle with allprojects{...} or subprojects{...}. A build.gradle file is not necessary if the appropriate plugins are applied to subprojects from root. A subproject's tasks can always be listed with gradle :subproject-name:tasks.

Subprojects of a root projects are not automatically exposing their artifacts to other subprojects of the same root project. The dependencies between projects must be declared explicitly in the dependencies section of the dependent subproject. If classes belonging to "subproject-B" depend on classes in "subproject-A", then in the build.gradle of subproject-B we must add:

dependencies {
    ...
    implementation project(':subproject-A')
    ...
}

The structure of a hierarchical project can be displayed with:

gradle projects

It is possible to run any task in any subproject with the following syntax:

 gradle :<subproject-name>:<task-name>

If you were to spend a lot of time working in one sub-project, changing to that directory and running the build from there is normal. Running a task from that subdirectory will trigger all necessary actions form its dependency projects, thanks to the Gradle task graph implementation.

Project Filtering

https://docs.gradle.org/4.7/userguide/multi_project_builds.html#sub:project_filtering

Sub-projects to apply specific configuration to can be selected dynamically with an expression. configure can be used with a predicate closure to allow for selective sub-projects to be configured.

configure(subprojects.findAll {it.name == 'subproject-A' || it.name == 'subproject-A'} ) { 

    apply plugin : ...

    dependencies {
        ...
    }
}

Layout

Hierarchical

The project path is assumed to be equal to the relative physical file system path. "include" method argument "project1:child2" is mapped onto a "project1/child2" directory, relative to the root directory of the project. "project1:child2:subchild3" implies three projects: "project1", "project1:child2" and "project1:child2:subchild3".

Flat

A flat layout is introduced by the "includeFlat" method, which takes directory names are argument. These directories need to exist as samplings of the root project directory.