Gradle composite construction

What is composite construction （Composing builds）？

A composite build is a build that includes other builds . in many ways , Composite construction is similar to Gradle Multi project build , The difference is that it does not contain a single project , It includes a complete build .

Distinguish between multi project construction and composite construction ：

Multi project build ：

​ Multi project construction focuses on how to organize multiple projects , There are often business logical connections between projects . It is also a scene we usually use more ： For example, projects APP, rely on ModuleA and ModuleB, The form of expression is as follows ：

implementation project(":ModuleA")
implementation project(":ModuleA2")

Composite construction ：

​ Composite construction focuses on how to integrate multiple independent projects , The introduced project can run independently , But there is not necessarily a logical connection . Like a project , It relies on another independent company SDK, This SDK It can be run as an independent project . The form of expression is as follows ：

// step 1： Of the main project settings.gradle Add the following code to the file 
includeBuild('../APPB') {
    
    dependencySubstitution {
    
        substitute module('com.beason.moduleb:ModuleB') using project(':ModuleB')
    }
}
// step 2： Then introduce Moduel place , Can be introduced 
implementation "com.beason.moduleb:ModuleB"

A build contained in a composite build is naturally called “ Include build ”. Included builds do not share any configuration with composite builds or other included builds . Each included build is configured and executed independently .

The containing build interacts with other builds through dependency substitution . If any build in the composition has dependencies that can be satisfied by the included build , Then the dependency will be replaced by the project dependency containing the build . Due to the dependence on dependency substitution , Composite builds may force the configuration to be resolved earlier when combining task execution diagrams . This will have a negative impact on the overall build performance , Because these configurations are not solved in parallel .

By default ,Gradle You will try to identify the dependencies that can be replaced by the included build . however , For more flexibility , If Gradle The determined default replacement pair combination is incorrect , You can explicitly declare these substitutions .

In addition to using output through project dependencies , Composite builds can also declare task dependencies directly on included builds . Included builds are isolated , And you cannot declare dependencies on composite builds or other tasks that contain builds .

Define composite build

The following example demonstrates 2 individual Gradle Build various ways of combining into composite builds . For these examples ,my-utils Multi project construction will generate 2 Different java library （number-utils and string-utils）, also my-app The build will use the functions in these libraries to generate executable files .

my-app Building pairs my-utils There is no direct dependency . contrary , It declares that my-utils Binary dependency of the generated library .

file ：my-app/app/build.gradle

plugins {
    
    id 'application'
}

application {
    
    mainClass = 'org.sample.myapp.Main'
}

dependencies {
    
    implementation 'org.sample:number-utils:1.0'
    implementation 'org.sample:string-utils:1.0'
}

The way 1： Through the command --include-build Define composite build ：

The command line arguments will --include-build The executed build is transformed into a composite , Replace the dependencies in the included build with the executed build .

command ：gradle --include-build ../my-utils run

> gradle --include-build ../my-utils run
> Task :app:processResources NO-SOURCE
> Task :my-utils:string-utils:compileJava
> Task :my-utils:string-utils:processResources NO-SOURCE
> Task :my-utils:string-utils:classes
> Task :my-utils:string-utils:jar
> Task :my-utils:number-utils:compileJava
> Task :my-utils:number-utils:processResources NO-SOURCE
> Task :my-utils:number-utils:classes
> Task :my-utils:number-utils:jar
> Task :app:compileJava
> Task :app:classes

> Task :app:run
The answer is 42


BUILD SUCCESSFUL in 0s
6 actionable tasks: 6 executed

The way 2： adopt settings.gradle Define composite build ：

By using Settings.includeBuild(java.lang.Object) stay settings.gradle（ or Kotlin Medium settings.gradle.kts） The file declares the included build . The settings file can be used to add subprojects and included builds at the same time . Included builds are added by location .

One disadvantage of the above method is that it requires you to modify existing builds , Make it built as a stand-alone . One way to avoid this is to define a separate composite build , Its sole purpose is to combine other separate builds .

settings.gradle

rootProject.name = 'my-composite'

includeBuild 'my-app'
includeBuild 'my-utils'

under these circumstances , Executive “ Lord ” Construction is compound , It does not define any useful tasks to perform itself . In order to be in “my-app” Execute during construction “ function ” Mission , A composite build must define a delegated task .

build.gradle

tasks.register('run') {
    dependsOn gradle.includedBuild('my-app').task(':app:run')
}

---

---

---

Here are more details about the tasks that depend on the included build tasks .

Definition Gradle Construction of plug-ins

A special case of inclusion construction is definition Gradle Construction of plug-ins . You should use the set file block includeBuild Statements within contain these constructs .pluginManagement {} Use this mechanism , The included build can also provide a setup plug-in , The plug-in can be applied to the setting file itself .

settings.gradle

pluginManagement {
    includeBuild '../url-verifier-plugin'
}

Including plug-in construction through the plug-in management block is an incubation function . You can also use the includeBuild External stabilization mechanism pluginManagement To include plug-in builds . however , This does not support all use cases , Once the new mechanism is stable , Including such plug-in builds will be deprecated .

