So, I have been an Android developer since 2009 (HTC dream), and have been actively "consuming" XDA, custom ROMs and other tweaks. Surprisingly, never tried to build my own ROM from scratch.
Recently, something made me want to build the ROM, so that I can make some changes to the way SystemUI behaves (specifically putting some app shortcuts to my Pixel phone(s), like camera etc. which are now removed in Android 10). So, after a week's struggle I got to where I wanted to reach. (90% time spent in getting the first successful flash. 1% feature development. 9% feature polishing).
Here is my guide to all beginners. (It is pretty simple, if you know the steps).
System setup
I have always been a Windows user (and I love my Surface(s)), but you cannot build Android on Windows machines (as clearly called out in source.android.com). I still tried to install Ubuntu shell from Microsoft store, and build (Spoiler alert: Does not work).
Next is Mac. Android can be built in Mac, I got it build in Mac. But, it is not easy. Especially with setting up the environment, having the right version of MacOS (doesn't work on Catalina yet). And also, challenges with filesystem format (Android building only works on case sensitive file system, so you have to create such a partition). Android building needs at least 160GB of disk space (so unless you are super rich and have 512GB+ Macbook with top specs, it is going to be hard).
My choice machine hence became, my two desktops (i7 4 core, 16GB, 1TB SSD, Ubuntu 18.04 and Xeon 12 core, 32GB, 512GB disk, with Ubuntu 18.04).
There is a reason why I specifically talk about these two machines. To build Android fast (cold clean build in less than 4 hours), you need
Setting up your Ubuntu machine. {ETA 30 mins}
Android has official (and clearly laid out) steps here.
But for Ubuntu these are pretty much the steps.
And the guide doesn't mention this, but you need Python2.7, so get this.
Also install adb.
If you have come till here, you're ready to build for different devices.
Getting the code ready to build {ETA 5 hours - 1 day}
Most of this is also mentioned in the AOSP official website, but some stuff are tricky, I will try to highlight those steps here.
We are going to build the ROM for Pixel 3 (Android 10 - QP1A.191105.003 )
Download and explode the code {ETA 2-3 hours, depending on internet speed}
Here we are talking about downloading at least 20GB of code (text heavy content) over the internet. Going to be excruciatingly slow.
Also, we will be downloading code for specific device model, so if you want to do it for a newer model, you will have to go through the grind again.
Although, technically it might be possible to have the same folder contain code for multiple devices, it is too risky IMO, something goes wrong, you lose everything.
Recommended folder structure would be
Setting up repo.
Repo is a tool that Google uses to checkout and manage the AOSP code in your local machine. Once you download the codebase, you can use the command to resync, update, code base.
You should persist this folder in your PATH variable all the times.
This sets up repo in your machine.
One final step before you actually start the long download, setup your git details.
Now download the code. Like I previously suggested I would do this.
Now, let's start getting the code home.
Here we have done a bunch of things.
This command is going to take a while to download over 20GB of code. In the meanwhile, let's see what we did here.
. Note that I have had situations where I put a very high value for n (higher than my cores as well), and eventually ran my JVM out of RAM to run the command (in parallel). So, the trade off here is to restrict it to the core number.
***Key step: Download radio drivers.***
Most tutorials miss this or mention it very subtly. But, without this step the ROM you flash won't boot to the home screen (you will be in the boot loop).
Go to the driver binaries page, and download the right zip files for the Android build version (android-10.0.0_r10) and device (Pixel 3) you chose earlier in the repo command.
You will be downloading two zip files (one vendor image zip and one radio drivers zip), both zips will have on shell script file each (.sh), just put those two files in your repo folder (~aosp/pixel3) and run the scripts. It will download the required proprietary files (after asking you to accept the terms). Do not miss this step.. I lost 3 days trying to find the reason for my ROM not booting up, this was it.
Let's build our code
Now things are more definitive.
This command basically sets up your environment, adding necessary commands to path etc.
You can read more about this command here.
Basically this sets up the right parameters to build for your specific model. The param can derived based on aosp_[device code]-[userdebug | eng | user].
Once you have run the above two commands, you can *finally* build your codebase.
m basically makes and builds the whole codebase.
refers to the defaults target configuration (optional). -jN is to specify parallelism (equal to number of cores you have).
This command could take anywhere between 4-12 hours for the first run. But, if you followed all steps above, you should have a green message in the end saying this
Flashing your phone
Now, you're 50% safe when your build has finished successfully. Now, next 50% depends if you're able to flash it and get the phone booting.
This part most of you should know, so I am keeping it brief.
Enter fastboot
Unlock your bootloader
Flash your Build
From the root folder of your repository (~/aosp/pixel3)
In a few minutes your device should be booting to the freshing baked ROM that you made.
What next?
This has been pretty much my journey so far with AOSP. I am comfortable making changes to modules and building them again.
Recently, something made me want to build the ROM, so that I can make some changes to the way SystemUI behaves (specifically putting some app shortcuts to my Pixel phone(s), like camera etc. which are now removed in Android 10). So, after a week's struggle I got to where I wanted to reach. (90% time spent in getting the first successful flash. 1% feature development. 9% feature polishing).
Here is my guide to all beginners. (It is pretty simple, if you know the steps).
System setup
I have always been a Windows user (and I love my Surface(s)), but you cannot build Android on Windows machines (as clearly called out in source.android.com). I still tried to install Ubuntu shell from Microsoft store, and build (Spoiler alert: Does not work).
Next is Mac. Android can be built in Mac, I got it build in Mac. But, it is not easy. Especially with setting up the environment, having the right version of MacOS (doesn't work on Catalina yet). And also, challenges with filesystem format (Android building only works on case sensitive file system, so you have to create such a partition). Android building needs at least 160GB of disk space (so unless you are super rich and have 512GB+ Macbook with top specs, it is going to be hard).
My choice machine hence became, my two desktops (i7 4 core, 16GB, 1TB SSD, Ubuntu 18.04 and Xeon 12 core, 32GB, 512GB disk, with Ubuntu 18.04).
There is a reason why I specifically talk about these two machines. To build Android fast (cold clean build in less than 4 hours), you need
- Fast processors, and more cores
- Lots of RAM
- A SSD disk (with 200GB space)
Setting up your Ubuntu machine. {ETA 30 mins}
Android has official (and clearly laid out) steps here.
But for Ubuntu these are pretty much the steps.
Code:
$sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev libgl1-mesa-dev libxml2-utils xsltproc unzip
Code:
# refreshing the repositories
sudo apt update
# its wise to keep the system up to date!
# you can skip the following line if you not
# want to update all your software
sudo apt upgrade
# installing python 2.7 and pip for it
sudo apt install python2.7 python-pip
# installing python-pip for 3.6
sudo apt install python3-pip
Code:
sudo apt install android-tools-adb android-tools-fastboot
Getting the code ready to build {ETA 5 hours - 1 day}
Most of this is also mentioned in the AOSP official website, but some stuff are tricky, I will try to highlight those steps here.
We are going to build the ROM for Pixel 3 (Android 10 - QP1A.191105.003 )
Download and explode the code {ETA 2-3 hours, depending on internet speed}
Here we are talking about downloading at least 20GB of code (text heavy content) over the internet. Going to be excruciatingly slow.
Also, we will be downloading code for specific device model, so if you want to do it for a newer model, you will have to go through the grind again.
Although, technically it might be possible to have the same folder contain code for multiple devices, it is too risky IMO, something goes wrong, you lose everything.
Recommended folder structure would be
With each folder containing over 150GB of contents (after downloading, building etc), so in practical sense, n could be only 3-4 at max.
Setting up repo.
Repo is a tool that Google uses to checkout and manage the AOSP code in your local machine. Once you download the codebase, you can use the command to resync, update, code base.
Code:
mkdir ~/bin
PATH=~/bin:$PATH
Code:
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
One final step before you actually start the long download, setup your git details.
Code:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Now download the code. Like I previously suggested I would do this.
Code:
mkdir ~/aosp
cd ~/aosp
mkdir pixel3
cd pixel3
Now, let's start getting the code home.
Code:
repo init -u https://android.googlesource.com/platform/manifest -b android-10.0.0_r10 --depth=1
- We have chosen a particular Android build tag to download (branch). You can follow the link to choose which branch you want to checkout, based on your test phone and Android version you want to build.
- We have asked to only download the latest version of the branch and not all of the branch (--depth), this considerably reduces our download time.
Code:
repo sync -qc -j4
- -q Asks the download to be silent (which means it will show just overall progress)
- -c Makes sure we are only downloading current branch
- -j[x] This the tricky one. Let's talk about this.
Code:
nproc --all
***Key step: Download radio drivers.***
Most tutorials miss this or mention it very subtly. But, without this step the ROM you flash won't boot to the home screen (you will be in the boot loop).
Go to the driver binaries page, and download the right zip files for the Android build version (android-10.0.0_r10) and device (Pixel 3) you chose earlier in the repo command.
You will be downloading two zip files (one vendor image zip and one radio drivers zip), both zips will have on shell script file each (.sh), just put those two files in your repo folder (~aosp/pixel3) and run the scripts. It will download the required proprietary files (after asking you to accept the terms). Do not miss this step.. I lost 3 days trying to find the reason for my ROM not booting up, this was it.
Let's build our code
Now things are more definitive.
Code:
source build/envsetup.sh
Code:
lunch aosp_blueline-userdebug
Basically this sets up the right parameters to build for your specific model. The param can derived based on aosp_[device code]-[userdebug | eng | user].
Once you have run the above two commands, you can *finally* build your codebase.
Code:
m droid -j4
Code:
droid
This command could take anywhere between 4-12 hours for the first run. But, if you followed all steps above, you should have a green message in the end saying this
Code:
[COLOR="SeaGreen"]#### build completed successfully (2:03:04 (hh:mm:ss)) ####[/COLOR]
Flashing your phone
Now, you're 50% safe when your build has finished successfully. Now, next 50% depends if you're able to flash it and get the phone booting.
This part most of you should know, so I am keeping it brief.
Enter fastboot
Code:
adb reboot bootloader
Unlock your bootloader
Code:
fastboot flashing unlock
Flash your Build
From the root folder of your repository (~/aosp/pixel3)
Code:
fastboot flashall -w
In a few minutes your device should be booting to the freshing baked ROM that you made.
What next?
- You can just repeat
Code:
m droid -j4
- You can also go to a specific module folder and execute
Code:
mm
- You can use adb sync to update specific modules without flashing again (this never worked for me, always bricked my device)
- Use *fastboot flashall* without [-w] flag to flash over existing ROM without losing user data.
- You can clean up the whole builds and rebuild everything from scratch. Run
Code:
make clobber
Code:m
- You could face adb issues (device not detected) in Ubuntu. I am not going into details of how to fix that
This has been pretty much my journey so far with AOSP. I am comfortable making changes to modules and building them again.