How to migrate a project to AndroidX

Refactoring your code to use AndroidX Jetpack made easy
How to migrate a project to AndroidX

Using AndroidX is highly recommended: Pepper applications and libraries developed at SoftBank Robotics use it, and Google announced it as the new standard.

Here you will learn how to migrate a project to AndroidX using the "Refactor > Migrate to AndroidX" menu in Android Studio. In most cases, it will do the trick without any more hassle. Still, you should take the time to read the prerequisites and infos in this blog article, as following the recommended steps will make activating Jetpack and migrating from Support Library to AndroidX easier.

Introducing terminology

Jetpack is a set of libraries and tools to help developers write high quality code and apps. These libraries limit boilerplate code and simplify complex tasks.

AndroidX is the package name for all libraries within Jetpack. It is distributed as an open source library.

Support Library was the equivalent before its refactoring to AndroidX namespace was announced in 2018.

This is fine, but you may wonder why you should spend time migrating an application that is working perfectly well without AndroidX?

Why should I migrate?

Here are several reasons why you should consider switching to AndroidX:

  1. Version 28 of Android Support Library is the last release of Android Support namespace. It is no longer maintained since 2018. It means no bug fixes and no new features.
  2. AndroidX has improved package management and you will get standardized and independent versioning, standardized naming and more frequent releases.
  3. To have access to the libraries that use AndroidX, you need to use it in your app. Several libraries have already migrated to AndroidX namespace, including notable players such as Firebase.
    And of course, all SoftBank Robotics libraries use AndroidX. You can find them here # Softbank Robotics Lab.
  4. All new Android libs are in AndroidX.

Preparing your project for migration

  • As you would do for any change that may have a major impact on your code: back up your project! In most cases you are already using a version control tool such as git, which makes things easier.
  • Use a dedicated branch for your migration changes.
  • Minimize feature development during migration as much as possible.

Now let's check the main steps recommended by the Android team for projects using Support Library 28 or less.

As always when developing on Pepper QiSDK, you should install the latest Android SDK Platform. See installation section in Pepper QiSDK tutorials.

1/ Update to Support Library 28

Migrating directly to AndroidX from an older version of the Support Library than 28 isn't recommended. If you use an older version of Support Library such as 26 or 27, it will be easier and smoother to upgrade to Support Library 28 first.

Changes between versions 26 or 27 and AndroidX include namespaces but also some API changes, so it's best not to handle all of them at once:updating to Support Library 28 addresses API changes and ensures that your app compiles correctly before migrating to AndroidX.

Indeed, Support Library 28 and AndroidX are binary equivalent. Only the package name changes between these two versions, involving minor changes to fix during migration.

2/ Enable Jetifier

Jetifier helps migrate third party dependencies. It has no impact on your source code, as it only changes the byte code of these dependencies to make them compatible with AndroidX.

Adding the two following lines to your app gradle.propreties file will enable Jetifier:

android.useAndroidX=true

android.enableJetifier=true

Activate AndroidX means that when code auto-completion imports libraries, it imports the AndroidX version of these libraries.

3/ Update dependencies

You should update third-party libraries before migration, otherwise you may face compilation issues. The library version used needs to be AndroidX-compatible.

4/ Migrate to AndroidX

Once you complied with the previous steps, you can migrate your code.

From Android Studio version 3.2 and above access the "Refactor > Migrate to AndroidX..." menu.

It will instantly migrate your source code.

'Refactor > Migrate to AndroidX' menu
'Refactor > Migrate to AndroidX' menu

This will work in most cases. Still, in some situations you may need to use a more technical way of updating your project.

5/ Alternative: Migrate using a Bash script

Android provides a bash script for those of you who may not use Android Studio or whose more sophisticated app architecture prevents automatic migration.

A bash script using grep and sed will do the trick to help you replace all source code instances of support library packages with their AndroidX equivalent. It really is the brute force version, isn't it?

You can find the script on https://goo.gle/androidx-migration-script

Troubleshooting

You may still face issues as some changes are not easy to automatize.

  • Regarding property and build files, the bash script does not modify them completely, so you may need to manually update the following:
  • Version configuration files
  • Proguardfiles
  • Build scripts
  • The migration tool can sometimes suggest either an alpha or a stable version of the referenced library, depending on the version of the most recent release. Check it and select the most appropriate version for your usage.
    // Support Library
    implementation 'com.android.support:appcompat:28.0.0'

    // AndroidX - Alpha
    implementation 'androidx.appcompat:appcompat:1.1.0-alpha01'

    // AndroidX - Stable
    implementation 'androidx.appcompat:appcompat:1.0.2'