Limitations on included builds

Most builds can be included in compositions , Including other composite builds . But there are some limitations .

• must not rootProject.name Same as another included build .
• must not rootProject.name Same as the top-level project of composite construction .
• must not rootProject.name Same as composite construction rootProject.name.

Interact with composite builds

Usually , Interaction with composite builds is very similar to conventional multi project builds . Can perform tasks , You can run tests , And you can import the build IDE.

Perform tasks

Tasks in a composite build can be done from the command line or from your IDE perform . Executing a task will result in the execution of direct task dependencies , And the tasks required to build dependency artifacts from the included build .

You use a fully qualified path （ Usually :included-build-name:subproject-name:taskName. Sub project and task names can abbreviation . The included build name does not support this feature .

$ ./gradlew :included-build:subproject-a:compileJava
> Task :included-build:subproject-a:compileJava

$ ./gradlew :included-build:sA:cJ
> Task :included-build:subproject-a:compileJava

want Exclude tasks from the command line , You also need to provide a fully qualified path to the task .

The included build tasks are automatically executed to generate the required dependency artifacts , perhaps Included builds can declare dependencies on tasks that contain builds .

Import IDE

One of the most useful features of composite construction is IDE Integrate . By way of idea or eclipse Plug ins are applied to your build , You can generate a single IDEA or Eclipse project , This project allows all builds in the portfolio to be developed together .

In addition to these Gradle Beyond plug-ins , Latest version IntelliJ IDEA and Eclipse Buildship also Support direct import of composite construction .

Importing a composite build allows you to build from different Gradle Built sources are easily developed together . For each included build , Each subproject is included as a IDEA Module or Eclipse project . Configure source dependencies , Provide cross build navigation and refactoring .

Declare dependencies that are replaced by contained builds

By default ,Gradle Each included build will be configured , To determine the dependencies it can provide . The algorithm for performing this operation is very simple ：Gradle The group and name containing the project under construction will be checked , And replace any external dependency matches with project dependencies ${project.group}:${project.name}.

By default , No replacement will be registered for the main build . To make the main build （ Son ） The project can be through $project.group:${project.name} Addressing , You can tell Gradle Treat the main build as an inclusive build by self-contained it ：includeBuild(". ”）.

In some cases , from Gradle The determined default substitution is not enough , Or they are not correct for a particular combination . For these cases , You can explicitly declare the substitution that contains the build . Build with a single project “anonymous-library” For example , It generates a java Utility library , But do not declare group The value of the property ：

Example . Build without declaring group properties

build.gradle

plugins {
    id 'java'
}

When this build is included in the composition , It will try to replace the dependent module “undefined:anonymous-library”（“undefined” yes The default value of project.group,“anonymous-library” Is the root project name ）. obviously , This will not be very useful in composite construction . To use unmodified unpublished libraries in composite builds , A composite build can explicitly declare the alternatives it provides ：

Included build declaration replacement

settings.gradle

rootProject.name = 'declared-substitution'

include 'app'

// tag::composite_substitution[]
includeBuild('anonymous-library') {
    
    dependencySubstitution {
    
        substitute module('org.sample:number-utils') using project(':')
    }
}
// end::composite_substitution[]

Use this configuration ,“my-app” Composite construction will use org.sample:number-utils Yes “anonymous-library” The root project's dependencies replace any dependencies .

Composite build substitution does not work

Some builds will not work properly when included in a composite , This is true even if dependency substitution is explicitly declared . This limitation is due to the fact that the replaced project dependency will always point to default Configuration of the target project . Whenever the artifacts and dependencies specified for the default configuration of the project do not match what is actually published to the repository , Composite builds may behave differently .

The following are some cases where the metadata of the publishing module may be different from the default configuration of the project ：

• When publishing configurations other than default.
• Use maven-publish or ivy-publish When the plug-in .
• When POMorivy.xml When the document is adjusted as part of the release .

When included in a composite build , Builds that use these functions will not work properly . We plan to improve this in the future .

Depends on the tasks in the included build

Although the included builds are isolated from each other and cannot declare direct dependencies , But a composite build can declare task dependencies on the build it contains . Use Gradle.getIncludedBuilds() or Gradle.includedBuild(java.lang.String) Access the included build , And pass IncludedBuild.task(java.lang.String) Method to get the task reference .

Use these API, You can declare dependencies on tasks in specific included builds , Or declare a task with a specific path in all or part of the include build .

Current limitations and future plans for composite construction

Currently implemented limitations include ：

• Builds that contain publications that do not reflect the default configuration of the project are not supported . see also Situations where composite construction does not work .
• The establishment of this institution based on software model is not supported .（ This organization does not support binary dependencies ）.
• If multiple composite builds contain the same build , Then the parallel runtime may conflict .Gradle Not in Gradle The project lock of composite construction is shared between calls , To prevent concurrent execution .

The improvements we plan for the upcoming release include ：

• Make implicit buildSrc Projects become included builds .