Skip to main content

Java/Android 发布 library 包含源码和文档

使用优秀的开源库的时候，我们在 IDE 中往往能够看到注释良好的源码，并且能够断点调试，十分方便。这是如何做到的呢？其实很简单，打开下载到的库，我们就可以看到需要上传的文件。

必需文件​

在发布 library 到 Maven 仓库时，通常情况下我们上传的文件包含：

  • 描述文件 POM: artifactId-version.pom
  • aar/jar: artifactId-version.aar/jar

示例如下：

perfmonitor-0.1.1-20200114.075334-4.aar           14-Jan-2020 15:53  48.27 KB
perfmonitor-0.1.1-20200114.075334-4.pom           14-Jan-2020 15:53  463 bytes

有了这两者，其他人就可以通过 GAV(Group, Artifact, Version) 来定位并下载到我们发布的 library。

可选文件​

除了上述的必需文件，我们还可以上传两个可选文件：

  • javadoc jar 包: artifactId-version-javadoc.jar，

    打包了 library的 Javadoc。 只要按照规范命名，你发布到 Maven Central 或 Bintray (JCenter) 的 library 的 Javadoc 就可以自动部署到比如javadoc.io这样的服务上。

  • sources jar 包: artifactId-version-sources.jar

    打包了 library 的源码。 只要按照规范命名，智能的 IDE（比如 IDEA/Android Studio）会自动帮我们下载并将.java文件与相应的.class文件关联。 此时当我们在这些 IDE 中查看某个我们发布的 library 的类代码时，看到的就是.java文件而不再是.class文件，这样不仅方便阅读理解代码逻辑，而且可以直接进行断点调试。 几乎所有开源项目的发布都会包含 sources，比如 Android 本身。

示例如下：

perfmonitor-0.1.1-20200114.075334-4-javadoc.jar   14-Jan-2020 15:53  94.29 KB
perfmonitor-0.1.1-20200114.075334-4-sources.jar   14-Jan-2020 15:53  23.93 KB
info

如果你的 library 要发布到 Maven Central，那么这两个文件就是必需的。

如何配置打包这两个文件​

Android Gradle plugin与Java plugin有不同，使用了 Kotlin 后也会不同，这里只列出不使用 Kotlin 的 Android 的核心配置方法。

创建 tasks​

// sources
tasks.register('sourcesJar', Jar) {
    archiveClassifier.set('sources')
    from android.sourceSets.main.java.sourceFiles
}

// javadoc
tasks.register('androidJavadoc', Javadoc) {
    source = android.sourceSets.main.java.srcDirs
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
}
tasks.register('javadocJar', Jar) {
    dependsOn androidJavadoc
    archiveClassifier.set('javadoc')
    from androidJavadoc.destinationDir
}

在需要发布的 artifacts 中添加之前创建的 tasks​

publishing {
    publications {
        releaseAar(MavenPublication) {
            // ... 原有artifact
            artifact sourcesJar
            artifact javadocJar
        }
    }
}
tip

兼容 Java/Android 各种情况的配置请移步这里