• Kevlar and AndroidX
  • Original post by Tiem Song
  • The Nuggets translation Project
  • Permanent link to this article: github.com/xitu/gold-m…
  • Translator: Mirosalva
  • Proofread by: PhxNirvana

An AndroidX migration guide

Images courtesy of Virginia Poltrack.

Plaid is a fun app that presents a Material Design style and rich interface. The app has recently been refactored using today’s Android app development techniques. For more information about the app and the redesigned visuals, see Restitching Plaid.

  • Restitching Plaid: Update Plaid to the latest application standard

Like most Android apps, Plaid relies on the Android Support Library, which provides backward compatibility for new Android features to run on older Versions of the operating system. In September 2018, the latest Support Library release (28.0.0) was released, Android libraries released with the Support Library have been migrated to AndroidX (except the Design Library was migrated to Android’s Material Components), and new developments in these libraries are based on AndroidX. Therefore, the only option to receive bug fixes, new features, and other library updates is to migrate Plaid to AndroidX.

What is a AndroidX?

At Google I/O 2018, the Android team announced AndroidX. It is the open source code that the Android team uses to develop, test, package, customize, and distribute libraries in Jetpack. Like the Support Library, each AndroidX Library is released independently of the Android OS and provides backward compatibility across Android versions. It is a major improvement and comprehensive alternative to the Support Library.

Read below to see how we prepared our own code for the migration process and performed it.

Preparing for migration

I strongly recommend doing the migration in a version-controlled branch. This way you can gradually resolve any migration issues that may arise, while isolating each change for analysis and locating issues. You can check out our discussion under the Pull Request and keep up with the latest information by clicking on the submit link below. In addition, Android Studio provides an optional service to do project backup before migration.

As with any large-scale code refactoring effort, it is best to minimize merging between the migration branch and the main development branch during the migration to AndroidX to avoid merge conflicts. Although not feasible for other applications, our team was able to temporarily suspend code submission to the main branch to help with the migration. It is also necessary to migrate the entire application at once, because a partial migration — using both AndroidX and the Support library — will result in a failure in the migration process.

Finally, read the tips on migrating to AndroidX on developer.android.com. Now let’s get started!

Depend on the logo

Before you start, the most important piece of advice for code preparation is:

Make sure the dependency libraries you are using are compatible with AndroidX.

Third-party libraries that rely on an older support library may not be compatible with AndroidX, which is likely to cause your application to fail to compile after migrating to AndroidX. One way to check whether any of your application’s dependencies are compatible is to visit the project site of those dependencies. A more straightforward approach is to start the migration and check for possible errors.

For the Plaid application, we used an older version (4.7.1) of Glide, a graphics loading library that is not compatible with AndroidX. This resulted in a code generation issue that made the application unbuildable after the migration (a similar issue documented under Glide), and we updated Glide to version 4.8.0 (see this submission) before starting the migration, which added support for AndroidX annotations.

For this, try to update to the latest version of the third-party libraries that your application relies on. This is especially a good idea for the Support library, because upgrading to 28.0.0 (as of the final version of this writing) will make the migration smoother.

Use Android Studio for refactoring

During the migration, we used the refactoring tools built into Android Studio 3.2.1. The AndroidX migration tool is located in the Refactor > Migrate to AndroidX option on the menu bar. This option will migrate all modules for the entire project.

Preview window after running AndroidX refactoring tool.

If you don’t use Android Studio or prefer another tool for migration, consult Artifact and Class to compare schema and Class changes between the old and new support libraries, which are also available in CSV format.

The AndroidX migration tool in Android Studio is the main method of AndroidX migration. The tool is constantly being refined, so if you encounter problems or want to see a feature, please submit a vote on the Google Problem Tracker page.

The migration application

Minimal code changes to ensure that the application still works.

After running the AndroidX migration tool, a lot of code was changed, but the project didn’t compile successfully. At this point, we’ve done minimal work to get the application up and running again.

