docs/faq.md
[TOC]
androidx?Artifacts within the androidx package comprise the libraries of
Android Jetpack.
Libraries in the androidx package provide functionality that extends the
capabilities of the Android platform. These libraries, which ship separately
from the Android OS, focus on improving the experience of developing apps
through broad OS- and device-level compatibility, high-level abstractions to
simplify and unify platform features, and other new features that target
developer pain points.
androidx and AndroidX related to Jetpack?They are effectively the same thing!
Jetpack is the external branding for the set of components, tools, and guidance that improve the developer experience on Android.
Libraries within Jetpack use the androidx Java package and Maven group ID.
Developers expect these libraries to follow a consistent set of API design
guidelines, conform to SemVer and alpha/beta revision cycles, and use the public
Android issue tracker for bugs and feature requests.
AndroidX is the open-source project where the majority* of Jetpack
libraries are developed. The project's tooling and infrastructure enforce the
policies associated with Jetback branding and androidx packaging, allowing
library developers to focus on writing and releasing high-quality code.
<sup>* Except a small number of libraries that were historically developed using a different workflow, such as ExoPlayer/Media or AndroidX Test, and have built up equivalent policies and processes.</sup>
androidx?Please read our blog post about our migration.
As part of the Jetpack effort to improve developer experience on Android, the Support Library team undertook a massive refactoring project. Over the course of 2017 and 2018, we streamlined and enforced consistency in our packaging, developed new policies around versioning and releasing, and developed tools to make it easy for developers to migrate.
No, revision 28.0.0 of the Support Library, which launched as stable in
September 2018, was the last feature release in the android.support package.
There will be no further releases under Support Library packaging and they
should be considered deprecated.
You can see all publicly released versions on the interactive Google Maven page.
If you're working on a new feature or bug fix in AndroidX, you may want to test your changes against another project to verify that the change makes sense in a real-world context or that a bug's specific repro case has been fixed.
If you need to be absolutely sure that your test will exactly emulate the developer's experience, you can repeatedly build the AndroidX archive and rebuild your application. In this case, you will need to create a local build of AndroidX's local Maven repository artifact and install it in your Android SDK path.
First, use the createArchive Gradle task to generate the local Maven
repository artifact:
# Creates <path-to-checkout>/out/repository/
./gradlew createArchive
Using your alternate (non-AndroidX) version of Android Studio open the project's
settings.gradle.kts and add the following within
dependencyResolutionManagement to make your project look for binaries in the
newly built repository:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// Add this
maven {
setUrl("<absolute-path-to-checkout>/out/repository/")
}
}
}
NOTE Gradle resolves dependencies in the order that the repositories are defined (if 2 repositories can resolve the same dependency, the first listed will do so and the second will not). Therefore, if the library you are testing has the same group, artifact, and version as one already published, you will want to list your custom maven repo first.
Finally, in the dependencies section of your standalone project's build.gradle
file, add or update the implementation entries to reflect the AndroidX modules
that you would like to test. Example:
dependencies {
...
implementation "androidx.appcompat:appcompat:1.0.0-alpha02"
}
If you are testing your changes in the Android Platform code, you can replace
the module you are testing
YOUR_ANDROID_PATH/prebuilts/sdk/current/androidx/m2repository with your own
module. We recommend only replacing the module you are modifying instead of the
full m2repository to avoid version issues of other modules. You can either take
the unzipped directory from
<path-to-checkout>/out/dist/top-of-tree-m2repository-##.zip, or from
<path-to-checkout>/out/repository/ after building androidx. Here is an
example of replacing the RecyclerView module:
$TARGET=YOUR_ANDROID_PATH/prebuilts/sdk/current/androidx/m2repository/androidx/recyclerview/recyclerview/1.1.0-alpha07;
rm -rf $TARGET;
cp -a <path-to-sdk>/extras/m2repository/androidx/recyclerview/recyclerview/1.1.0-alpha07 $TARGET
Make sure the library versions are the same before and after replacement. Then
you can build the Android platform code with the new androidx code.
Put content in a markdown file that ends with -documentation.md in the
directory that corresponds to the Overview page that you'd like to document.
For example, the androidx.compose.runtime
Overview page
includes content from
compose-runtime-documentation.md.
It is enabled automatically as androidx minSdkVersion is API >=21.
If you've encountered a build failure and you're not sure what is triggering it,
then please run
./development/diagnose-build-failure/diagnose-build-failure.sh.
This script can categorize your build failure into one of the following categories:
Some more-specific build failures are listed below in this page.
Like a normal Android library developed in Android Studio, libraries within
androidx are built against prebuilts of the platform SDK. These are checked in
to the prebuilts/fullsdk-darwin/platforms/<android-version> directory.
If you are developing against pre-release platform APIs in the internal
androidx-platform-dev branch, you may need to update these prebuilts to obtain
the latest API changes.
If Gradle cannot resolve a dependency listed in your build.gradle:
You will probably want to import the missing artifact via importMaven.sh
prebuilts/androidx to facilitate reproducible builds even if remote
artifacts are changed.You may need to establish trust for the new artifact
libs.versions.tomlLibraries typically reference dependencies using constants defined in
libs.versions.toml.
Update this file to include a constant for the version of the library that you
want to depend on. You will reference this constant in your library's
build.gradle dependencies.
After you update the libs.versions.toml file with new dependencies, you
can download them by running:
cd frameworks/support &&\
development/importMaven/importMaven.sh import-toml
This command will resolve everything declared in the libs.versions.toml file
and download missing artifacts into prebuilts/androidx/external or
prebuilts/androidx/internal.
Make sure to upload these changes before or concurrently (ex. in the same Gerrit topic) with the dependent library code.
libs.versions.tomlYou can also download a dependency without changing libs.versions.toml file by
directly invoking:
cd frameworks/support &&\
./development/importMaven/importMaven.sh someGroupId:someArtifactId:someVersion
Kotlin Multiplatform projects need prebuilts to compile native code, which are
located under prebuilts/androidx/konan. After you update the kotlin
version of AndroidX, you should also download necessary prebuilts via:
cd frameworks/support &&\
development/importMaven/importMaven.sh import-konan-binaries --konan-compiler-version <new-kotlin-version>
Please remember to commit changes in the prebuilts/androidx/konan repository.
If you import a new dependency that is either unsigned or is signed with a new, unrecognized key, then you will need to add new dependency verification metadata to indicate to Gradle that this new dependency is trusted. See the instructions here
If an older version of a dependency prebuilt was already checked in, please
manually remove it within the same CL that adds the new prebuilt. You will also
need to update Dependencies.kt to reflect the version change.
You probably need to update the prebuilt SDK used by the gradle build. If you are referencing new framework APIs, you will need to wait for the framework changes to land in an SDK build (or build it yourself) and then land in both prebuilts/fullsdk and prebuilts/sdk. See Updating SDK prebuilts for more information.
Because AndroidX must compile against both the current framework and the latest SDK prebuilt, and because compiling the SDK prebuilt depends on AndroidX, you will need to refactor in stages: