Chapter 8. Introduction to multi-project builds 多工程构建介绍

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 through multi-project builds.

8.1. Structure of a multi-project build

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

//gradle具有的一些通用的特性

• A settings.gradle file in the root or master directory of the project  //在项目的根目录下有一个settings.gradle文件

• A build.gradle file in the root or master directory   //在根目录下有一个build.gradle文件

• Child directories that have their own *.gradle build files (some multi-project builds may omit child project build scripts)  //每个子目录有他们自己的*.gradle文件

The settings.gradle file 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 command gradle projects. Here's the output from using that command on the Java multiproject build in the Gradle samples:

//settings.gradle文件告诉gradle工程和子工程是如何被组织的。幸运的是，你不需要读这个文件来了解项目结构，你可以使用gradle projects命令。例子如下：

Example 8.1. Listing the projects in a build

Output of gradle -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>:tasks
For example, try running gradle :api:tasks

This tells you that multiproject has three immediate child projects: api, services and shared. The services project then has its own children, shared and webservice. These map to the directory structure, so it’s easy to find them. For example, you can find webservice in <root>/services/webservice.

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

//每一个项目通常会有一个自己的build文件，但是这不是必须要有的。在上面的例子中，services工程就是一个其他子工程的容器，因此在其对应的目录下没有build文件。然后多工程必须在根目录下有一个build文件

The root build.gradle is 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 should always check the root build file when discovering how a particular subproject is being configured.

//根目录下的build.gradle文件通常被用来共享子工程的通用配置，例如给所有的子工程应用相同的插件设置。它也可以用来配置子工程的独立配置，这意味着当研究某一个特定子工程是如何被配置的问题时，根目录的build.gradle文件应该是需要查看的。

Another thing to bear in mind is that the build files might not be called build.gradle. Many projects will name the build files after the subproject names, such asapi.gradle and services.gradle from the previous example. Such an approach helps a lot in IDEs because it’s tough to work out which build.gradle file out of twenty possibilities is the one you want to open. This little piece of magic is handled by the settings.gradle file, 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 the .gradle suffix.

//另一个事需要了解的是，build文件可能不叫build.gradle.很多工程会自己命名子工程下的build文件，例如上面例子中的api.gradle 和 services.gradle.这种方法帮了IDE很大的忙，因为让ide从20多重可能的文件中找到你想要打开的那个build文件是艰难的。这个处理逻辑在setting.gradle文件中。

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 control which project's tasks get executed. You have two options here:

//从用户的角度看，多工程构建仍然是一堆你可以运行的任务的集合。不同的是，你可能想去控制哪个工程的任务来执行，这里你有两个选项：

• Change to the directory corresponding to the subproject you’re interested in and just execute gradle <task> as normal.  //切换目录到需要构建的子工程目录下，然后像正常情况一样执行gradle <task>

• Use a qualified task name from any directory, although this is usually done from the root. For example: gradle :services:webservice:build will build the webservicesubproject and any subprojects it depends on.    //在任何目录下使用全称的任务名

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 command gradle test will execute the test task 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 run test inapi, shared, services:shared and services:webservice. If you run the command from the services project directory, you’ll only execute the task in services:shared andservices:webservice.

//第一种方法和在只有一个工程的项目中使用方法是相似的，但是在多工程的项目中gradle的操作会有一些不同。命令gradle test将会执行所有子工程中的test任务，相对于当前的工作目录并且有test任务的都会执行。所以，如果你在根目录运行这个命令，你将会运行在api,shared,services：shared,services:webservice中的test任务，如果你在setvices工程目录中运行这个命令，你将只会执行在servics:shared和service:webservice中的test任务

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.

//想要更高级的控制执行的内容，使用全称名字（上面提到的第二种办法）。有一些像目录路径一样的路径信息，但是使用冒号：而不是/,如果路径以：开头，那么这个路径就是相对根工程而言的，换句话说，开头的：代表根工程它自己。所有其他的冒号表示的是路径下划线。

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

//这个方法适用于所有的任务。如果你想知道在某一个特定子工程中有哪些task，执行tasks任务。

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 in the webservice subproject directory, you would have to run ../../gradlew build.

//使用第一种方法时候如果想要执行gradlew命令，需要切到根工程目录下：../../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.