This approach helps break down the process into manageable steps. We left tasks such as fixing the import order, extracting dependent variables, and reducing the use of the full CLASspath for subsequent cleanup.

One of the first errors that came up was repeating classes — in this case, PathSegment:

Execution failed for task ':app:transformDexArchiveWithExternalLibsDexMergerForDebug'.

> com.android.builder.dexing.DexArchiveMergerException: Error whileMerging dex archives: how to solve the problem of reference here: https://developer.android.com/studio/build/dependencies#duplicate_classes.

Program type already present: androidx.core.graphics.PathSegment
Copy the code

This is an error caused by the migration tool generating an error dependency (Androidx.core :core-ktx:0.3). We manually update (refer to this submission) to the correct dependent version (Androidx.core :core-ktx:1.0.0). This bug has been fixed in Android Studio 3.3 Canary 9 and later. We point this out because you may encounter similar problems during migration.

Next, the Palette API becomes empty in the new version, and to avoid this for now (refer to this commit), we added it!! Non-null assertion operator.

Then we encountered an error with the missing plusAssign. This loading was removed in version 1.0.0. The use of plusAssign is temporarily commented out (see this commit). Later in this article we will look at a sustainable solution to the Palette and plusAssign problems.

Now that the application is ready to run, it’s time to clean up the code!

Clean up the code

The application is running, but our continuous integration system reported a build error after the code was committed:

Execution failed for task ':designernews:checkDebugAndroidTestClasspath'.

> Conflict with dependency 'androidx.arch.core:core-runtime' in project ':designernews'. 

Resolved versions forRuntime classpath (2.0.0) and compile classpath (2.0.1-alpha01) differ. This can lead to runtime crashes this issue follow advice at https://developer.android.com/studio/build/gradle-tips#configure-project-wide-properties.Alternatively, you can try to fix the problem by adding this snippet to /... /plaid/designernews/build.gradle: dependencies { implementation("Androidx. Arch. The core: the core - the runtime: 2.0.1 - alpha01")}Copy the code

We added the missing dependency module as suggested in the test log (see this submission).

We also took the opportunity to update our Gradle plugin version, Gradle Wrapper version, and Kotlin version (see this submission). Android Studio recommended that we install version 28.0.3 of the build tool, which we did. The problems we encountered using the Gradle 3.3.0-Alpha13 plugin were resolved by demoting to 3.3.0-Alpha8.

One drawback of the migration tool is that if you use variables in dependent versions, the migration tool automatically inlines them. We reextracted these versions from the build.gradle file (see this commit).

Above we mentioned a temporary solution to the plusAssign and Palette problem after running the AndroidX migration tool. We re-added the plusAssign function and related tests by lowering the AndroidX version (see this submission), and restored the commented code. At the same time, we update the Palette parameter to the version that can be empty (see this commit) so that no operator is needed!! .

Similarly, automatic conversion may require some classes to use their full classpath. Making minimal manual corrections is a good idea. As part of the cleanup, we removed the full classpath and re-added related references if necessary.

Finally, a few minor test-related changes were added to the project, around dependency conflicts during testing (see this commit) and Room’s test cases (see this commit). At this point our project is fully transformed and our tests have passed.

The end of the process

Despite some hurdles, the AndroidX migration has gone relatively smoothly. The problems encountered mainly involve incorrect conversions of dependent libraries or classes, and API changes in new libraries. Fortunately, these are relatively easy to solve. Plaid is now ready to be used again!

If you find any mistakes in your translation or other areas that need to be improved, you are welcome to the Nuggets Translation Program to revise and PR your translation, and you can also get the corresponding reward points. The permanent link to this article at the beginning of this article is the MarkDown link to this article on GitHub.

The Nuggets Translation Project is a community that translates quality Internet technical articles from English sharing articles on nuggets. The content covers Android, iOS, front-end, back-end, blockchain, products, design, artificial intelligence and other fields. If you want to see more high-quality translation, please continue to pay attention to the Translation plan of Digging Gold, the official Weibo, Zhihu column.