翻譯--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/      

samples/java/multiproject

我們有三個工程： 

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
}