Chapter 8. Introduction to multi-project builds multi-project construction Introduction, openbuilds

Chapter 8. Introduction to multi-project builds multi-project construction Introduction, openbuilds

Only the smallest of projects has a single build file and source tree, unless it happens to be a massive, monolithic application. it's often much easier to digest and understand a project that has been split into smaller, inter-dependent modules. the word "inter-dependent" is important, though, and is why you typically want to link the modules together through a single build.

Gradle supports this scenario throughMulti-projectBuilds.

8.1. Structure of a multi-project build

Such builds come in all shapes and sizes, but they do have some common characteristics:

// Some general features of gradle

• Asettings.gradleFile in the root ormasterDirectory of the project // There Is A settings. gradle file under the root directory of the project

• Abuild.gradleFile in the root ormasterDirectory // There is a build. gradle file under the root directory

• Child directories that have their own*.gradleBuild files (some multi-project builds may omit child project build scripts) // each subdirectory has its own *. gradle File

Thesettings.gradleFile tells Gradle how the project and subprojects are structured. Fortunately, you don't have to read this file simply to learn what the project structure is as you can run the commandgradle projects. Here's the output from using that command on the JavaMultiprojectBuild in the Gradle samples:

// The settings. gradle file tells the gradle project and subproject how they are organized. Fortunately, you don't need to read this file to understand the project structure. You can use the gradle projects command. Example:

Example 8.1. Listing the projects in a build

Outputgradle -q projects

> gradle -q projects------------------------------------------------------------Root project------------------------------------------------------------Root project 'multiproject'+--- Project ':api'+--- Project ':services'|    +--- Project ':services:shared'|    \--- Project ':services:webservice'\--- Project ':shared'To see a list of the tasks of a project, run gradle <project-path>:tasksFor example, try running gradle :api:tasks

 

This tells you thatMultiprojectHas three immediate child projects:Api,ServicesAndShared.ServicesProject then has its own children,SharedAndWebservice. These map to the directory structure, so it's easy to find them. For example, you can findWebserviceIn<root>/services/webservice.

Each project will usually have its own build file, but that's not necessarily the case. In the above example,ServicesProject is just a container or grouping of other subprojects. There is no build file in the corresponding directory. However,MultiprojectDoes have one for the root project.

// Each project usually has its own build file, but this is not necessary. In the preceding example, the services Project is the container of another sub-project, so there is no build file under the corresponding directory. Then, you must have a build file under the root directory for multiple projects.

The rootbuild.gradleIs often used to share common configuration between the child projects, for example by applying the same sets of plugins and dependencies to all the child projects. it can also be used to configure individual subprojects when it is preferable to have all the configuration in one place. this means you shoshould always check the root build file when discovering how a participant subproject is being configured.

// The build. gradle file under the root directory is usually used to share the common configuration of the Child project, for example, to apply the same plug-in settings to all child projects. It can also be used to configure the independent configuration of the sub-project, which means the build of the root directory when studying how a specific sub-project is configured. the gradle file must be viewed.

Another thing to bear in mind is that the build files might not be calledbuild.gradle. Your projects will name the build files after the subproject names, suchapi.gradleAndservices.gradleFrom the previous example. Such an approach helps a lot in IDEs because it's tough to work out whichbuild.gradleFile out of twenty possibilities is the one you want to open. This little piece of magic is handled bysettings.gradleFile, but as a build user you don't need to know the details of how it's done. Just have a look through the child project directories to find the files with.gradleSuffix.

// Another thing you need to know is that the build file may not be called build. gradle. Many projects will name their own build files under the Sub-Project. For exampleapi.gradleAndServices. gradle. This method helps IDE greatly, because it is difficult for ide to find the build file you want to open from more than 20 possible files. The processing logic is in the setting. gradle file.

Once you know what subprojects are available, the key question for a build user is how to execute the tasks within the project.

8.2. Executing a multi-project build

From a user's perspective, multi-project builds are still collections of tasks you can run. The difference is that you may want to controlWhichProject's tasks get executed. You have two options here:

// From the user's perspective, multi-project construction is still a collection of tasks that you can run. The difference is that you may want to control which project task to execute. Here you have two options:

• Change to the directory corresponding to the subproject you're interested in and just executegradle <task>As normal. // switch the directory to the sub-project directory to be built, and then execute it as normalgradle <task>

• Use a qualified task name from any directory, although this is usually done from the root. For example:gradle :services:webservice:buildWill buildWebserviceSubproject and any subprojects it depends on. // use the full name of the task name in any directory

The first approach is similar to the single-project use case, but Gradle works slightly differently in the case of a multi-project build. The commandgradle testWill executetestTask in any subprojects, relative to the current working directory, that have that task. So if you run the command from the root project directory, you'll runtestInApi,Shared,Services: sharedAndServices: webservice. If you run the command from the services project directory, you'll only execute the task inServices: sharedAndServices: webservice.

// The first method is similar to the method used in only one project, but the gradle operation is somewhat different in multiple projects. The command gradle test will execute all the test tasks in the sub-project, which will be executed if there is a test task relative to the current working directory. Therefore, if you run this command in the root directory, you will run the test task in api, shared, services: shared, services: webservice, if you run this command in the setvices project directory, you will only execute the test task in servics: shared and service: webservice.

For more control over what gets executed, use qualified names (the second approach mentioned ). these are paths just like directory paths, but use ': 'instead of'/'or '\'. if the path begins with a': ', then the path is resolved relative to the root project. in other words, the leading ': 'represents the root project itself. all other colons are path separators.

// Use the full name (the second method mentioned above) for more advanced control of execution content ). There is some path information like a directory path, but it uses the colon: instead of/. If the path starts with:, this path is relative to the root project. In other words, it starts: represents the root project itself. All other colons indicate path underscores.

This approach works for any task, so if you want to know what tasks are in a participant subproject, just usetasksTask, e.g.gradle :services:webservice:tasks.

// This method applies to all tasks. If you want to know which tasks exist in a specific project, execute the tasks task.

Regardless of which technique you use to execute tasks, Gradle will take care of building any subprojects that the target depends on. you don't have to worry about the inter-project dependencies yourself. if you're interested in how this is configured, you can read about writing multi-project builds later in the user guide.

There's one last thing to note. when you're using the Gradle wrapper, the first approach doesn' t work well because you have to specify the path to the wrapper script if you're not in the project root. for example, if you're inWebserviceSubproject directory, you wowould have to run../../gradlew build.

// When using the first method, if you want to execute the gradlew command, you need to switch to the root project directory:../../gradlew build

That's all you really need to know about multi-project builds as a build user. you can now identify whether a build is a multi-project one and you can discover its structure. and finally, you can execute tasks within specific subprojects.