Today I want to share, how to release an open source library to JCenter step by step
There are already many blogs on the Internet in this regard, so this article does not intend to just record the process steps, but to make it as clear as possible, why this step is necessary, so that everyone knows the reason and the reason, then master It will be a little deeper, so this article will be very long. In addition, this article refers to, cites, and draws from the following articles:
How to distribute your own Android library through jCenter and Maven Central from Android Studio
Although it is in English, you can basically understand it if you have the four-level foundation. The article is very comprehensive and detailed.
I really don't want to read the English version, there is a Chinese translation in China, and there is a full Chinese translation in Chapter 9 of ***"Android Advanced Advanced"***
foreword
First of all, you have to think about one thing: Is it only open source libraries that are well written, or only good people and great gods can publish open source libraries to JCenter?
Some people may feel that they are not great gods, and they can't write any awesome open source libraries, so they don't need to publish them on JCenter for others to use. So, you have to think clearly first, why do you want to publish an open source library to JCenter?
It’s okay to learn; it’s okay to share; it’s okay to use it yourself; in short, there is no rule that only the great gods can publish;
In fact, the reason why it is called an open source library is that everyone can use it after it is published on JCenter. I prefer the statement in "Android Advanced Advanced": function library
I have this idea:
As a lazy person, I really don't want to manually copy and paste some common basic modules that can be used in multiple projects, or manually import Modules every time I create a new project, so I want to package and publish these common basic modules to JCenter. When you create a new project in the future, you only need to configure build.gradle.
Q: You ask me why I don't upload it to the private server?
A: No money
Q: You ask me that I am not afraid of the code being stolen?
A: It's not some awesome open source library, it's just some basic public modules such as tools, network layer encapsulation, etc. If others want to use it, I'm too happy to be too late, what are you afraid of?
Q: You ask me why these basic modules are not open sourced by others, and they have to build their own wheels?
A: My own use is easy, and I can change my own how I want.
Q: You ask me if I am not afraid that the open source library code released is too bad and will be scolded by others?
A: Brother, I'm not a god. If I don't write this blog, no one will know that I have released an open source library. Anyway, I use it myself.
Q: You ask me...
A: Brother, don't ask, go and post one and try it out, in case you will become a god in the future, you can save time and learn again
Ok, let's start talking about the steps of publishing.
step
First steal a picture from the link shared at the beginning
The whole process is actually as described in the above figure. First, it is packaged into a jar or aar file locally, then uploaded to bintray's own warehouse, and finally published to jcenter.
Except for the first step, which is to do it locally, the rest of the operations are done by moving the mouse on the web page and clicking a little bit.
Step 0: JCenter URL
Why are there two? That's because the first one is a website that provides us with ui interactive operations. Operations such as registering an account, configuring warehouses, publishing, etc. are all performed on the first URL. We only need to remember the first website.
The second is the URL where these open source libraries are stored. If you want to manually download the jar of an open source library, you can directly add the path to the open source library after the second URL.
For example, I wrote an article on how to use Android Studio to view the source code of build.gradle. In some cases, Android Studio did not successfully download the source code of the Android Gradle plugin. When we want to view the source code, we can only download it ourselves. . When I wrote that blog, Android Studio still used the default configuration of mavenCentral as the source of the open source library.
But now the new version of Android Studio has been changed to the default configuration of JCenter as the source of open source libraries, for example:
compile 'com.squareup.okhttp:okhttp:2.4.0'
If you want to download the jar package of okhttp manually, then visit: https://jcenter.bintray.com/com/squareup/okhttp/okhttp/2.4.0/
and so on
Step 1: Register an Account & Create a Repository
1.1 Register an account
Open the bintray.com/ website, register an account, or you can choose to log in directly with your Github account. It's very simple, no pictures.
1.2 Create a warehouse
After logging in to your account, similar to Github, bintray allows you to create your own repository on the website, which can be public or private.
The operation of creating a repository is similar to Github, so I won't demonstrate it. I created an empty repository called base-module here.
Next, it is a bit different from the concept of Github. On Github, one of our warehouses usually corresponds to a specific project. What the local project looks like, the warehouse on Github basically looks like.
In bintray, I prefer to understand a warehouse as a warehouse, that is, as a container. After creating an empty warehouse, there will be an Add New Package button in the lower right corner of the page, that is, there is a concept of a package under the warehouse.
A package is an open source package that can be published to JCenter, and the content published to JCenter is some pom, aar, jar and other files, not the entire project. So we need to create a package first to prepare the storage place for generating pom, aar and other files for the module that needs to be packaged and released locally.
Step 2: Configure the local gradle script plugin
The source code of the entire project is uploaded to Github, and the files such as pom, jar, and arr are uploaded to bintray.
Therefore, before publishing the open source library to JCenter, we need to package the Module to be published locally into jar, aar. So, how to do it locally? Just as Google provides the Android Gradle plugin to facilitate developers to compile the project directly, bintray also provides the corresponding gradle plugin to facilitate us to directly package it into a jar locally.
Similarly, Github supports uploading local projects to Github through Git, and bintray also provides corresponding gradle scripts to allow developers to upload locally packaged jars to the warehouse on the bintray website.
This is why we need to configure some gradle plugins locally. One is to facilitate developers to compile and package the project into the required files; the other is to upload to the warehouse on the bintray website through the bridge it provides.
2.1 Configure the gradle plugin address
To use the Android Gradle plugin, you need to configure it in the root project's build.gradle file:
dependencies {
classpath 'com.android.tools.build:gradle:2.3.3'
}
For the same reason, to use the bintray gradle plugin, it must also be configured in the build.gradle file of the root project :
dependencies {
//Android Gradle 插件
classpath 'com.android.tools.build:gradle:2.3.3'
//bintray 插件
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.4'
classpath 'com.github.dcendents:android-maven-gradle-plugin:1.4.1'
//android-maven-gradle-plugin:1.3版本有bug，网上很多例子用的这个版本，编译的时候可能会出错，改一下版本就好了
}
Above, only the path of the plugin is configured, so the place to use the plugin must be in the build.gradle file under the corresponding module
2.2 Using the gradle plugin
The places where the gradle plugin is used are in the build.gradle file under each specific module :
apply plugin: 'com.android.library'
android {
...
}
The above is a common build.gradle file, which means that the gradle plugin whose id is com.android.library in the Android gradle plugin will be used to build the Module into a library, and other configuration items in build.gradle such as android Etc. means some configuration required to build the project, which is my understanding of gradle (not sure if it's right).
Similarly, because some pom and jar files are uploaded to bintray, we also need to use the plugin provided by bintray in this build.gradle to compile and package the project:
//切记：以下代码必须放在 build.gradle 文件末尾
apply from: 'https://raw.githubusercontent.com/nuuneoi/JCenter/master/installv1.gradle'
apply from: 'https://raw.githubusercontent.com/nuuneoi/JCenter/master/bintrayv1.gradle'
The above apply from means that the module needs to use a gradle script file stored on the Internet to compile and package the project according to various configuration items.
The reason why this gradle script file is stored on the network is purely because bintray is worried that we don't know how to use the gradle plugin it provides to generate pom, jar and other files, so even the template script is provided to us (this is my understanding) .
So, you can enter the link after apply from on the web page and you will see the following script:
//以下代码大概瞄一眼即可，不用细看
apply plugin: 'com.github.dcendents.android-maven'
group = publishedGroupId //开源库的 groupId
install {
repositories.mavenInstaller {
// This generates POM.xml with proper parameters
pom {
project {
packaging 'aar'//将项目打包成 aar
groupId publishedGroupId
artifactId artifact
// Add your description here
name libraryName
description libraryDescription
url siteUrl
// Set your license
licenses {
license {
name licenseName
url licenseUrl
}
}
developers {
developer {
id developerId
name developerName
email developerEmail
}
}
scm {
connection gitUrl
developerConnection gitUrl
url siteUrl
}
}
}
}
}
This is a script that packs the project into arr and generates the project's pom.xml file, which is to be uploaded to your repository on the bintray website.
So, if you know what configuration is required to use the bintray gradle plugin, you can directly write the configuration required in the above script in build.gradle without using apply from; The link to copy-paste the script code into the build.grale file also works.
For the same reason, I will not take a screenshot of the gradle script provided by another apply from. The function of that script is to upload the generated pom, aar and other files to the warehouse of your bintray website.
That is to say, bintray provides two gradle plugins, one is used to compile the local project, package it into aar, and generate the required pom.xml and other files; the other is used to upload the generated files to your bintray to the warehouse. At the same time, bintray also provides two script configuration templates. If you don't know how to use them, just refer to these two templates .
2.3 Modify the configuration items in the gradle script template file
Since only template files are provided, the specific configuration items must be configured according to our actual project. There are two ways:
- Without using apply from, directly copy the code in the script template file to build.gradle, and then manually modify each configuration item according to the specific project (slightly troublesome, not recommended)
- In the script template file, each configuration item is configured with corresponding variables, then we only need to declare these variables in build.gradle and assign values to the variables.
The usage of Android Gradle to compile the project is actually the first one, but since we are quite familiar with the items to be configured for android project compilation, and Android Studio will automatically generate some necessary configuration items, so it is not troublesome. However, due to the unfamiliarity with the configuration items of the bintray gradle plugin, I personally do not recommend using this method here.
In the second way, if you are interested in searching the Internet for other articles of this kind of tutorial, you may find that many articles will let you write such a piece of code in the build.gradle file:
//下一步会具体来看每个配置项含义
ext {
bintrayRepo = 'maven'
bintrayName = 'fb-like'
publishedGroupId = 'com.inthecheesefactory.thecheeselibrary'
libraryName = 'FBLike'
artifact = 'fb-like'
...
}
Now it's understandable why they want you to write this code. Because in the script template file provided by bintray, the corresponding variables are used for the configuration items it needs, so if we use the script template file directly, we need to declare and assign these variables, that is to say, declare in ext The variables such as bintrayRepo, libraryName, etc. are actually because they are used in the script template files provided by bintray.
In addition, since the gradle script executes the code in sequence, the code that declares these variables must be before the apply from code, otherwise, if the apply from is executed first, an error will be reported that the corresponding variable cannot be found.
Another point, I didn't look into the source code of the bintray gradle plugin, but I want the project to generate the corresponding pom project description file and package it into aar, so I guess, this shows that the bintray gradle plugin is in addition to the various listed on the script template. In addition to the configuration items, some configuration items of the Android Gradle plugin are also required, such as the android block configuration items in build.gradle.
This is why other articles mentioned that the lines of apply from should be placed at the end of build.gradle. Because the gradle script executes the code in sequence, and the operation of the bintray gradle plugin depends on some android configuration items, if you put apply from at the beginning, it will report that some variables cannot be found.
2.3.2 Write the variable declaration and assignment code in a separate script file (optional)
If you don't want to have too much code in the build.gradle file that is not related to compiling the project itself, you can write all the code related to the bintray gradle plugin in another gradle file, and then pass apply from at the beginning of the build.gradle. The gradle file can be applied, which is somewhat similar to the concept of import.
//build.gradle 文末
//bintray-config.gradle 就是跟 build.gradle 同层目录下的一个 gradle 文件，里面就是单纯将 exe {} 这块代码里的变量声明和赋值拷贝至 bintray-config.gradle 文件里
apply from: 'bintray-config.gradle'
apply from: 'https://raw.githubusercontent.com/nuuneoi/JCenter/master/bintrayv1.gradle'
apply from: 'https://raw.githubusercontent.com/nuuneoi/JCenter/master/installv1.gradle'
Step 3: Set various configuration items in the gradle plugin
The second step is to configure the various required gradle plugins and how to use them. As for each line of code in the script template, those who are interested can go to the bottom of it, but don’t worry about it. Anyway, you probably know what the two scripts are doing. It's alright, you don't have to worry about it.
Then you need to know what properties you need to configure for the project, so that these plugins can run normally, and you can upload the open source library to the warehouse on bintray normally:
3.1 Various basic configuration items
ext {
//bintray 网站上你创建的仓库的名字（必配项）
bintrayRepo = 'base-module'
//在这个仓库下的 package name（必配项）
bintrayName = 'tv'
//以上两项均只是指向 bintray 网站上你的仓库和仓库下的package
//publishedGroupId:artifact:libraryVersion 构成你开源库的唯一路径
//例如：com.dasu.tv:tv:0.0.1，在build.gradle里就可以根据这个路径来compile依赖库了
//以下三项均是必配项
publishedGroupId = 'com.dasu.tv'
artifact = 'tv'
libraryVersion = '0.0.1'
//以下三项只是对开源库的描述（应该不是必配项吧，没尝试过）
libraryName = 'tv'
libraryDescription = 'dasu 封装的常用，可公用的 tvui 库'
siteUrl = 'https://github.com/woshidasusu/base-module/tree/master/tv'
//开源库对应的 github 地址，不知道可不可以不配，应该也是必配
gitUrl = 'https://github.com/woshidasusu/base-module.git'
//开发者信息，也是必配的吧
developerId = 'dasu'
developerName = 'dasu'
developerEmail = '[email protected]'
//这部分可以不用改，我也不大懂这些开源协议，但应该都一样
licenseName = 'The Apache Software License, Version 2.0'
licenseUrl = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
allLicenses = ["Apache-2.0"]
}
Just like the build.gradle file, some properties must be configured before the project can compile and run normally. To use the bintray gradle plugin to generate the corresponding pom, aar files, upload to the bintray warehouse and other functions, you must also configure some properties.
In short, the information corresponding to the bintray warehouse must be configured, the only path after publishing to JCenter also needs to be configured, and the developer information is also required. Others also need some open source library description information and open source protocol information.
3.2 Configuring Authentication Information (Sensitive Information)
If you use Github often, you must also feel that you need key user and key information, otherwise you will not be able to authenticate when uploading projects to Github using Git.
In the same way, to upload the pom, aar, etc. generated by the bintray gradle plugin to the bintray warehouse, authentication is also required, then some key information of the user name and key should be configured, but these information are extremely sensitive and private, so only The configuration is in a local file.
If you do not modify the two script template files, then this information needs to be configured in the local.properties file under the root directory of the project:
//根目录下的local.properties文件
bintray.user= woshidasusu
bintray.apikey= XXXXXXX
bintray.user is the login account of your bintray website. If you log in with Github authorization, it is your Github account.
bindtray.apikey needs to go to your settings on the bintray website to check:
Maybe when you read the tutorial articles written by others, you will find that they also configure a
bintray.gpg.password=YOUR_GPG_PASSWORD
This should be the verification information used to publish the open source library on bintray to the mavenCentral repository synchronously. Anyway, I tested it, and I didn't configure this. I can still upload the local open source library to bintray and publish it to JCenter.
Step 4: Execute the gradle script
Well, we have configured the bintray gradle plugin, and we have also configured the various properties required for its operation, so the next step is to just execute it.
If the gradle environment is configured locally, the script can be executed directly in the form of command line in cmd.
If the gradle environment is not configured, there is a gradle folder in the root directory of each project, which contains the files required for the execution of the gradle naming line, so you can directly execute the corresponding script in the form of the command line in the Terminal of Android Studio. You can, as follows:
So how to run the script of the bintray gradle plugin? Just record two commands:
- gradlew install
- gradlew bintrayUpload
gradlew installUsed to compile and package the project to generate pom, aar and other files;
gradlew bintrayUploadUsed to upload the generated pom, aar and other files to the bintray repository;
Just like compiling and running the project, when the above two scripts are named in sequence, if the operation is successful, you can see the BUILD SUCCESSFULinformation . Similarly, if the script runs incorrectly, then you need to check the log to see where the problem is. , usually there are some problems with steps 2 and 3.
In addition, you can also judge whether the gradlew installscript . Then directly check whether the file is uploaded in your repository on the bintray website to determine whether the gradlew bintrayUploadscript has been successfully executed.
Step 5: Publish the package to JCenter on the bintray website
The next step is the last step, log in to your bintray account, enter your repository, find the uploaded open source library, then find the Add to JCenter button in the lower right corner of the page, click on it, fill in the open source library description as required, and then just sit still Wait for a few hours and wait for the approval email sent to you by JCenter, then you are successful.
Then at this time, you can happily rely on your open source library into your project through compile directly in the build.gradle file of your new project.
summary
The above is how to package and publish your own open source library to JCenter step by step. To summarize, it is nothing more than the following points:
- Register a bintray account (you can log in with Github authorization)
- Create a warehouse on bintray and create a package under the warehouse
- Prepare the project that needs to be packaged and released locally
- Configure the bintray gradle plugin in the project, there are two, one is used to generate aar, pom and other files; the other is used to upload these files to the bintray repository; both plugins are in the build.gradle configuration plugin's classPath in the project root directory path
- Configure the use of the two plugins in the build.grale file under the Module to be packaged and released. You can directly use apply from to configure the script file stored on the Internet, or you can download the script template file to use locally.
- apply from must be at the end of the build.gradle file, and the exe code block needs to be in front of apply from, because various variables used by the script template file need to be declared in the exe block first, and assigned
- Understand the meaning of various configuration items in the exe block
- Execute the gradlew install, gradlew bintrayUpload command directly in the Terminal panel of Android Studio to execute the script
- After the script is successfully executed, you can find the Add to JCenter button on the bintray website and publish it to JCenter, and then wait for the email message.
Finally, there is also an article dedicated to recording some of the problems and solutions I encountered during the whole process: some problem records for
publishing open source libraries to JCenter