AOSP from the trenches

March 10, 2021

When it comes to Android development we can think of two different ecosystems that are tightly interrelated: app development and platform development.

This differentiation between app and platform development is a direct consequence of the existing Android architecture.

Android architecture

Platform development has to do with the development of the Android OS itself. This task is commonly done by OEMs or very specific developers, mostly coming from traditional embedded Linux scenarios.

App development, on the other hand, refers to the design and implementation of specific functionality aiming the Android OS as the distribution platform. This task is pretty much what the vast majority of so called Android developers work on a daily basis.

The differences between app and platform development are quite substantial when it comes to working processes. Being aware of them is crucial for understanding the kind of expertise you will need and therefore for the success of your project.

In this post I want to share my personal experience after working on the AOSP for a while. Given that I had some previous experience as an Android app developer, the following insights could be quite useful for other devs willing to descend to the dungeons of the Android ecosystem.

How I got started

First things first, the reason why I decided to give AOSP development a try is because I only heard bad things about it. At that point, fellow app developers used to complain about the platform being based on Java instead of Kotlin. Others complained about IDE support as well. In addition to that, people didn’t really like the fact of having to use a Linux machine instead of their beloved MacBook Pro.

But you know, as Seth Godin says:

If it scares you, it might be a good thing to try.

So, out of curiosity (or masochism) I wanted to check if the pain was really just because of the previous complains.

Personal insights

Far from reality, I think I have identified other more serious issues that could be summarise as follows.

Lack of documentation

In my opinion one of the things that explains the fear to work on the AOSP is the lack of official documentation. I know Google has some docs around about how to download the AOSP and do contributions on Gerrit. Recently, they even published a codelab for getting started on the platform. However, I believe all this is quite limited and insufficient for getting devs interested about working on this topic. Somehow, I have the feeling that Google knows this, and in the recent years they have put some effort on improving the situation by publishing tools like or Adding to this, Andrea Falcone also gave some public talks about how to get started on creating your first AOSP contribution.

Things are a bit different when it comes to Android Automotive (the Android form factor for cars). It is clear that Google wants to seduce automotive OEMs to jump straight into Android and sell them the Google Automotive Services (GAS). Thanks to this, I found the documentation about customizing and extending the AOSP in the automotive sector much better than what you would find for creating your own Phone ROM.

The Android Automotive documentation is obviously not at the same level Google uses when describing for example AndroidX libs, but still you can get very good insights about where to look in the code later.

Docs about the project structure and the repository organization would be definitely very useful. In this regard, I found the book Embedded Android by Karim Yaghmour very educating. It was written in 2013, but most of what it states is still quite valid.


This is probably one of the issues that will make newbie AOSP devs quit early. There are several verticals here that are worth mentioning:

  • Dealing with Repo. Even though this is a script on top of Git to deal with the massive amount of individual repos in the AOSP, there is still some complexity added and devs coming from the app world need to get used to it.

  • Dealing with Gerrit. Android app developers are mostly used to solutions like Github, where you push your code and create a PR with your changes. In Gerrit, things are different. There aren’t PRs, but Change Lists (CLs in short) attached to the same commit. For me personally, this was the first obstacle. Specially, I needed to learn about how to push my changes and how to solve conflicts.

  • Hardware. Downloading the AOSP is quite demanding in time. I even remember having issues with the WiFi, so I had to use a wire instead. Still more painful is when you need to wait long periods of time for building the AOSP. Even though, the first build is obviously the most time consuming, waiting for incremental builds in a consumer laptop (~32GB RAM) translates in a reasonable break. I know that Google and probably OEMs have powerful workstations for devs working on the AOSP. However, if you aren’t lucky and you need to work on a normal consumer laptop, you better have good patience.

  • IDE support. I am personally still struggling with this one, so probably this issue and the previous one are the worst pain points I experienced so far in AOSP-land. I used to have IntelliJ configured just like it is described in some of the docs available in the AOSP. However, dealing with the indexing nightmare regularly and the fact that it doesn’t support remote working mode (for example for working via ssh or within a Docker container) made me switch to VS Code. This one is not much better when it comes to IDE autocompletion or maybe I still didn’t figure out a right way of configuring the workspace. However, I find VS Code lighter and faster than IntelliJ. It also supports the remote mode, which is a great advantage if you have your source code in a special build machine and just use your laptop as a client.

  • Libraries. App developers can usually benefit from the latest libraries by just changing the Gradle coordinates, however the platform includes some bundled versions of those libraries which might be old depending on the AOSP branch you used. Updating these bundled libraries might have side effects in the AOSP code.

Strong upstream dependencies

In software engineering like in investing, I have seen two different kinds of profiles, i.e., those who go short-term and those who go long-term. By analogy, engineers in the first group try to solve the problem at hand as fast as possible and move to the next one, without maybe analyzing the impact of their decision in the overall architecture with the time. Engineers in the second group usually take a longer time to evaluate and understand the code that need to be modified, with an eye on future maintainability.

I personally believe that the second profile is better suited to work on the AOSP considering the strong upstream dependencies to Google.

One of my biggest pain points in this sense has been the migration from one Android version to the next. Even though Google recommends to always rely on overlays for customizing the platform, code changes are still quite common. I know that Google favors inheritance instead of modifying the original code, but still this doesn’t avoid the need for big refactorings when the interfaces change. I have seen that this is a very common problem in system apps that are included in the platform, like the system ui or the launcher.


Working with the AOSP is harder than developing Android apps, which doesn’t mean the second is trivial either. Getting the right mindset and being eager to research and learn are crucial if you want to start on this field.

I hope all the issues I mentioned previously are not scaring you, but rather giving you enough courage and curiosity to check out the AOSP. At last this is just my personal experience, so don’t take it as set in stone.

If you are interested in giving AOSP a try for the first time, I wrote this tutorial together with the team at Building the Android Open Source Project

Get in touch if you have some other insights worth sharing.

Meanwhile, strength and honor!