JitPack.io 基本使用法

时间  2019-12-12
标签 jitpack.io jitpack 基本 使用 繁體版
原文   原文链接

JitPack.io 是一个 GitHub 开源代码库的便捷发布渠道。它可让你的 Android/Java 代码库自动完成发布，从而令使用者可以最便利地享受到你的代码库。html

本质上说，一切可以经过 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 引用到它。java

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

因此很明显，发布一个公开的第三方库史无前例地简便。git

固然，这一切大致上限定在 Java 及其衍生领域，例如 Android。而诸如 Python，Nodes 等就无法github

除了支持 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 项目，将这些代码打包在一块儿。这时，问题来了，别的工程怎么引用这个库呢？bash

Android使用一个库，有不少种方法。服务器

没有 JitPack

你能够将 Library Module 嵌入到目标项目中，而后经过markdown

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，应该遵循如下的步骤：

  1. 添加一条 DNS TXT 记录，以完成从 git.yourcompany.com 到 https://github.com/yourcomany。另一种情形是：从 lib.yourdomain.com 映射到 https://github.com/USER。你须要在本身的域名托管商提供的DNS记录修改工具中完成这样的操做，能够参考 How to add a TXT record。
  2. 而后请前往 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

也可使用非圆角的样式：

[![Release](https://jitpack.io/v/jitpack/maven-simple.svg?style=flat-square)](https://jitpack.io/#jitpack/maven-simple)

Release

当你使用自定义域名或者 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 设计的很是简单，所以没必要另文专述。有须要者不妨直达：

https://jitpack.io/docs/API/

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程