<commit_before># Gogradle - 完善的Go语言构建工具

## 功能特性

- 除JDK 8+外无需预先安装任何东西（包括Go本身）
- 支持所有版本的Go且允许多版本共存
- 完美支持几乎所有平台（只要能够运行Java）
- 项目级的依赖隔离，无需设置GOPATH
- 完善的包管理
  - 无需手工安装依赖包，只需指定版本
  - 无需安装即可支持Go语言默认支持的四种版本控制工具：Git/Svn/Mercurial/Bazzar （当前只实现了Git）
  - 支持传递性依赖
  - 支持自定义传递性依赖策略
  - 自动解决冲突 
  - 支持依赖锁定
  - 支持glide/glock/godep/gom/gopm/govendor/gvt/gbvendor/trash等外部依赖的导入（基于[这份报告](https://github.com/blindpirate/report-of-go-package-management-tool)）
  - 支持[语义化版本](http://semver.org/)
  - 支持[vendor](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo)
  - 支持依赖的扁平化 （受[glide](https://github.com/Masterminds/glide)启发）
  - 支持本地包重命名
  - 支持私有仓库
  - 构建、测试依赖分别管理
  - 支持依赖树可视化
- 支持构建、测试、单个/通配符测试、交叉编译  
- 现代的、生产级别的自动化构建支持，添加自定义任务极其简单
- 原生的Gradle语法
- 额外为中国开发者提供的特性，你懂的
- IDE插件支持（计划中）

## 优势

- 完善的跨平台支持
- 支持所有主流外部依赖管理工具
- 100%测试覆盖率 （当然，这一点还在努力中）
- 长期维护
- 众多Gradle插件

## 入门指南

Gogradle是[Gradle](https://gradle.org/)的一个插件。Gradle是一个使用Groovy作为DSL的自动化构建工具，允许用户通过自定义的构建脚本来完成构建工作。
大多数情况下，你无需了解Gradle本身，只需要阅读本文档即可。

### 准备工作

- 安装[JDK 8+](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
- 将本项目中的`gradle`目录、`gradlew`（*nix）/`gradlew.bat`（Windows）文件拷贝到欲构建的Go语言项目目录下。
- 在欲构建的Go语言项目下新建`build.gradle`文件，内容如下：

```groovy
plugins {
    id "com.github.blindpirate.gogradle" version "0.1.0"
}

golang {
    packagePath = 'your/package/path'
}
```
如果你之前使用的是glide/glock/godep/gom/gopm/govendor/gvt/gbvendor/trash之一，那么无需任何设置，Gogradle会自动读取这些包管理工具保存在项目目录中的依赖锁定文件。在Gogradle进行过第一次构建后，它会在项目目录下生成自己的锁定文件`gogradle.lock`。一旦该文件生成，原先的包管理工具的依赖锁定文件就不会再生效，你可以选择删除它们。详见[依赖锁定](#依赖锁定)一节。

### 构建Go项目

进入项目目录，运行

```
./gradlew build # *nix

gradlew build # Windows
```

在下文中，`gradlew`命令将以统一的`gradlew <task>`形式给出，不再区分平台。

以上命令等价于在当前项目目录下运行`go build`，区别在于，Gogradle自动完成了依赖解析、安装等一系列过程。注意，Gogradle**不使用全局的`GOPATH`**，它会将所有的依赖安装在当前项目目录下并自动设置与构建相关的环境变量——这意味着构建是完全隔离的、可复现的。


### 测试Go项目

进入项目目录，运行 

```
gradlew test
```

测试指定文件：

```
gradlew test --tests github.com/my/package/subpackage // 必须是当前构建项目的子目录或者后代目录
gradlew test --tests main_test.go // 指定一个测试文件
gradlew test --tests *_test.go // 通配符测试
```

若希望构建在测试完成之后进行，只需在`build.gradle`中添加

```groovy
build.dependsOn test
```

### 添加依赖

欲添加一个指定版本的依赖，只需要在`build.gradle`中的`dependencies`中，添加对应的包和版本即可：

```groovy
dependencies {
    build 'github.com/a/b@v1.0.0' 
    test 'github.com/c/d#d3fbe10ecf7294331763e5c219bb5aa3a6a86e80'
}
```

其中，build和test分别是构建和测试的依赖，二者是独立的。构建时的环境中只包含声明为`build`的依赖包，测试时的环境中包含声明为`build`和`test`的依赖包。

有关依赖的详细解释，参考[依赖管理](#依赖管理)一节

### 查看依赖

```
gradlew dependencies
```

输出如下：

```
build:

github.com/gogits/gogs
├── github.com/Unknwon/cae:c6aac99 √
├── github.com/Unknwon/com:28b053d √
├── github.com/Unknwon/i18n:39d6f27 √
│   ├── github.com/Unknwon/com:28b053d √ (*)
│   └── gopkg.in/ini.v1:766e555 -> 6f66b0e
├── github.com/Unknwon/paginater:701c23f √
├── github.com/bradfitz/gomemcache:2fafb84 √
├── github.com/go-macaron/binding:4892016 √
│   ├── github.com/Unknwon/com:28b053d √ (*)
│   └── gopkg.in/macaron.v1:ddb19a9 √
│       ├── github.com/Unknwon/com:28b053d √ (*)
│       ├── github.com/go-macaron/inject:d8a0b86 -> c5ab7bf
│       └── gopkg.in/ini.v1:766e555 -> 6f66b0e (*)
... 

```

这是[gogs](https://github.com/gogits/gogs)项目v0.9.113的依赖树。其中，对号(√)代表该依赖包即最终的依赖包；
箭头(->)代表该依赖包与其他依赖包冲突，因此被解析成了另外一个版本；星号(*)代表本节点之前已经显示过，因此忽略其后代。

### 依赖锁定

```
./gradlew lock # *nix

gradlew lock # Windows <commit_msg>Improve docs<commit_after># Gogradle - 完善的Go语言构建工具

Gogradle是一个提供Go语言构建支持的Gradle插件。

## 功能特性

- 除JDK 8+外无需预先安装任何东西（包括Go本身）
- 支持所有版本的Go且允许多版本共存
- 完美支持几乎所有平台（只要能够运行Java）
- 项目级的依赖隔离，无需设置GOPATH
- 完善的包管理
  - 无需手工安装依赖包，只需指定版本
  - 无需安装即可支持Go语言默认支持的四种版本控制工具：Git/Svn/Mercurial/Bazzar （当前只实现了Git）
  - 支持传递性依赖
  - 支持自定义传递性依赖策略
  - 自动解决冲突 
  - 支持依赖锁定
  - 支持glide/glock/godep/gom/gopm/govendor/gvt/gbvendor/trash等外部依赖的导入（基于[这份报告](https://github.com/blindpirate/report-of-go-package-management-tool)）
  - 支持[语义化版本](http://semver.org/)
  - 支持[vendor](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo)
  - 支持依赖的扁平化 （受[glide](https://github.com/Masterminds/glide)启发）
  - 支持本地包重命名
  - 支持私有仓库
  - 构建、测试依赖分别管理
  - 支持依赖树可视化
- 支持构建、测试、单个/通配符测试、交叉编译  
- 现代的、生产级别的自动化构建支持，添加自定义任务极其简单
- 原生的Gradle语法
- 额外为中国大陆开发者提供的特性，你懂的
- IDE插件支持（计划中）

## 优势

- 完善的跨平台支持
- 支持所有主流外部依赖管理工具
- 完善的测试覆盖
- 长期维护
- 众多Gradle插件

## 入门指南

Gogradle是[Gradle](https://gradle.org/)的一个插件。Gradle是一个使用Groovy作为DSL的自动化构建工具，允许用户通过自定义的构建脚本来完成构建工作。
大多数情况下，你无需了解Gradle本身，只需要阅读本文档即可。

### 准备工作

- 安装[JDK 8+](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
- 将本项目中的`gradle`目录、`gradlew`（*nix）/`gradlew.bat`（Windows）文件拷贝到欲构建的Go语言项目目录下。
- 在欲构建的Go语言项目下新建`build.gradle`文件，内容如下：

```groovy
plugins {
    id "com.github.blindpirate.gogradle" version "0.1.0"
}

golang {
    packagePath = 'your/package/path'
}
```
如果你之前使用的是glide/glock/godep/gom/gopm/govendor/gvt/gbvendor/trash之一，那么无需任何设置，Gogradle会自动读取这些包管理工具保存在项目目录中的依赖锁定文件。在Gogradle进行过第一次构建后，它会在项目目录下生成自己的锁定文件`gogradle.lock`。一旦该文件生成，原先的包管理工具的依赖锁定文件就不会再生效，你可以选择删除它们。详见[依赖锁定](#依赖锁定)一节。

### 构建Go项目

进入项目目录，运行

```
./gradlew build # *nix

gradlew build # Windows
```

在下文中，`gradlew`命令将以统一的`gradlew <task>`形式给出，不再区分平台。

以上命令等价于在当前项目目录下运行`go build`，区别在于，Gogradle自动完成了依赖解析、安装等一系列过程。注意，Gogradle**不使用全局的`GOPATH`**，它会将所有的依赖安装在当前项目目录下并自动设置与构建相关的环境变量——这意味着构建是完全隔离的、可复现的。


### 测试Go项目

进入项目目录，运行 

```
gradlew test
```

测试指定文件：

```
gradlew test --tests github.com/my/package/subpackage // 必须是当前构建项目的子目录或者后代目录
gradlew test --tests main_test.go // 指定一个测试文件
gradlew test --tests *_test.go // 通配符测试
```

若希望构建在测试完成之后进行，只需在`build.gradle`中添加

```groovy
build.dependsOn test
```

### 添加依赖

欲添加一个指定版本的依赖，只需要在`build.gradle`中的`dependencies`中，添加对应的包和版本即可：

```groovy
dependencies {
    build 'github.com/a/b@v1.0.0' 
    test 'github.com/c/d#d3fbe10ecf7294331763e5c219bb5aa3a6a86e80'
}
```

其中，build和test分别是构建和测试的依赖，二者是独立的。构建时的环境中只包含声明为`build`的依赖包，测试时的环境中包含声明为`build`和`test`的依赖包。

有关依赖的详细解释，参考[依赖管理](#依赖管理)一节

### 查看依赖

```
gradlew dependencies
```

输出如下：

```
build:

github.com/gogits/gogs
├── github.com/Unknwon/cae:c6aac99 √
├── github.com/Unknwon/com:28b053d √
├── github.com/Unknwon/i18n:39d6f27 √
│   ├── github.com/Unknwon/com:28b053d √ (*)
│   └── gopkg.in/ini.v1:766e555 -> 6f66b0e
├── github.com/Unknwon/paginater:701c23f √
├── github.com/bradfitz/gomemcache:2fafb84 √
├── github.com/go-macaron/binding:4892016 √
│   ├── github.com/Unknwon/com:28b053d √ (*)
│   └── gopkg.in/macaron.v1:ddb19a9 √
│       ├── github.com/Unknwon/com:28b053d √ (*)
│       ├── github.com/go-macaron/inject:d8a0b86 -> c5ab7bf
│       └── gopkg.in/ini.v1:766e555 -> 6f66b0e (*)
... 

```

这是[gogs](https://github.com/gogits/gogs)项目v0.9.113的依赖树。其中，对号(√)代表该依赖包即最终的依赖包；
箭头(->)代表该依赖包与其他依赖包冲突，因此被解析成了另外一个版本；星号(*)代表本节点之前已经显示过，因此忽略其后代。

### 依赖锁定

```
gradlew lock
{'fraction_non_alphanumeric': 0.16612377850162866, 'fraction_numerical': 0.03953212910867634, 'mean_word_length': 5.124206708975521, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 13, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5121248', 'n_tokens_mistral': 4681, 'n_tokens_neox': 5093, 'n_words': 323}