JitPack.io 是一个 GitHub 开源代码库的便捷发布渠道。它可以让你的 Android/Java 代码库自动完成发布,从而令使用者能够最便利地享受到你的代码库。
本质上说,一切能够通过 Maven Repository 发布的代码库,你都可以借助 JitPack 的自动打包和发布功能,从 GitHub 上发布给大众使用。例如你的 Kotlin/Java 代码库,SpringBoot 工具库,Android 三方库,等等,一旦你发布了源代码到 GitHub,并完成了提交、Release标签动作,那么 JitPack 上将会自动生成一个相应的符合 Maven 包引用规则的 ID:com.github.your-github-username:your-github-reponame:release-tag
。在这里,Maven Group Name 即 com.github.your-github-username
,Maven Artifact Name 即 your-github-repo-name
。这样的 Maven ID,三方库使用者能够通过 POM 或 gradle 引用到它。
那么这和 Maven Central,JCenter 有何不同呢?最大的区别就在于你不必完成 Maven Central 的一系列注册手续,乃至发布一个库之前的登记 Post 和等待管理员批准,也不必在 JCenter 上填写冗长的标签,找图做图做图标写说明,更不必每到发布时做一系列的准备工作,使用专用的工具完成最后一击。你只需要写好你的 GitHub Repo README就行了,其他的事情,JitPack 会全数包办。
所以很明显,发布一个公开的第三方库前所未有地简便。
当然,这一切大体上限定在 Java 及其衍生领域,例如 Android。而诸如 Python,Nodes 等就没法
除了支持 GitHub 上的公开 Repository 的自动发布之外,JitPack 也支持 Bucket,GitLab,Gitee 账户中的公开库的发布。
JitPack is a novel package repository for JVM and Android projects. It builds Git projects on demand and provides you with ready-to-use artifacts (jar, aar).
那么,这里会讲讲利用 JitPack.io 的方法。为了讲述方便,下面会主要使用 Android Library 作为讲解的例子。
你是库开发者
假定你是一个Android开发者,手头有一堆代码行之有效,而且厌倦了每次在各个 Projects 之间拷贝来拷贝去,那么你就建立了一个独立的 Android Library 项目,将这些代码打包在一起。这时,问题来了,别的工程怎么引用这个库呢?
Android使用一个库,有很多种方法。
没有 JitPack
你可以将 Library Module 嵌入到目标项目中,然后通过
dependencies {
implements ':my-library'
}
来引用它。
这很蠢,但最简单。所以我们会将库独立建立一个工程 my-library
,然后通过 gradle 命令构建它,从而得到一个 .aar 文件,然后我们可以复制这个 .aar 文件到目标项目中的 app/libs/
之中,利用:
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}
来引用它。
这就方便多了,不过如果修订了 my-library
的话,我们需要复制那个 .aar 到每个引用它的目标项目中,如果我们引用了5次,甚至我的团队伙伴们引用了它时,那么灾难还是会发生。
所以我们可以用过 gradle deploy
指令将 .aar 发布到 $HOME/.m2/repositories/
之中,然后通过 Maven Artifact ID方式引用它。如果我的团队伙伴们也需要引用它,那么我发布到 Maven 私服上,就解决问题了。这时候通常是这样的:
allprojects {
repositories {
jcenter()
google()
mavenCentral()
mavenLocal()
maven { url "https://maven.our-nexus.com" }
}
}
dependencies {
implementation 'com.example.android:my-library:1.0.1'
}
使用 JitPack
那么新问题还是不可避免地来了,我们没有私服呢,又或者我们的异地伙伴呢,而我们也没有公网上的 Maven 私服呢?又或者,如果我觉得这个代码库具有通用性,我希望让任何感兴趣的人都能够使用它呢?这些情况下,我们只能考虑 Maven Central,JCenter 那样的公共 Maven Repository Servers 了,特别是针对 Android 开发的情况,JCenter 是首选的推荐。所以前文我们已经提到过了,当你的技能水平和开发经验推进到一定水平时,你就会面临这样的选择。而且你幸运的是,现在你不必要那么麻烦了,JitPack.io 可以更好地为你的设想进行变现。
这时候,你的 gradle 脚本中可能是像这样子声明引用的:
allprojects {
repositories {
jcenter()
google()
maven { url "https://jitpack.io" }
}
}
dependencies {
implementation 'com.github.Username:my-library:Tag'
}
在这里,Username
是你的 GitHub 账户登录名。而 my-library
是你的 Repository 的名字。换句话说,你的库被放在 https://github.com/Username/m... 处可以被浏览器访问。
当你的开源库变得越来越受欢迎时,你不能使用 JitPack 方式发布它,因为那时候你会发现更多新的需求,你会需要更好地规划版本推进路线图,解决全球各地使用者的依赖、补丁修复等各类型的新问题,也为使用者们释疑和提供可信度,那时候你需要更严谨的登记自己的开源库到 JCenter 并采取更稳定更可信赖的方式来发布代码库。那将会是另一篇文章了。
按照 JitPack 的官方说明,Tag
是这样的:Tag
可以是 Release 标签,commit hash,分支名加上 -SNAPSHOT
后缀等等。
引用 Snapshots
在开发过程中,Snapshots 版本是非常有用的。你可以这样指定版本号来引用 repo 的 snapshots:
- commit hash
-
branch-SNAPSHOT
(替换branch
为你的分支名)
例如:
// dependency on the latest commit in the master branch
implementation 'com.github.jitpack:gradle-simple:master-SNAPSHOT'
// dependency on the latest commit in the devel branch
implementation 'com.github.jitpack:gradle-simple:devel-SNAPSHOT'
// dependency on the certain a commit 33e0c37ee8
implementation 'com.github.jitpack:gradle-simple:33e0c37ee8'
刷新缓存
注意 Gradle 会缓存SNAPSHOT内容,所以有时候你可能无法获取某个分支上的最新 build。Gradle 自身也提供的方法来控制这一点。你可以在 build.gradle 中要求 Gradle 总是拉取最新的 build 版本:
configurations.all {
resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
}
你也可以通过命令行添加 --refresh-dependencies
来要求一次 gradle build 中额外地废除 cache 内容并从远程拉取最新的 build 版本。Gradle documentation 提供了更多的关于控制缓存的相关信息。
使用 Android Studio 时,如果你刷新了 gradle cache,那么你可能也需要在 AS 中通过 File -> Synchronize 菜单来更新和同步 gradle 各种依赖状态。
对于在你的开源库中提供多个 Modules 的情况,JitPack 也提供了相应的支持:https://jitpack.io/docs/BUILD...。不过我们并不建议你这么去做。
引用 Release
通过 JitPack 来发布开源库,而不是使用你的库的 Snapshots 版本,也是超级容易的。当然,你需要具备 GitHub Release 的相关知识。
本质上说,GitHub 的 Release 和 git 的 tag 没有什么不同,只是在 tag 名称上略有要求。你可以在GitHub 上通过 Web 界面建立 pre-release 和 release,但你也可以直接通过本机的命令行或者 IDE 或者 Git Client 来建立 release 标签。无论如何,对于这些标签的命名的这些要求,通常也符合软件团队的发布策略:
git tag 0.17.2
git tag v0.17.3
git tag release-0.1.1
git tag release/v0.13.3
不同的团队可能采取不同的 CI 策略以及 Release 命名策略。
- 较为简明的方式是
0.17.2
,它便于手工管理且视觉上明确无歧义。 - 采用自动化 CI 的团队可能会使用
v0.17.3
和release/v0.13.3
,前者利用前缀触发 CI builder Rules,而后者则在兼顾触发规则的同时,提供一个可视化层面的更好的组织形式:当你通过多数 Git 客户端审查代码时,所有的 releases tags 会被组织为release/
之下的一组节点——类似地,往往同时也会使用诸如hotfix/v0.13.3-h101
,rc/v2
,beta/1
等 tags 来组织和管理其他情形的版本。
当然,tag 的命名是全自由度的。你可以在无论是 git,git client,github,jitpack 等各种不同场合使用像 temporary-rel-1
或者 fxx-123-kk
这样的 tag 名称,毫无障碍地。
可以通过 Gradle 插件来帮助你管理你的 Git/GitHub 版本号:Gradle release & version management plugin
如果你尚未有任何关于如何进行 Git Tag 命名的概念的话。
一旦通过 git 命令或者任何方式建立了一个 git tag,那就代表着你建立了一个 Release,无论其名称多么狗屎都可以。那么一旦你推送这个 tag 到 GitHub 之后,例如 fxx-123-kk
,任何人就可以在项目中这样引用它:
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
dependencies {
implementation 'com.github.yourname:your-repo:fxx-123-kk'
}
这就是全部了。
发布 JavaDoc
如果你的库的构建脚本能够产出 javadoc jar 包,那么 JitPack 将会自动处理 javadoc 的生成以及发布。你可以直接在这里浏览:
-
https://jitpack.io/com/github/USER/REPO/VERSION/javadoc/
or -
https://jitpack.io/com/github/USER/REPO/latest/javadoc/
(latest release tag)
对于一个多 Module 的项目来说,它的 Maven 发布点使用 com.github.USER.REPO:MODULE:VERSION
这样的 Artifact。因此,相应的 JavaDoc 位置在:
https://jitpack.io/com/github/USER/REPO/MODULE/VERSION/javadoc/
Source codes jar 包会被 JitPack 自动处理,你无需额外提供处理依据或编排。
一个简短的 Module-level build.gradle 样本如下:
apply plugin: 'com.android.library'
apply plugin: 'kotlin-android'
apply plugin: 'com.github.dcendents.android-maven'
repositories {
mavenCentral()
google()
jcenter()
maven { url "https://jitpack.io" }
}
group = 'com.github.jitpack'
version = '1.0'
android {
compileSdkVersion 28
buildToolsVersion "28.0.2"
defaultConfig {
minSdkVersion 16
targetSdkVersion 28
versionCode 1
versionName version
testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
lintOptions {
abortOnError false
}
sourceSets {
main.java.srcDirs += 'src/main/kotlin'
androidTest.java.srcDirs += 'src/androidTest/kotlin'
androidTest.resources.srcDirs += 'src/androidTest/res'
}
}
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
testImplementation 'junit:junit:4.12'
androidTestImplementation 'com.android.support.test:runner:1.0.2'
androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
implementation 'com.android.support:appcompat-v7:28.0.0-rc01'
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}
task sourcesJar(type: Jar) {
classifier = 'sources'
from android.sourceSets.main.java.sourceFiles
}
task javadoc(type: Javadoc) {
source = android.sourceSets.main.java.sourceFiles
classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
}
task javadocJar(type: Jar, dependsOn: javadoc) {
classifier = 'javadoc'
from javadoc.destinationDir
}
task classesJar(type: Jar) {
from "$buildDir/intermediates/classes/release"
}
artifacts {
archives classesJar
archives javadocJar
archives sourcesJar
}
其他特性
- 支持私有 Repositories。
你只需要提供一个授权给予 jitpack.io 并微调一下开发机环境就可以了,其他的部分和前文述及的用法没有区别。具体的步骤可以参考:https://jitpack.io/private。不过,你想要通过 JitPack 发布私有repo的话,是收费的,按月订阅制。
- 支持动态版本号。
所以你可以使用 '1.+' 这样的版本号。
- 可以使用自己的域名作为groupId。
这个需要更高价位的订阅级别。
不过对于 free 的 GitHub repo 来说,你也可以免费获得这个特性。稍后章节我们会提到这一点。
- 一般情况下 jitpack 按照构建顺序存储你的若干个库版本,但并不确保这些构建后的版本总是存在。就是说,直到用户向服务器发起了拉取一个库的请求的时候,jitpack按需就地构建请求的版本而不是提前构建好之后等待用户发起请求。这意味着首位用户的首次请求通常是失败的,他需要等待构建完成后再次发布请求时才能完成pom和库包的下载。
通常,一个 jitpack 构建完成的版本至少会维持 7 天不变。
多数时候,我们并不真的介意有时候会拉取失败的问题,尤其是有一次成功后本地.m2也会有一份缓存的情况。你可以登录 JitPack.io 之后在 对应库的构建列表中点击 “Get It” 按钮来明确地发出构建请求而不是由使用者发起。
自定义域名
默认时,你的库的 groupId 为 com.github.USER
或者 com.github.yourORGANIZATION
。但你也可以使用自己的域名前缀,例如 com.hedzr
或者 com.hedzr.lib
。为了使用自己的域名前缀作为 groupId,应该遵循以下的步骤:
- 添加一条 DNS TXT 记录,以完成从 git.yourcompany.com 到 https://github.com/yourcomany。另外一种情形是:从
lib.yourdomain.com
映射到 https://github.com/USER。你需要在自己的域名托管商提供的DNS记录修改工具中完成这样的操作,可以参考 How to add a TXT record。 - 然后请前往 https://jitpack.io/#com.yourc... 并点击
Look up
按钮,确定映射已经生效。
为了检测TXT记录已经生效,可以执行命令行:
dig TXT git.yourcompany.com
例如:
~$ dig txt git.jitpack.io
...
;; ANSWER SECTION:
git.jitpack.io. 600 IN TXT "https://github.com/jitpack"
支持的代码库网站
GitHub
GitLab
BitBucket
Gitee
角标 Badges
在你的项目的 README.md 中添加相应的角标的方法是:
[![Release](https://jitpack.io/v/User/Repo.svg)](https://jitpack.io/#User/Repo)
也可以使用非圆角的样式:
[![Release](https://jitpack.io/v/jitpack/maven-simple.svg?style=flat-square)](https://jitpack.io/#jitpack/maven-simple)
当你使用自定义域名或者 BitBucket 时,可以这样:
[![Release](https://jitpack.io/v/com.example/Repo.svg)](https://jitpack.io/#com.example/Repo)
[![Release](https://jitpack.io/v/org.bitbucket.User/Repo.svg)](https://jitpack.io/#org.bitbucket.User/Repo)
你是库使用者
你需要的引用方式是在 Module-level build.gradle 中添加:
dependencies {
implementation 'com.github.Username:my-library:Tag'
}
你应该在 Top-level build.gradle 中添加 jitopack 的 Maven 仓库:
allprojects {
repositories {
jcenter()
google()
maven { url "https://jitpack.io" }
}
}
详细的解释,请阅读库开发者
相关章节内容。
后记
关于 JitPack 的 API
这给予我们 ChatOps 回调能力或者 CI 控制能力,或者其他——取决于你的想象力。
由于 API 设计的非常简单,因此不必另文专述。有需要者不妨直达:
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。