JitPack使用

Posted 2022-12-13 Red风信子

JitPack

• 一 介绍
• • 1.1 JitPack是干嘛的？
  • 1.2 有何不同？
  • 1.3 使用 JitPack
  • • 1.3.1 配置你的gradle
    • 1.3.2 引用 Snapshots
    • 1.3.3 刷新缓存
    • 1.3.4 引用 Release
    • 1.3.5 发布 JavaDoc
    • 1.3.6 其他特性
    • 1.3.7 自定义域名
    • 1.3.8 支持的代码库网站
    • 1.3.9 角标 Badges
    • 1.3.10 你是库使用者
    • 1.3.11 后记

一 介绍

1.1 JitPack是干嘛的？

JitPack用来管理项目。为了在JitPack上发布您的库，您只需要在Git存储库中使用一个有效的构建文件。

JitPack当前可以构建Gradle，Maven，Sbt和Leiningen项目。让我们知道是否要与其他构建工具一起使用。具体使用可以查看官网。

流程极度简化，只需要输入Github项目地址就可发布项目，大大方便了像我这种懒得配置环境的人。

1.2 有何不同？

那么这和 Maven Central，JCenter 有何不同呢？最大的区别就在于你不必完成 Maven Central 的一系列注册手续，乃至发布一个库之前的登记 Post 和等待管理员批准，也不必在 JCenter 上填写冗长的标签，找图做图做图标写说明，更不必每到发布时做一系列的准备工作，使用专用的工具完成最后一击。你只需要写好你的 GitHub Repo README就行了，其他的事情，JitPack 会全数包办。所以很明显，发布一个公开的第三方库前所未有地简便。

除了支持 GitHub 上的公开 Repository 的自动发布之外，JitPack 也支持 Bucket，GitLab，Gitee 账户中的公开库的发布。

1.3 使用 JitPack

我们没有私服呢，又或者我们的异地伙伴呢，而我们也没有公网上的 Maven 私服呢？又或者，如果我觉得这个代码库具有通用性，我希望让任何感兴趣的人都能够使用它呢？这些情况下，我们只能考虑 Maven Central，JCenter 那样的公共 Maven Repository Servers 了，特别是针对 android 开发的情况，JCenter 是首选的推荐。所以前文我们已经提到过了，当你的技能水平和开发经验推进到一定水平时，你就会面临这样的选择。而且你幸运的是，现在你不必要那么麻烦了，JitPack.io 可以更好地为你的设想进行变现。

当你的开源库变得越来越受欢迎时，你不能使用 JitPack
方式发布它，因为那时候你会发现更多新的需求，你会需要更好地规划版本推进路线图，解决全球各地使用者的依赖、补丁修复等各类型的新问题，也为使用者们释疑和提供可信度，那时候你需要更严谨的登记自己的开源库到
JCenter 并采取更稳定更可信赖的方式来发布代码库。那将会是另一篇文章了。

1.3.1 配置你的gradle

这时候，你的 gradle 脚本中可能是像这样子声明引用的：

allprojects 
    repositories 
        jcenter()
        google()
        maven  url "https://jitpack.io" 
    

dependencies 
    implementation 'com.github.Username:my-library:Tag'

在这里，Username 是你的 GitHub 账户登录名。而 my-library 是你的 Repository 的名字。换句话说，你的库被放在 github.com/Username/my… 处可以被浏览器访问。

1.3.2 引用 Snapshots

在开发过程中，Snapshots 版本是非常有用的。你可以这样指定版本号来引用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'

1.3.3 刷新缓存

注意 Gradle 会缓存SNAPSHOT内容，所以有时候你可能无法获取某个分支上的最新 build。Gradle 自身也提供的方法来控制这一点。你可以在 build.gradle 中要求 Gradle 总是拉取最新的 build 版本：

configurations.all 
    resolutionStrategy.cacheChangingModulesFor 0, 'seconds'

你也可以通过命令行添加 --refresh-dependencies 来要求一次 gradle build 中额外地废除 cache 内容并从远程拉取最新的 build 版本。

使用 Android Studio 时，如果你刷新了 gradle cache，那么你可能也需要在 AS 中通过 File ->
Synchronize 菜单来更新和同步 gradle 各种依赖状态。

1.3.4 引用 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'
   

1.3.5 发布 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

1.3.6 其他特性

1. 支持私有 Repositories。 你只需要提供一个授权给予 jitpack.io
   并微调一下开发机环境就可以了，其他的部分和前文述及的用法没有区别。具体的步骤可以参考：jitpack.io/private。不过，你想要通过
   JitPack 发布私有repo的话，是收费的，按月订阅制。
2. 支持动态版本号。

所以你可以使用 ‘1.+’ 这样的版本号。
3. 可以使用自己的域名作为groupId。

这个需要更高价位的订阅级别。
4. 一般情况下 jitpack
按照构建顺序存储你的若干个库版本，但并不确保这些构建后的版本总是存在。就是说，直到用户向服务器发起了拉取一个库的请求的时候，jitpack按需就地构建请求的版本而不是提前构建好之后等待用户发起请求。这意味着首位用户的首次请求通常是失败的，他需要等待构建完成后再次发布请求时才能完成pom和库包的下载。

通常，一个 jitpack 构建完成的版本至少会维持 7 天不变。

多数时候，我们并不真的介意有时候会拉取失败的问题，尤其是有一次成功后本地.m2也会有一份缓存的情况。你可以登录 JitPack.io
之后在 对应库的构建列表中点击 “Get It” 按钮来明确地发出构建请求而不是由使用者发起。

1.3.7 自定义域名

1. 默认时，你的库的 groupId 为 com.github.USER 或者
   com.github.yourORGANIZATION。但你也可以使用自己的域名前缀，例如 com.hedzr 或者
   com.hedzr.lib。为了使用自己的域名前缀作为 groupId，应该遵循以下的步骤： 添加一条 DNS TXT 记录，以完成从
   git.yourcompany.com 到 github.com/yourcomany。另外一种情形是：从
   lib.yourdomain.com 映射到
   github.com/USER。你需要在自己的域名托管商提供的DNS记录修改工具中完成这样的操作，可以参考 How to add a TXT record。
2. 然后请前往 jitpack.io/#com.yourco… 并点击 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"

1.3.8 支持的代码库网站

GitHub

GitLab

BitBucket

Gitee

1.3.9 角标 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)

1.3.10 你是库使用者

你需要的引用方式是在 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" 
    

1.3.11 后记

关于 JitPack 的 API:
这给予我们 ChatOps 回调能力或者 CI 控制能力，或者其他——取决于你的想象力。
由于 API 设计的非常简单，因此不必另文专述。有需要者不妨直达：
jitpack.io/docs/API/