JitPack.io 基本使用法

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 的名字。換句話說，你的庫被放在 github.com/Username/my… 處能夠被瀏覽器訪問。

當你的開源庫變得愈來愈受歡迎時，你不能使用 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 也提供了相應的支持：jitpack.io/docs/BUILDI…。不過咱們並不建議你這麼去作。

引用 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 並微調一下開發機環境就能夠了，其餘的部分和前文述及的用法沒有區別。具體的步驟能夠參考：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，應該遵循如下的步驟：

1. 添加一條 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"
複製代碼

支持的代碼庫網站

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 設計的很是簡單，所以沒必要另文專述。有須要者不妨直達：

jitpack.io/docs/API/