build.gradle 的结构 - CUBA 框架开发者手册

4.3.1. build.gradle 的结构

本章节介绍 build.gradle 脚本的结构和主要元素。

buildscript

脚本的 buildscript 部分定义了以下内容：

平台的版本。
一组用来加载项目依赖的仓库。查看仓库章节了解如何配置仓库。
构建系统的依赖，包括 CUBA 的 Gradle 插件。

在 buildscript 下面，是一些变量的定义。会在后面的脚本中用到。

cuba

CUBA 特殊的构建逻辑封装在 cuba Gradle 插件里。CUBA 插件在构建脚本的根节点引用，同时也需要在所有模块的 configure 部分使用下面这个语句引用进来：

apply(plugin: 'cuba')

cuba 插件的配置在 cuba 部分定义：

cuba {
    artifact {
        group = 'com.company.sales'
        version = '0.1'
        isSnapshot = true
    }
    tomcat {
        dir = "$project.rootDir/build/tomcat"
    }
    ide {
        copyright = '...'
        classComment = '...'
        vcs = 'Git'
    }
}

以下是一些可选的参数：

artifact - 这里定义项目工件的分组和版本信息。工件的名称按照 settings.gradle 里面设置的模块名称来设置。
- group - 工件组
- version - 工件版本
- isSnapshot - 如果设置 true，工件名称会被添加 SNAPSHOT 后缀。
  
  可以通过命令行参数来覆盖工件的版本，示例：
  gradle assemble -Pcuba.artifact.version=1.1.1
tomcat - 这部分定义了用来快速部署的 Tomcat 服务的设置。
- dir - Tomcat 的安装目录。
- port - Tomcat 监听端口，默认 8080。
- debugPort - Java 调试监听端口，默认 8787。
- shutdownPort - 监听 SHUTDOWN 命令的端口，默认 8005。
- ajpPort - AJP 连接器端口，默认 8009。
ide - 这部分包含 Studio 和 IDE 的内容
- vcs - 项目的版本控制系统配置，目前只支持 Git 或者 svn。
- copyright - 插入到每个源文件开头的版权信息。
- classComment - Java 源文件类声明开头插入的注释信息。
uploadRepository - 这部分定义了使用 uploadArchives 任务上传打包的项目工件目标仓库的设置。
- url - 仓库的地址 URL。如果不设置，默认会使用 Haulmont 的仓库地址。
- user - 访问仓库的用户名。
- password - 访问仓库的密码。
  
  也可以通过命令行参数的方式给这个上传仓库的任务提供参数：
  gradlew uploadArchives -PuploadUrl=http://myrepo.com/content/repositories/snapshots -PuploadUser=me -PuploadPassword=mypassword

dependencies

这部分包含了项目中使用的一组应用程序组件。有两种添加组件依赖的方式：appComponent - 用于添加 CUBA 应用程序组件；uberJar - 用于添加需要在应用程序启动之前加载的库。组件通过他们各自的 global 模块来指定。在下面的例子中，使用了三个组件：com.haulmont.cuba (cuba 平台组件), com.haulmont.reports (reports premium 组件) 和 com.company.base (自定义组件)：

dependencies {
  appComponent("com.haulmont.cuba:cuba-global:$cubaVersion")
  appComponent("com.haulmont.reports:reports-global:$cubaVersion")
  appComponent("com.company.base:base-global:0.1-SNAPSHOT")
}

configure

configure 部分包含模块的配置。其中最主要的部分就是声明依赖，示例：

configure(coreModule) {

    dependencies {
        // standard dependencies using variables defined in the script above
        compile(globalModule)
        provided(servletApi)
        jdbc(hsql)
        testRuntime(hsql)
        // add a custom repository-based dependency
        compile('com.company.foo:foo:1.0.0')
        // add a custom file-based dependency
        compile(files("${rootProject.projectDir}/lib/my-library-0.1.jar"))
        // add all JAR files in the directory to dependencies
        compile(fileTree(dir: 'libs', include: ['*.jar']))
    }

对于 core，web 和 portal 模块（带有 CubaDeployment 类型 gradle 任务的模块），您可以通过 server 配置添加依赖。例如，在 UberJar 部署时，需要在应用程序启动之前访问依赖库，并且该库对于某个特定模块无论用何种部署选项都需要。那么，可以在模块中单独声明该依赖（这是必要的，比如，对于 WAR 部署时），因为如果在项目级别通过 uberjar 配置的话，会导致不必要的重复依赖。这些依赖会在执行 deploy，buildWar 和 buildUberJar 任务时被放置在 server 的 libs 中。

entitiesEnhancing 配置模块用来对实体类进行字节码增强（weaving - 也叫织入），至少需要在 global 模块声明这个任务，也可以在其它模块分别声明。

这里的 main 和 test 分别是项目和测试的代码目录，可选的 persistenceConfig 参数用来指定各自的 persistence.xml 文件。如果这个可选参数没设置，这个任务会对 CLASSPATH 里能找到的 *persistence.xml 文件中的所有实体做增强。

configure(coreModule) {
    ...
    entitiesEnhancing {
        main {
            enabled = true
            persistenceConfig = 'custom-persistence.xml'
        }
        test {
            enabled = true
            persistenceConfig = 'test-persistence.xml'
        }
    }
}

非标准的模块依赖可以在 Studio 中通过 CUBA 项目视图的 Project properties 部分来设置。

对于动态版本依赖和版本冲突的问题，可以用 Maven 对此场景的解决方法。按照这个方法，正式版本的优先级会高于快照版本，而且越新的版本有越精确的版本编号。所有条件都一样的情况下，版本编号按照字母表的顺序定优先级，示例：

1.0-beta1-SNAPSHOT         // 最低优先级
1.0-beta1
1.0-beta2-SNAPSHOT         |
1.0-rc1-SNAPSHOT           |
1.0-rc1                    |
1.0-SNAPSHOT               |
1.0                        |
1.0-sp                     V
1.0-whatever
1.0.1                      // 最高优先级

有的时候，项目恰巧需要某些库的特定版本，但是由于传递依赖，导致这个库的另外一个版本已经出现在依赖树中了。比如，您需要使用 CUBA 平台的 7.2-SNAPSHOT 版本，但是同时又使用了一个基于版本 7.2.0 构建的又一次新组建。根据上面解释的依赖优先级，最后组装的项目会使用平台版本 7.2.0，尽管 build.gradle 中已经声明了 ext.cubaVersion = '7.2-SNAPSHOT'。

为解决这个问题，可以在 build.gradle 文件中如下配置 Gradle 的依赖解决方案：

allprojects {
    configurations {
        all {
            resolutionStrategy.eachDependency { details ->
                if (details.requested.group == 'com.haulmont.cuba') {
                    details.useVersion '7.2-SNAPSHOT'
                }
            }
        }
    }
}

这段代码中，我们添加了一条规则，所有的 com.haulmont.cuba 依赖都使用 7.2-SNAPSHOT 版本。