One of the core principles of Jetpack is “Developed as open-source and compatible with AOSP Android,” but what does that mean in practice? This guide provides specific, technical guidance on developing an open-source library and interacting with proprietary or closed-source libraries and services.
Our definition of open-source includes products that provide publicly-available source code that can be compiled by an end-user to generate a functional version of the product, e.g. an AAR, that is equivalent to the one used by the library.
The only unconditional exception to this definition is the Android Open Source Project itself, which does not release sources publicly until well after its API surface has been finalized.
Libraries which are developed against the pre-release Android platform SDK may remain closed-source until the platform SDK's API surface is finalized, at which they must move to open-source.
In specific cases, libraries may include closed-source dependencies. See the Open-source compatibility section of the API Guidelines for implementation details.
.so file with no publicly-available source codeJAR) or in a public repositoryThe Android Open-Source Project enables a diverse ecosystem of devices with a wide array of software environments in which our libraries will operate. Many of those devices are certified to run Play Services, but it's important for our libraries to work on all devices that are certified as Android -- even those with no Google software installed.
Isolating behavior makes it easier to write reliable and targeted tests, but introducing dependencies on proprietary components makes this difficult. In a well-abstracted library, developers should be able to write integration tests against the library's documented API surface without concerning themselves with the implementation details of a backing service.
Developers should be able to choose between proprietary components; however, libraries are also encouraged to provide a sensible default.
Third-party developers should be able to provide their own backing services, which means service discovery mechanisms, communication protocols, and API surfaces used to implement a backing service must be publicly available for implementation.
Third-party developers should also be able to validate that their implementation conforms to the expectations of the library. Library developers should already be writing tests to cover their backing service, e.g. that a service implementing a protocol or interface is correct, and in many cases these tests will be suitable for third-party developers to verify their own implementations.
While we recommend that developers provide a stub backing implementation in a -testing artifact or use one in their own unit tests, we do not require one to be provided; only that it is possible to write one.
Intent handling as a service discovery mechanism and hard-codes a reference to com.google.android as a ranking heuristic.Bundle where they keys, values, and behaviors are documented outside of Jetpack.Bundle with a privately-documented protocol means that (1) it is not possible to write adqeuate tests in Jetpack and (2) developers outside of Google cannot feasibly write correct backing implementations.Bundle with a strongly-typed and documented API surface and robust suite of tests to ensure implementations on either side of the protocol are behaving correctly.interface and an API that allows developers to specify a backing service using classes that implement that interface. The interface API surface has several @hide methods annotated with @RestrictTo(LIBRARY_GROUP).interface means that only Jetpack libraries can feasibly provide a backing implementation.interface fully public and documented so that it can be implemented by a third-party. They should also provide robust tests for the default backing implementation with the expectation that third-party developers will use this to verify their own custom implementations.