翻译--Gradle之Java工程入门

原文地址 http://www.gradle.org/docs/current/userguide/tutorial_java_projects.html

 

7.1. The Java plugin插件

我们已经看到Gradle是一个通用构建工具，它可以完成相当多的任务，只要你能在脚本里定义好。如果你没写好脚本，它就啥也干不成。

大部分Java项目都是这样的流程：编译源文件，单元测试，打成jar包。你希望不用每次都为每个项目搞下这个。你的小清新到了：Gradle通过插件解决了这个问题。一个插件就是一个Gradle扩展，它以某种方式配置项目。一般会预配置一些任务来一起完成某个目标。Gradle 自带了不少插件，你还可以自己写，并分享给别人。其中的Java插件（ Java plugin）可以实现编译测试打包任务。这个插件是基于约定的，它定义了工程的很多默认值，比如源文件位置等。如果就照着它的约定，你就不用怎么改构建脚本了。如果不想或者不能，你可以自己写。实际上，既然对Java项目的支持是一个插件实现的，你完全可以不用插件来构建。

后面我会通过很多例子来讲Java插件的依赖管理和多工程构建等。不过首先我们要看到的是怎么使用Java插件。

7.2. A basic Java project简单的Java工程

要使用Java插件，在脚本里写一句这个（是不是有点像play!框架的插件配置）:

Example 7.1. Using the Java plugin

build.gradle

apply plugin: 'java'

Note: The code for this example can be found at samples/java/quickstart which is in both the binary and source distributions of Gradle.

这样就增加了Java插件功能，也就配好了一些任务。Gradle默认希望你的源代码在 src/main/java 而测试源代码在src/test/java，资源目录是src/main/resources，测试资源是src/test/resources。输出目录是build 文件夹。需要的jar文件在build/libs下面。

What tasks are available?

 gradle tasks 命令可以列出当前工程的全部任务。你可以看看到底Java插件增加了什么任务。

7.2.1. Building the project开始搞

Java插件会增加一些默认任务，不过你应该不会全都需要。一般需要的任务是 build, 它会完整构建你的项目。运行 gradle build就行:

Example 7.2. Building a Java project

Output of gradle build

> gradle build
:compileJava
:processResources
:classes
:jar
:assemble
:compileTestJava
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL

Total time: 1 secs

其他的任务比如:

clean

删除 build 目录和所有构建文件。

assemble

编译和打包，不进行单元测试。结合其他插件可以实现额外功能。比如加入War插件后这个任务还回生成war包。

check

编译和测试，也可以结合其他插件，比如Code-quality插件会额外执行Checkstyle 

7.2.2. External dependencies外部依赖

要引用外部jar包，就要告诉Gradle它们的位置。Gradle的引用在repository 属性下。比如要引用Maven库的包：:

Example 7.3. Adding Maven repository

build.gradle

repositories {
    mavenCentral()
}

Let's add some dependencies. 咱们加一些依赖试试，比如我们的发行版有一个commons collections运行时依赖，测试类则依赖的是 junit:

Example 7.4. Adding dependencies

build.gradle

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

更多信息去看看 Chapter 8, Dependency Management Basics.

7.2.3. customizing the project手动配置工程

Java插件增加了一些属性，要修改Java插件属性的默认值也很简单，看一个例子。比如我们要指定版本号，并增加一些manifest属性。

Example 7.5. Customization of MANIFEST.MF

build.gradle

sourceCompatibility = 1.5
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart', 'Implementation-Version': version
    }
}

What properties are available?

gradle properties 命令可以列出工程的属性，可以看到Java插件到底增加了什么属性，它们的值是多少。

Java插件增加的都是普通任务，和构建脚本里的一样。所以前面学到的那些机制可以随便用。，比如设置属性值，增加任务行为，修改任务依赖，甚至取代任务。我们配置一个 test 任务，它是Test类型的，让它执行时增加系统属性：

Example 7.6. Adding a test system property

build.gradle

test {
    systemProperties 'property': 'value'
}

7.2.4. Publishing the JAR file发布

一般jar需要发布到一个地方，所以你要告诉Gradle发布到哪。默认是发布到库里面。我们让它发布到本地目录，你愿意的话可以发布到远程或者同时多个地方。

Example 7.7. Publishing the JAR file

build.gradle

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

要发布jar包，执行 gradle uploadArchives.

7.2.5. Creating an Eclipse project转成Eclipse项目

要导入到Eclipse里面需要另一个插件：

Example 7.8. Eclipse plugin

build.gradle

apply plugin: 'eclipse'

现在执行 gradle eclipse 可以生成Eclipse项目文件。更多Eclipse任务操纵见 Chapter 38, The Eclipse Plugin.

7.2.6. Summary总结

这是完整的构建文件：

Example 7.9. Java example - complete build file

build.gradle

apply plugin: 'java'
apply plugin: 'eclipse'

sourceCompatibility = 1.5
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart', 'Implementation-Version': version
    }
}

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

test {
    systemProperties 'property': 'value'
}

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

 

7.3. Multi-project Java build多工程构建

现在来看多工程构建。下面是工程结构：

Example 7.10. Multi-project build - hierarchical layout

Build layout

multiproject/
  api/
  services/webservice/
  shared/

Note: The code for this example can be found at samples/java/multiproject which is in both the binary and source distributions of Gradle.

我们有三个工程： api 工程用来生成给客户端用的jar文件，这个jar文件可以为XML webservice 提供Java客户端。webservice 是一个web应用，生成 XML。shared 工程包含的是前述两个工程共用的代码。

7.3.1. Defining a multi-project build定义

要定义多工程构建需要一个“设置文件”(settings file)，这个文件在项目的根目录下，指明哪些工程要被处理。它的名字叫 settings.gradle. 对于我们的例子来说，对应的设置文件是这样的：

Example 7.11. Multi-project build - settings.gradle file

settings.gradle

include "shared", "api", "services:webservice", "services:shared"

更多信息看56章： Chapter 56, Multi-project Builds.

7.3.2. Common configuration公共配置

多工程构建一般会有配置是各工程都会用到的。比如我们的例子会通过“配置注入（ configuration injection）”来实现，在根项目下定义一个公共配置。根项目就像一个容器，子项目会迭代访问它的配置并注入到自己的配置中。这样我们就可以简单的为所有工程定义主配置单了：

Example 7.12. Multi-project build - common configuration

build.gradle

subprojects {
    apply plugin: 'java'
    apply plugin: 'eclipse-wtp'

    repositories {
       mavenCentral()
    }

    dependencies {
        testCompile 'junit:junit:4.11'
    }

    version = '1.0'

    jar {
        manifest.attributes provider: 'gradle'
    }
}

我们使用了Java插件，这样所有的工程都有了该特性。所以你可以在跟项目下通过 gradle build 编译、测试、打包了。

7.3.3. Dependencies between projects工程依赖

同一个构建中可以建立工程依赖，这样比如说，一个工程的jar文件就可以给另一个工程使用了。我们给 api 工程的构建增加对  shared 工程jar的依赖。这样Gradle会保证构建api工程之前总要构建shared。

Example 7.13. Multi-project build - dependencies between projects

api/build.gradle

dependencies {
    compile project(':shared')
}

Section 56.7.1, “Disabling the build of dependency projects”讲了如何停用这个功能。

7.3.4. Creating a distribution发布

要发布到客户端就这样：

Example 7.14. Multi-project build - distribution file

api/build.gradle

task dist(type: Zip) {
    dependsOn spiJar
    from 'src/dist'
    into('libs') {
        from spiJar.archivePath
        from configurations.runtime
    }
}

artifacts {
   archives dist
}