ipfs的御用包管理器 gx入门指南

何为 gx

源码位置：https://github.com/whyrusleeping/gx|

官方称其为一个通用包管理器，构建于 IPFS 之上，gx 最初的设计灵感来自 nodejs 的 npm ，用来处理 golang 项目中的依赖包。如果从源码来欣赏 IPFS 并且心存二次开发的愿望，那么对 gx 的掌握还是非常有必要的。

本人在年初学习 IPFS (v0.4.12) 时并没有重视 gx 这个工具，甚至还在二次开发的过程中放弃了 gx 而改用 govendor 来进行 deps 的管理，这在后期升级 libp2p 时简直就是一场灾难。由于工作需要现在又需要使用 go-libp2p 来做一个 p2p 应用，所以下定决心一定要征服 gx

想要了解更多需要仔细阅读源码的 README，此处用来简要说明这个工具的使用方法，希望对使用 go-ipfs 和 go-libp2p 的同学能起到一些帮助的作用

工具要求

使用 gx 前本地一定要先启动 ipfs daemon ，版本也是有要求的，用最新版 ipfs 总是没错的。
如果没有启动 ipfs 那么 gx 会从 ipfs.io 这个公共网关获取资源，在国内这个网关几乎是不可用的。

安装 gx

$ go get -u github.com/whyrusleeping/gx

前提是已经安装和配置了最新版的 golang

工具会安装在
$GOPATH/src/github.com/whyrusleeping/gx
并且会 install 到 $GOPATH/bin
不要忘记把 bin 目录放到 PATH 中哦

使用 gx

创建和发布一个包：

$ gx init
$ gx publish

创建一个 golang 的工程，并在工程工程根目录gx init 后，会生成一个 package.json 文件用来描述你的库，执行 gx publish 后将会得到一个 hash 值，这是与你当前库的版本相对应的唯一ID，以后导入包时需要使用。

安装 gx包

当你在 github 上 clone 了一个 gx 包时，这个包很可能用 gx 管理了本地的依赖，所以你要通过 gx install 或者 gx i 这个子命令来进行安装，此时依赖包也会一并被安装到 GOPATH$/src/gx/ipfs 这个目录中。

导入依赖

导入一个依赖非常简单，只要知道 hash 通过 import 即可完成导入

$ gx import QmaDFJvcHAnxpnMwcEh6VStYN4v4PB4S16j4pAuC2KSHVr

gx 会去 ipfs 中下载这个 hash 对应的包并且这个包的 hash、版本、名字 都会出现在你的 package.json 中

$ gx deps
go-log QmSpJByNKFX1sCsHBEp3R73FL4NF6FnQTEGyNAXHm2GS52 1.2.0
go-libp2p-peer QmWXjJo15p4pzT7cayEwZi2sWgJqLnGDof6ZGMh9xBgU1p 2.0.4
......

查看直接依赖，还可以通过 -r -s 来查看全部依赖

$ gx deps -r -s
go-base58  QmT8rehPR3F6bmwL6zjUN8XpiDBFFpMP2myPdC6ApsWfJf 0.0.0
go-crypto  Qme1boxspcQWR8FBzMxeppqug2fYgYc15diNWmqgDVnvn2 0.0.0
go-datastore QmbzuUusHqaLLoNTDEVLcSF6vZDHZDLPC7p4bztRvvkXxU 1.0.0
go-ipfs-util QmZNVWh8LLjAavuQ2JXuFmuYH3C11xo988vSgp7UQrTRj1 1.0.0
go-keyspace  QmUusaX99BZoELh7dmPgirqRQ1FAmMnmnBn3oiqDFGBUSc 1.0.0
go-libp2p-crypto QmVoi5es8D5fNHZDqoW6DgDAEPEV5hQp8GBz161vZXiwpQ 1.0.4
go-libp2p-peer QmWXjJo15p4pzT7cayEwZi2sWgJqLnGDof6ZGMh9xBgU1p 2.0.4
go-libp2p-peerstore QmYkwVGkwoPbMVQEbf6LonZg4SsCxGP3H7PBEtdNCNRyxD 1.2.5
......

