[MUSIC PLAYING]
NICK ANTHONY: Hi, everyone.
My name is Nick Anthony, and I'm a program manager with Jetpack.
TIEM SONG: Hello, everyone.
My name is Tim song.
I'm a Developer Programs Engineer
on the Android Developer Team.
Today, we're going to talk about migrating your app to AndroidX.
NICK ANTHONY: Great.
So before we dive in, it's important to ask ourselves,
what is AndroidX?
We throw a lot of terms out there.
So by a show of hands, who here has heard of AndroidX?
By a show of hands, who here has heard of Jetpack?
By a show of hands, who here has heard of the Support Library?
By a show of hands, who here knows what the difference
is between all those?
[CHUCKLING] Great.
I think I caught most of the people in the room.
But for those of you who need more clarification
or may not know, Jetpack is the set of libraries, tools,
and guidance to help you, developers, write high quality
apps easier.
So we think of that in terms of three things.
That's best practices, limiting boilerplate code,
and simplifying complex tasks.
So you can focus on the code that you really care about.
So how does this relate to AndroidX?
As you can see on the slide, AndroidX
is the package name for All libraries within Jetpack.
So we think of AndroidX as the open source project
that we use to develop, test, version, and release
Jetpack libraries.
Now, how is this related to Support Library?
So if you remember, back in I/O of 2018,
we announced that we'd be refactoring the Support Library
to the AndroidX namespace.
So we did this with Support Library 28.
We also announced AndroidX 1.0.
And so we'll touch on that a little bit
about why it's important.
Great.
So we got to the point, now, where
we talked a little bit about what these things are.
And now, the next question we want to ask ourselves
is, why should I migrate?
Why is this talk important?
Why are we here?
So there's four points we want to bring up.
One is that the Support Library is done.
28.0 was the last release of the Android Support namespace.
So this is a namespace we're no longer maintaining.
So if you want bug fixes or new features that normally would
have gone in the Support Library,
you're going to need to go and migrate to AndroidX.
The next thing, you get some better package management.
So these are the reasoning why we made the refactor--
that's the standardized and independent versioning, as well
as the better standardized naming
and more frequent releases.
These are what you get out of the box with AndroidX.
The third thing is that some other libraries have migrated
to the AndroidX namespace.
So there's some notable players in there,
as well as Google Play services.
Firebase, Butterknife, Mockito 2,
in some cases, and SQL Delight.
And we're going to touch on migrating these dependencies
in just a minute.
The final thing we want to point out
is that all new libraries are coming out in AndroidX.
So we're really pushing forward on AndroidX namespace.
And some of you might have heard of things like Jetpack Compose
or CameraX.
Those are going to be in the AndroidX namespace.
And the precursor is going to be migrating to AndroidX.
So now we've talked about what these things are, what
is Jetpack, what is AndroidX.
We've also talked about why you should migrate.
I'm going to pass to Tiem, now, to talk
about the specifics of actually going through this migration.
TIEM SONG: Thanks, Nick.
So let's go ahead and talk about how we want to migrate.
But before we do that, here are some things
to do to prepare your project for migration,
so you can have a smoother experience.
First, back up your project.
Now, many of you might be using Source Control.
So that's probably OK.
But just in case, make a backup of this project,
because the migration will change many
of the files in your project.
Next, we want you to try to minimize future development
during this time.
And we'll cover this more in a little bit.
And also, try to make these migrations
on a separate branch.
Now, we have a recommended approach on how to migrate.
Now, I know these are a lot of steps,
and we'll explore these one by one.
I'll explore steps 1 through 3.
And then Nick will talk about steps 4 and 5.
So first, we want to update the Support Library to version 28.
Now, if you're on an older version of the support library,
say 26 or 27, and try to make the migration all
the way to AndroidX, you're probably
going to have a bad time.
That's because not only will you need
to address the namespace changes, but also the API
changes between 26, 27, 28, and AndroidX.
So what we suggest is first try to update to version 28,
and address all of those API changes,
and get your app compiling with 28.
And at that point, make them jump over to AndroidX.
Now, Support Library version 28 and AndroidX 1.0
are binary equivalent.
So what does that mean?
That means only the package name changes
between those two versions.
All the APIs are the same.
So this way, you'll have, probably,
a minimal set of things that you need
to fix between migrating from 28 to AndroidX.
So now that you've migrated your app to Support Library 28,
we next want to enable Jetifier.
So what is Jetifier, and why is it necessary?
So Jetifier will help you migrate your third party
dependencies to use AndroidX.
What this means is that Jetifier will actually change the flight
code of those dependencies to be compatible with your project
that's using AndroidX.
Now, Jetifier won't do a couple of things.
It won't change your source code,
nor will it migrate your generated code.
Here's how to enable Jetifier in your app.
You add a couple of lines to your gradle.properties files.
And in here, useAndroidX is set to true,
along with enableJetifier.
Now, the useAndroidX setting turned to true means
that when you do code auto completion
and you're importing libraries, you'll
import the AndroidX version of that library instead
of the old Support Library version.
Moving on to step 3.
Once you've enabled Jetifier, we'll
need to update your dependencies.
So a lot of third party dependencies
may need to be updated before you actually
start the migration.
So here are some of the dependencies
that we covered earlier.
And I want to highlight a specific example.
One of our flagship sample apps is called Plaid.
And it uses the Glide image loading library.
We wanted to use Plaid as an example of how
to migrate over to AndroidX.
And we discovered when we did the migration without first
migrating our Glide dependency, we
ran into a bunch of compilation issues.
And we looked, and we found that version
of Glide that we were using was not AndroidX compatible.
So what we did was we first updated Glide
and our other dependencies, and then ran
the AndroidX migration.
And then that error no longer appeared.
So if you can, try to update your third party dependencies
first, before starting the migration.
Now, if you're using a code generation library,
Jetifier won't modify these.
So you might need to check if the code generation
library actually is compatible with AndroidX.
So let's look at some common errors
that might happen if you skip steps 2 and 3, one of which
is the third party code that you're using
is not compatible with AndroidX.
You'll see that it's trying to pull
in the old version of the Support Library.
Also, if you have a project that's partially migrated,
you might get a duplicate class error,
where it's trying to pull in the same code
from both the Support Library and AndroidX.
So back over to Nick to talk about step 4.
NICK ANTHONY: Thank you.
Now, at this point, we're going to talk a little bit more
about the actual source code.
So we've got Support Library 28.
We've enabled Jetifier.
We've got our dependencies in order.
Now, we're going to go in.
And as of Studio 3.2 stable and above,
there is a handy migrate to AndroidX button.
So you can see under the refactor, in blue here,
there is a migrate to AndroidX.
And what that will do is migrate your source code.
And this will work for a majority of cases.
Now, however, we do realize that some teams may not use Studio.
Or there are some more sophisticated app architectures
that our tooling can't exactly automate.
So that leaves you with two options, here.
So these options and just migrating
the source code itself--
and one option's use a bash script.
So this is a grep and sed.
And we'll see the script in just a second,
here, in the next slide.
And before we dive in there, we want
to give special thanks to Dan Lew for picking this up.
You can follow this Go link, goo.gle/AndroidX migration
script.
And that'll link you to the GitHub source page, where
you can see that script as well as more community
contributions.
So how about that script?
You can see here, we have the class mapping, as well as
your project, and what is effectively just a grep command
followed by a sed command to replace those package names.
One thing to note when using this script
is it's pretty brute force.
It is a bash script.
So it may do some of those migrations
incorrectly on some cases.
So just be aware of that when you're
using this kind of methodology.
The other option is you can do it by hand.
So if you go to developer.android.com,
go to our Migrate to AndroidX page,
we have an artifact mapping from the Support Library packages
to our new ones, as well as a class mapping
with the same Support Library to AndroidX.
And that will let you do a case by case basis,
so you know it's right.
So at this point, if you've managed to follow us
along this long path, you get your project compiling again
and fix any tests that may have broken along the way.
You'll have a project that's running
on AndroidX, which is awesome.
So before we end this talk, I think
it's also important to talk about some issues
that the community has run into.
And so I'm going to pass over to Tiem, now, to dive into those,
so you know about them ahead of time.
TIEM SONG: So here are some issues
that you might run into for your migration.
So there are some things that we cannot automate.
So your version control files may require
some manual intervention.
Now, let's go ahead and see that in action.
Here is your build.gradle file prior to migration.
Now, you'll note that we used the old Support Library.
And in here, we actually extract out our version variables
into its own separate section.
Now, after running the migration tool,
we now have our drawer layout and recycler view,
using the new AndroidX packages.
But you'll notice that the version numbers are now
in line.
And their variable numbers are not yet changed.
So the tool does not modify this.
So you'll need to manually update this as such.
Let's change the drawer and recycler view versions,
manually, to 1.0.
And then we'll need to inline those variables back
in-- so something to be aware of.
Next, the tool has enabled to migrate your Pro Guard and any
built scripts.
So if you're using these and have package names in them,
you'll need to go in and manually edit these, as well.
Now, earlier, we talked about trying to slow down development
or working on separate branches.
And we'll talk about this a little bit more.
Because so many files will need to change,
we suggest that, if possible, try
to slow down or stop development entirely.
I know this is a very, very big ask, asking
an entire development team to stop development,
but this definitely reduces the amount of merge conflicts
that will happen.
If you can, have a few people on your team
just focus on the migration.
And then have everybody else say, hey,
there's a big merge conflict that will come in your future.
So let them know about this ahead of time.
Also, try to do the migration on a separate branch.
When you're doing this migration,
it's good to just focus on addressing the errors,
and getting your app to compile, and all tests passing again.
Don't try to do refactoring, or don't
try to pull in new features during this time.
It'll just make this a lot more difficult.
So when you run this migration tool,
you may have an alpha version or a stable version
of the library, depending on the most recent release.
Now, here, we have the Support Library version of appcompat.
And we run our migration tool, which
migrates our appcompat to an alpha version of the library.
Now, depending on your particular needs
in your project, you may want to use the alpha version.
Or maybe you prefer stable.
So this is something that you'll need to go back and manually
check to see which version it migrated to.
And make sure that you select the version that's
appropriate for your needs.
And you can find more about these particular versions
in the table, and we'll cover that in our resources section.
So we have our AndroidX documentation
on our developer.android.com website.
This covers the overview of AndroidX project,
our migration guide, the mapping table of the old Support
Library to the new stable and alpha versions,
and also the CSV files if you want to script your migration.
We also wrote an article detailing our migration
to AndroidX in the Plaid sample project.
And in here, we uncover the steps that we took,
some of the problems that we ran across,
and the solutions to those problems.
And you can access that via goo.gle/plaid androidx
migration.
And finally, we had the issue tracker,
where you can go to see the issues that we're currently
working on with the migration tool.
Or if you like, you can create a new issue
using the button at the top left of the page.
So we wish you the best of luck in migrating your app
to AndroidX.
And if you're attending the conference in person,
please stop by our Jetpack Sandbox with any questions,
or tell us about your experience in migrating.
Thank you very much.
NICK ANTHONY: Thank you.
[APPLAUSE]
[MUSIC PLAYING]