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 CentralBintray (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 pluginJava 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 各种情况的配置请移步这里