We’ve been trying to do three things for a long time: practice guides, reduce template code, and simplify the task flow. We want to help developers focus on the logic that they really need to think about. Jetpack was born for this purpose, and it contains libraries, tools, and guidance to make it easier to write high-quality applications.
What does Jetpack have to do with AndroidX? All of the libraries in Jetpack use AndroidX as the package name, and we see AndroidX as an open source project to develop, test, and release the Jetpack libraries.
At I/O 2018 we announced plans to refactor the Support Library into the AndroidX namespace. At Support Library 28, we finished refactoring and released AndroidX 1.0. To take advantage of Jetpack, you need to migrate your old Support Library to AndroidX.
Why is migration to AndroidX necessary
You might be thinking: AndroidX is just a refactoring of Support Library 28, so why migrate? To this problem, we can give the following reasons:
- The Support Library has completed its historical mission, and 28 will be its final release. We will not continue to fix bugs or release new features in the Support Library;
- Better package management: separate versions, separate names, and more frequent updates. The above advantages, AndroidX out of the box;
- There are a number of well-known libraries that have been migrated to AndroidX, such as Google Play services, Firebase, Bufferknife, Mockito 2, SQL Delight, and we’ll talk about how to migrate their dependencies later.
- We are working hard to promote the AndroidX namespace, and all new component libraries, such as Jetpack Compose and CameraX, will be part of AndroidX in the future.
How do I migrate to AndroidX
preparation
Before starting the migration, we want you to do the following things to make the rest of your work smoother and smoother:
- First, back up the entire project. Most developers use a code version control system, but since the migration involves a lot of file changes, it is recommended that you back up the entire project;
- Second, we want you to minimize concurrent feature development;
- Finally, it is recommended that you do your migration work in a separate branch.
Starting the migration
Throughout the migration step, we will focus on fixing bugs and getting your application to compile and pass all tests.
The following is a schematic of the migration process, although there are many steps, each of which is explained in this article:
Step 1: Upgrade the Support Library to 28
First, we want you to upgrade your current Support Library dependencies to version 28. If you migrate from earlier versions of the Support Library, you may encounter API incompatibilities that require namespace changes; The only difference between the Support Library 28 API and AndroidX is namespace. Therefore, we recommend that you try to upgrade the Support Library to version 28, handle all API changes, and ensure that the build passes before proceeding to the next step, so that the changes are minimal.
Step 2: Enable Jetifier
The next thing you need to do is open Jetifier. Jetifier can help you migrate third-party dependencies to AndroidX. Literally, Jetifier modifies the code for these third-party libraries to make them compatible with projects using AndroidX. However, Jetifier does not modify your source code or auto-generated code, so don’t worry about additional adverse effects.
To enableJetifier, simply add “android.useAndroidX = ture” and “android.enableJetifier = true” to the gradle.properties file. UseAndroidX “setting is used to enable automatic import of AndroidX libraries. When you auto-complete or import dependent libraries, the AndroidX libraries will be automatically imported.
Step 3: Check the compatibility of third-party library versions
Once you have enabled Jetifier, it is time to upgrade the third-party dependencies to compatible versions. Before you actually start migrating, it’s a good idea to update all dependencies to the latest.
Why would you do that? We’ve actually stumbled on this one ourselves, and we have a demo app: Plaid, which relies on the image loading library Glide, we were going to use Plaid to demonstrate how to migrate applications to AndroidX, but we ran into a bunch of compile errors when we started migrating without checking the Glide dependency version. It turned out that the version you were relying on was not compatible with AndroidX.
When we upgraded Glide and other dependent library versions, we did the migration, and the same error did not occur again. Therefore, it is recommended that you check and update your app’s third-party dependencies before starting the migration. New versions of third-party libraries may already be compatible with AndroidX. Since Jetifier won’t help you migrate the dependency libraries that automatically generate code, you’ll still need to check for compatibility with AndroidX yourself.
If you skip the previous two steps, you may encounter some problems:
- If you are currently using a third-party Library that is not compatible with AndroidX, you will see it still trying to pull an older version of the Support Library;
- If your project is partially migrated, you may also encounter type duplication errors because the project is trying to pull the same code from the Support Library and AndroidX.
Step 4: Convert the Support library dependencies to AndroidX
Before starting this step, you should complete the first three steps: upgrading the Support Library to version 28; Open Jetifier; Upgrade and check third-party dependent libraries. With all of this confirmed, we can finally start the real migration. Here are three ways to do this:
- Use the Android Studio automatic migration tool
We have added the “Migrate to AndroidX” option in Android 3.2 Stable. You can find the “Migrate to AndroidX” option in the “Refactor” menu:
- Use automatic migration scripts
We also realized that there were teams that weren’t using Android Studio, and there were applications that were too complex to work with our tools.
So there are two options, one of which is to use the grep and sed commands in the bash script. Before we get into scripting for migration, a special thank you to Dan Lew for providing this tool.
You can use the short link: goo.gle/ AndroidX-mi… Go to the GitHub page for scripting source code, where you can also find more community contributions.
You need to manually configure the type mapping table “androidx-class-mapping.csv” and the project path address. The only effective part of the script is grep followed by a sed command to replace the package name imported from the project:
- Human migration
Another option is to do the migration manually. In moving to AndroidX, you can see the type mapping table for the Support Library and AndroidX mentioned earlier. With this mapping table, you can make the substitution as required:
Possible problems
Of course, the truth is that things are not always so smooth. Below we have collected some common migration questions that we hope will help you.
Common cases requiring manual handling
The drawerLayout and RecyclerView versions are set with a set of variables:
The automatic migration tool also does not modify your obfuscation files and build scripts. If these files contain relevant package names, you need to manually correct them.
To deal with conflict
We mentioned earlier that the migration must be handled in a new branch, and we have a few more things to share about this.
Because the migration will modify a large number of files, we recommend slowing down or stopping the development work at hand. While requiring the entire development team to shut down may sound outrageous, it can greatly reduce the potential for merger conflicts.
The next best thing is to have some people in a separate branch focused on the migration, if possible. At the same time, alert the rest of the team to impending merger conflicts.
When migrating dependencies, focus on fixing errors with the primary goal of successful compilation and passing all tests. Do not refactor or introduce new functionality at the same time as the migration.
Check the version of the library imported by the automatic migration tool
When you run the auto-migration feature, you may find both stable and Alpha versions in the new dependency library. It really depends on our latest release. You need to manually modify versions of these dependent libraries to meet the specific needs of your own project.
Document resources
We have summarized some documents related to this article at the end for your review and search.
AndroidX overview includes an overview of AndroidX, migration guides, and mapping tables from the Support Library to stable and Alpha versions of the AndroidX Library. If you want to script the migration, a CSV file for the mapping table is also provided.
We have an article on Kotlin & Jetpack best practice tips for making the “Plaid shirt” more stylish and describe the migration of the sample project Plaid to AndroidX. In this article, we explain the steps of the migration, the problems encountered, and the corresponding solutions.
We also provide a problem tracker page where you can see the problem we are working on or create a new problem for us via the button in the upper left corner.
Good luck with the migration to AndroidX!
You can also review the 2019 Android Developer Summit presentation via video — It’s time to migrate to AndroidX!
Tencent Video link: v.qq.com/x/page/r301…
Check out Android’s official Chinese document, AndroidX Overview, here
