This page describes the properties and options you should set to prepare your library project for publication using the Android Gradle plugin (AGP). Even if you have already set some of these properties at the outset of creating your library, we recommend reviewing the following guidance to optimize your settings.
Choose a namespace
Android libraries need to declare a namespace so that they can generate a unique R class when their resources are compiled. This namespace should closely match the library’s root class package to avoid confusion when users import regular classes from the library as well as its R class.
Starting with AGP 7.0, you can set the
namespace in
the app’s build.gradle
file as shown in the following code example:
Groovy
android { namespace = 'com.example.library' }
Kotlin
android { namespace = "com.example.library" }
If you set the namespace in the build.gradle
file and no other data needs to
be specified, then the library doesn't need a manifest file. This is recommended
because it removes the need to parse the manifest file during build steps and
sync.
The namespace is purely a developer-facing property of the library. It has
nothing to do with the application’s identity that is set using the
applicationId
property. In previous versions of AGP, both the applicationId
property (for an
app) and the namespace
property (for a library) could be set using the
manifest’s package
attribute, which led to confusion. Note that a library project does not have an
applicationId; it is a property of an application only.
Choose a minSdkVersion value
Choosing a minSdkVersion
for
your library is an important aspect of publishing your library. The
minSdkVersion
should reflect the minimum version of Android that your code can
support.
Be aware of the following considerations when choosing a minSdkVersion
:
- Choosing a low
minSdkVersion
generally allows for wider distribution of your library. A library’s code is generally not executed unless the application calls it explicitly. An application can still run on a version of Android that is lower than required by a library dependency—if the library is not essential to core app functionality—by doing runtime checks before calling the library. Therefore, setting a library’sminSdkVersion
low enough that it can be embedded in apps, and called when possible, will likely help you reach more users. - Choosing a high
minSdkVersion
might prevent applications from including the library. The manifest merger, which is a step in AGP that merges manifest files from the application and from its dependencies, enforces that no dependencies have a higherminSdkVersion
than the application. - Choosing a high
minSdkVersion
might prompt app developers to disable manifest merger safety checks, which causes issues later in the build process. Because the manifest merger prevents application projects from including libraries with a higherminSdkVersion
than the app itself, app developers might disable the safety checks of the manifest merger to minimize build errors. However, this risks true incompatibility issues downstream. - It might be necessary to choose a high
minSdkVersion
in special cases where a library’s manifest includes a broadcast receiver or some other mechanism by which its code is triggered automatically. In these cases, choosing a highminSdkVersion
ensures that code can run. Alternatively, you can disable the automated behavior so that the app can opt in to executing the library after doing the right checks.
Note that to allow for embedding in apps, a library should use the
RequiresApi
annotation to
indicate to its callers that they need to do runtime checks. Android Lint uses
the RequiresApi
information for its inspections. For more resources on using
annotations to improve your API code and APIs, see Improve code inspection with
annotations.
Set up AAR metadata
An Android library is packaged in the form of an Android Archive (AAR) file. AAR metadata consists of properties that help AGP consume libraries. If your library is consumed by an incompatible configuration, and AAR metadata is set up, users are presented with an error message to help them resolve the issue.
AAR metadata does not contain properties that are important at runtime and therefore are not typically found in compiled Android applications.
Choose a minCompileSdk value
Starting with version 4.1, AGP supports
minCompileSdk
.
This indicates the minimum
compileSdk
that
consuming projects can use. If your library contains manifest entries, or
resources that make use of newer platform attributes, you probably need to
set this value.
The minCompileSdk
value can be set in the defaultConfig{}
,
productFlavors{}
, and buildTypes{}
blocks in the module-level build.gradle
file.
Groovy
android { defaultConfig { aarMetadata { minCompileSdk = 29 } } productFlavors { foo { ... aarMetadata { minCompileSdk = 30 } } } }
Kotlin
android { defaultConfig { aarMetadata { minCompileSdk = 29 } } productFlavors { register("foo") { ... aarMetadata { minCompileSdk = 30 } } } }
If you set minCompileSdk
in multiple places, Gradle prioritizes the settings
locations as follows during the build process:
buildTypes{}
productFlavors{}
defaultConfig{}
So in the above example, where minCompileSdk
is defined in both
defaultConfig{}
and productFlavors{}
, productFlavors{}
is prioritized
and minCompileSdk
is set to 30. To learn more about how Gradle
prioritizes settings when combining code and resources, see Build with source
sets.
Enable test fixtures
Test fixtures are commonly used to set up the code being tested, or facilitate the tests of a component. Starting with version 7.1, AGP can create test fixtures for library projects (in addition to application and dynamic-feature projects.)
When publishing a library that others consume, consider creating test
fixtures for your API. Test fixtures can be turned on in the module-level
build.gradle
file:
Groovy
android { testFixtures { enable = true } }
Kotlin
android { testFixtures { enable = true } }
When you turn on test fixtures, Gradle automatically creates a
src/testFixtures
source set where you can write test fixtures. See the
TestFixtures
API reference doc for more options.
For more information, refer to the Gradle’s documentation about using test fixtures.