还可以通过 --tree 选项来查看完整的 依赖树

$ gx deps --tree
├─ go-base58 QmT8rehPR3F6bmwL6zjUN8XpiDBFFpMP2myPdC6ApsWfJf 0.0.0
├─ go-multihash  QmYf7ng2hG5XBtJA3tN34DQ2GUN5HNksEw1rLDkmr6vGku 0.0.0
│ ├─ go-base58  QmT8rehPR3F6bmwL6zjUN8XpiDBFFpMP2myPdC6ApsWfJf 0.0.0
│ └─ go-crypto  Qme1boxspcQWR8FBzMxeppqug2fYgYc15diNWmqgDVnvn2 0.0.0
├─ go-ipfs-util  QmZNVWh8LLjAavuQ2JXuFmuYH3C11xo988vSgp7UQrTRj1 1.0.0
│ ├─ go-base58  QmT8rehPR3F6bmwL6zjUN8XpiDBFFpMP2myPdC6ApsWfJf 0.0.0
│ └─ go-multihash QmYf7ng2hG5XBtJA3tN34DQ2GUN5HNksEw1rLDkmr6vGku 0.0.0
......

全部显示出来通常不是我查看依赖的需求，更常用的是针对某个库进行检查，gx 同时提供了 --highlight 选项来过滤感兴趣的内容

$ gx deps --tree --highlight=go-crypto
├─ go-multihash  QmYf7ng2hG5XBtJA3tN34DQ2GUN5HNksEw1rLDkmr6vGku 0.0.0
│ └─ go-crypto  Qme1boxspcQWR8FBzMxeppqug2fYgYc15diNWmqgDVnvn2 0.0.0
├─ go-ipfs-util  QmZNVWh8LLjAavuQ2JXuFmuYH3C11xo988vSgp7UQrTRj1 1.0.0
│ └─ go-multihash QmYf7ng2hG5XBtJA3tN34DQ2GUN5HNksEw1rLDkmr6vGku 0.0.0
│  └─ go-crypto Qme1boxspcQWR8FBzMxeppqug2fYgYc15diNWmqgDVnvn2 0.0.0
......

这个过滤后的树是前一个树的子集，而且仅显示出现在叶子节点上的 highlight 包

• gx deps 还有两个自命令 'dupes' 和 'stats' 。
  gx deps dupes 用来帮助我们查看重复导入的库，例如相同的库 在不同位置导入了 不同的 hash。
  gx deps stats 用来输出关于依赖的状态信息，包括 Total Import Count、Unique Import Count 、Average Import Depth ，可以大概用来了解依赖关系的复杂度。

注意：gx import这个操作会去修改我们已经写好的代码，例如：

我们在没有使用 gx 时，导入了 go-lightrpc/rpcserver

import "github.com/cc14514/go-lightrpc/rpcserver"

之后我们将 go-lightrpc 通过 gx publish发布得到 QmYaVXmXZNpWs6owQ1rk5VAiwNinkTh2cYZuYx1JDSactL 这个 hash

执行 gx import QmYaVXmXZNpWs6owQ1rk5VAiwNinkTh2cYZuYx1JDSactL

import "gx/ipfs/QmYaVXmXZNpWs6owQ1rk5VAiwNinkTh2cYZuYx1JDSactL/go-lightrpc/rpcserver"

查看代码时你会发现工程中所有导入了 go-lightrpc 的地方都被替换了

依赖关系的设计原则

设计程序依赖时尽量遵循以下原则：
1、依赖关系深度最小化
2、尽量让依赖树的广度最小化，但是不要以牺牲深度作为代价

更新

使用 gx 更新依赖非常简单

$ gx update mypkg QmbH7fpAV1FgMp6J7GZXUV6rj6Lck5tDix9JJGBSjFPgUd

其中 mypkg 指依赖包的 name ，可以在 package.json 中找到要更新的 mypkg ，也可以通过 gx deps 来找到对应的 mypkg.

也可以只提供要更新的包的 hash

$ gx update QmbH7fpAV1FgMp6J7GZXUV6rj6Lck5tDix9JJGBSjFPgUd

这样做时 gx 会去下载这个 hash 后检查名称并更新项目中对应的名称。

这里要顺便说一句，看过官方文档你会发现还有一个叫 gx-go 的工具，可以帮你自动把 gx 依赖导入 govendor 来管理，现在是动荡期，这个工具暂时就不推荐使用了，不出意外的话我们很快就要像送别 godeps 一样送别 govendor 了。

其实gx update 还有一个很让人期待的选项 '--with-deps'，顾名思义，他会帮助我们深度更新依赖的依赖 , 但遗憾的是这个功能尚不能达到生产级别，可以跟随gx每个版本的更新来体验其可用性，现在还是实验阶段。

Publishing and Releasing

如果你要 publish 一个库，但是并没有修改版本号，那么默认是不允许的，可以通过 '-f' 选项来强制发布。版本号记录在 package.json 中，升级版本号可以通过 gx version 这个子命令来完成

$ gx version 5.11.4

版本号的格式通常遵循 : major.minor.patch 原则，所以可以直接用下面方式更新

$ gx version patch
updated version to: 5.11.5
$ gx version minor
updated version to: 5.12.0
$ gx version major
updated version to: 6.0.0

使用 gx 更新工程时通常会做如下操作：

$ gx version minor
updated version to: 6.1.0

$ gx publish
package whys-awesome-package published with hash: QmaoaEi6uNMuuXKeYcXM3gGUEQLzbDWGcFUdd3y49crtZK

$ git commit -a -m "gx publish 6.1.0"
[master 5c4d36c] gx publish 6.1.0
 2 files changed, 3 insertions(+), 2 deletions(-)

为了自动执行以上脚本，可以使用 release 子命令 gx release <version>将会自动帮你执行 version update 和 publish ，随后会执行你在 package.json 中通过 releaseCmd 设置的指令，例如去获取你设置的 git commit -a -m \"gx publish $VERSION\"，执行时 gx 会用 version 来覆盖 $VERSION 变量。

忽略：Ignoring files from a publish

可以通过 .gxignore 文件来指定 gx 要在 publish 中忽略的文件，和 .gitignore 的作用类似，同时 gx 也遵守 .gitignore 约定。

中央库：Repos

gx 可以像 maven 一样来指定中央库，不过因为 ipfs 的网络多是以不稳定的 pc 机组成，所以添加一个 node 作为中央库也未必可靠，除非这个库就是你自己部署的，如果是临时的就不建议添加了。

如果你想在本地开发测试，在服务器上执行编译和运行，那么服务器上也至少要运行一个 ipfs daemon 了，此时你直接把本地 ipfs 连到 服务器上，如 'ipfs swarm connect 服务器ipfsid' ，当然你也可以选择交叉编译，go 提供的交叉编译能力还是很让人满意的。

• 添加一个新的中央库

$ gx repo add myrepo /ipns/QmPupmUqXHBxikXxuptYECKaq8tpGNDSetx1Ed44irmew3

• 列出本地已经添加的中央库

$ gx repo list
myrepo  /ipns/QmPupmUqXHBxikXxuptYECKaq8tpGNDSetx1Ed44irmew3

• 列出指定中央库中包含的库

$ gx repo list myrepo
events QmeJjwRaGJfx7j6LkPLjyPfzcD2UHHkKehDPkmizqSpcHT
smalltree  QmRgTZA6jGi49ipQxorkmC75d3pLe69N6MZBKfQaN6grGY
stump  QmebiJS1saSNEPAfr9AWoExvpfGoEK4QCtdLKCK4z6Qw7U

• 从指定的中央库导入一个库

$ gx repo import events