The Android Compatibility Definition Document (CDD) is Google's way to specify guidelines, rules, and constraints to be considered for an Android-compatible device. Every device designer and manufacturer has to refer to the CDD to be able to easily port Android onto its own hardware platform.

For each release of the Android platform, Google provides a detailed CDD. The CDD represents the policy aspect of Android compatibility and its role is to codify and clarify all the requirements and eliminate any ambiguity. The main goal is to provide rules for manufacturers to let them create complex hardware devices, compatible with Android SDK and Android apps.

Designing and developing a new device is no easy task. Even the smallest detail matters. Think about OpenGL support. There is no possible way to be sure that the graphical experience will be great for the user. The only thing that's possible is working according to the guidelines and then "test, test, and test". That's why providing as many details and guidelines as possible is the only way to help the manufactures to achieve their goal.

However, the CDD does not attempt to be comprehensive—it couldn't be. It just serves as guidance to approach as easily as possible the final goal—a compatible device. Further help comes from the source code itself and from the Android SDK API that can be considered a compatibility-proof test bench. Think about CDD as an overview of the minimum set of constraints to be compliant with: it's the very first step of the journey.

Native API gives the developers the opportunity to call native C, and partially C++, code from an Android Java application. Native code is compiled as standard ELF .so files and stored in the app APK file. Being native code, it has to be compiled for every architecture we are going to support, because, contrary to the bytecode, it can't be built once and run on every architecture.

As integrators, we must embrace one or more Android Application Binary Interfaces (ABIs) and aim for having full compatibility with the Android NDK. Of course, Google provides guidelines and constraints to easily reach this goal. These are the basic rules for proper compatibility:

From a libraries point of view, our implementation must be source-compatible (that is, header compatible) and binary-compatible (for the ABI) with all the following libraries:

These libraries also provide minimal support for the C++ JNI interface as well as support for OpenGL.

An implementation of each one of these libraries must be present in our system to be compatible with Android NDK. This is a dynamic list and we cannot treat it as a definitive set of libraries: future versions of Android could add new libraries and increase development possibilities and scenarios. That's why native code compatibility is challenging. For this reason, Google strongly suggests to use the implementations of the libraries listed earlier from the Android Open Source Project, taking advantage of the Open Source philosophy of Android and to enjoy well-supported and well-tested source code.

Nowadays, all major manufactures are switching to 64-bit architecture and new ARMv8 architecture deprecates lots of old CPU operations. Unfortunately, the market is still full of 32-bit compatible software and even on 64-bit architecture we must still support these deprecated operations, to avoid scaring developers and losing precious market share. Fortunately, we can choose to make them available via real hardware support or software emulation, at the expense of performance.

Supporting 32-bit architecture can be very tricky. We can just think about one simple scenario, for example, accessing the /proc/cpuinfo file. Legacy versions of the Android NDK used /proc/cpuinfo to discover CPU features. For compatibility with applications built using 32-bit NDK, we must specifically include the following things in /proc/cpuinfo when it is read by 32-bit ARM applications:

The tricky part is that these requirements only apply when /proc/cpuinfo is read by 32-bit ARM applications. The file must be not altered when read by 64-bit ARM or non-ARM applications.

When Android 4.4 KitKat was released, users could select a new experimental runtime environment in the Settings menu: ART. Android RunTime or, shortened, ART, is the current default runtime solution that replaced Dalvik from Android 5 Lollipop. The previous diagram shows a comparison between Dalvik and ART architecture.

The idea behind Dalvik's JIT (just-in-time) execution was to profile the applications while they were being executed and dynamically compile the most-used segments of the bytecode into native machine code. Native execution of these most-used segments called traces would then greatly speed-up the execution of the application even though most of the code would still be interpreted.

Our journey will be very practical and hands-on, that's why in this section we are going to set up Android Compatibility Test Suite to test an existing device. We can't start working on our own Android implementation without knowing what we are going to support and test. To be able to run Android CTS, we will need:

There are a lot of files to download. In the meantime, we will set up our device.

We are testing an existing device, a smartphone, so we are already satisfying needs such as having a screen and we can move to device software configuration.

Tests should be executed on a clean device, so we should run a Factory Restore to erase all the data on the smartphone. Be sure of having a backup of your data if you are not using a development device. On Android 4.4 KitKat, you can reach the specific menu by navigating to Settings | Backup & reset | Factory data reset.

This will take a while—the device will shut down and the erasing process will start. The procedure will remove every single byte that is not part of the original Android system provided with your device, restoring all the settings and bringing the device to its original setup.

When the device restarts, we need to select English US language by navigating to Settings | Language & input | Language.

Now we need to turn on the Location: We need Wi-Fi and GPS and we need to provide some Internet connectivity. We need to disable any Screen Lock by navigating to Settings | Security | Screen Lock = 'None'.

We need a few settings from the Developer options menu. On a brand new installation of a vanilla Android system this menu is hidden. We can enable using the following steps:

Once the Developer options menu has been enabled, navigate back to the Settings screen. In the Developer options menu, we need to enable the following:

Before running any tests, it's important that the device is on a steady support to avoid triggering accelerometers and the gyroscope. The camera should be pointing to a focusable object. Don't press any buttons or keys during the tests—this could invalidate test results.

To properly run all the tests, we will need a few multimedia files on the device—Android CTS media files. First of all, let's connect the device to the USB. If this is the first time that you connect this device to this host PC, the device will display a dialog to authorize the connection—allow the connection:

Any Android device can communicate with a host PC using Android ADB. This key tool is covered in great detail in the next chapters, so, for now, we can start downloading the latest Android SDK from https://developer.android.com/studio/index.html#downloads, according to your platform. Once the download is completed, decompress the file and you will be provided with an android-sdk folder, containing a platform-tools folder, containing adb executable.

Back to our media files setup now:

The next screenshot shows the output of the whole procedure:

Everything is in place now and we can use cts-tradefed to run some test plans. Move to the Android CTS folder and run the following command to enter the cts console:

$ ./tools/cts-tradefed

The previous screenshot shows how cts-tradefed automatically identifies our connected device and gets ready to test.

CTS console provides a few useful commands:

Typically, the following test plans are available:

As our first approach to CTS, we are going to run CTS plan:

cts-tf > run cts --plan CTS --disable-reboot

The testing will start immediately and the console will be full of log messages in the blink of an eye, as shown in the following screenshot:

Now, grab some coffee or make some good tea: this will take a while. cts-tradefed will test everything that is possible to test with an automatic test. Luckily for us, there is a lot that can be tested in this way.

Time has passed, the tea has gone, and the tests are over. On a quad-core smartphone, such as a Motorola Moto G or Nexus 4, this could take up to 10 hours. Eventually, we have got some nice results to check out. According to the folder's path we are working in, we will have results in a .zip file in the cts folder:

$ unzip ~/bin/android-cts/repository/results/START_TIME.zip

Unzipping the file, we will find a testResult.xml file. Opening this file with a recent web browser (Firefox is working fine here) will show plenty of meaningful tables, with all kind of test and results. The next screenshot shows the initial Test Summary. We have information about the test duration, how many tests were executed, how many tests passed, and how many tests failed:

As you can see, even testing a certified smartphone, currently on the market, will produce some failed tests. This gives you an idea about the complexity of producing the perfect Android device.

The next screenshot shows Test Summary by Package, specifying the test results one test after the other. For brevity, we are showing just a subset of the results:

The previous Test Summary screenshot shows that 29 tests have failed. If we dig into the test result file, we see that detailed reports are also available. This further information is hugely useful to precisely spot the failed test, like the one in the following screenshot, and investigate the issue:

The test result file tries to play polite and, for brevity, does not show the full stacktrace of the failed test. To reach the stack trace of the failure, we must inspect the source code of testResult.xml. For every executed test, there is a corresponding <Test> tag. For those tests that failed, we will have a <StackTrace> tag too. That's what we are looking for!

As a final note, testResult.xml contains a huge section with all the information about the device it has been able to retrieve. It's a very large amount of data that, for brevity, we are not reporting here, not even as an example.

All we need to run CTS Verifier is an Android certified device and the appropriate CTS Verifier APK file. As we are testing an Android 4.4 device, we need to pay attention to downloading the proper CTS Verifier version. You can download the APK for your Android version and device architecture here: http://source.android.com/compatibility/downloads.html.

You just need to unzip the downloaded file and you will find a folder hierarchy and two .apk files. You can install CtsVerifier.apk using ADB:

$ adb install –r CtsVerifier.apk

The following screenshot shows the properly installed CTS Verified app and the initial screen:

As we know, CTS Verifier contains tests that need manual input to execute, evaluate, pass, or fail. Every test has its own Info screen that helps the tester to perform the test. As an example, we will run the Accelerometer Test, in the Sensors section.

Launching the test, we are welcomed by the info screen, as shown in the following screenshot:

The Info button explains how to perform the test and what to evaluate. As we move into the testing, we can evaluate if the accelerometer is working as expected. The following screenshot shows three different moments of the test:

As specified in the Info button, the arrow is always pointing in the same direction as the gravity: the sensor is working properly. We can consider that we have passed the test and click on the Pass button.

We have passed our first test. CTS Verifier provides dozens of tests and, one by one, we are going to run, verify, and pass them, in the long journey towards our first Android Certified Device.

When every test has been executed, we can save the result using the Save icon in the top-right corner of the initial screen, as shown in previous screenshot. The results will be saved on the device and a dialog box will show the precise path, as shown in the following screenshot:

Now, let's open a terminal and copy all the results from the phone to our computer:

$ adb pull /mnt/sdcard/ctsVerifierReports/ .
$ unzip *.zip

At this point, we have a ctsVerifierReport-[…].xml with all the info about our manually executed tests.

Congratulations! You have fully tested an Android device. Step 0 of our journey is complete.