Porting AOSP ROMs using Source Code

This will be a rough guide to help people port their favourite AOSP ROMs using the open source Android code, thereby enabling your device to run full ROMs unofficially, built from source. This means you can be running the latest version of the ROM simply by updating your source code and re-building.

Some of you maybe thinking “Wait don’t I need to know how to program to do this?” Being able to program is not necessarily required (although if you are interested in learning, check out the Helpful Links page) – more important are some hours to research the use of git, looking at some existing ROM repository setups like Cyanogenmod and AOKP, and getting a feel as to how a new device is supported.

This guide is for the people who want an AOSProm that is not currently provided for by a developer. For example your device might have Cyanogenmod already available, however you may wish to run AOKP, because it allows more customisation without the need to decompile and recompile apks etc.

***Disclaimer – Please check if permission is needed before kanging ***
If the rom that’s been ported is already available for the device and it’s already built from source not a rom – zip port then please try to add some unique features as there will be not much point in porting if there it’s any additional value to what is already available and it will just create a massive mess in your device development section. However, what this allows us as extreme enthusiasts is to reduce the workload for our developers while, giving something back to the community in addition to showing your appreciation to your device developer/s or power members.

Ok now to the tools needed :
You will need a PC if not you wouldn’t be reading this.
A Github account created with Git installed on your system and if possible some knowledge on git commands or time to research on them if not known.
For a head start on some commands please refer to the excellent guide on XDA by forum moderator eagleeyetom called [Guide] How to use Github and can be found by searching on xda developers website.
Some experience with terminal if using Linux
A device and vendor tree for your device
Your AOSProm of choice
Some hours of your time to work on this

This can be done on any platform that has git supported so windows, linux or mac but you will need linux to build android. In this guide I shall be using linux as it’s my preferred system and my distribution of choice at the moment Zorin OS 6 as I have found it to be the fastest and least resource hungry OS for me so far. So all commands in this guide will be using terminal.

For a guide on how to setup an android environment please refer to the guide on how to compile from source found on XDA-U

Throughout this guide I shall refer to device repo or device tree they mean the same thing. It’s just different ways I like to refer to them. It means the device repository.

Ok now to the tutorial :

Once git is setup we now want to look for the device’s repo …. If CM or another AOSProm is already available for your device then look for the github page for it by either searching on google or looking for your developer’s github page.

Here is how one looks :

As shown above the name setup is usually something like android_device_manufacturer_device or device_manufacturer_device. This can be used to help find the device tree using a search engine.

Ok once we find that we are going to fork the device repo so we can edit it to work with the AOSProm we are porting. As different roms use different configurations for their setup.

You can fork a project by clicking the fork button on the top right of the github page like so -
Once that’s done we’re going to need to fork your device’s proprietary vendor files. Cyanogenmod usually names their repos differently to some other teams so when searching for for a vendor repo for your device on Cyanogenmod it will be properietary_vendor_manufacturer, whereas others teams might just name it vendor_manufacturer.
Now once that’s done go to the github page of the AOSProm that is being ported and also fork their vendor setup repo so we can add the device to the setup so it can be called later on when we run the . build/envsetup or source build/envsetup.sh command this allows us to compile the rom after when we have selected our target device.

Once that’s done we are now going to start cloning these repos onto your local machine so we can modify some files to add our device. Best way to do this is create a new directory where all the work is going to be done in your home folder and cd into that directory. So mkdir directory(name it whatever you want), then cd directory. So for example if the name of the new directory was named github then the commands will be mkdir github, cd github. Once that’s done navigate to your account page on github and clone the repos we forked earlier. To do this we look for the ssh url on each repo page then we copy it. Then we type git clone and paste the url and click enter on the keyboard. This will clone the repo from your github(remote) to your local(system) allowing you to make changes to the files then upload them back to github.

So when cloning is done the device, vendor tree and the rom’s vendor tree should be present. Now this is the part where we really need to switch on our brains. First go back to the github page of the rom’s vendor tree and click on commits now look through them and find one where a new device is added. Copy this new configuration and apply it to your device by either modifying existing files or creating new ones. To ensure no conflicts arise when envsetup.sh is ran try to make the product_name different but ensure the product_device and product_model are the same as the one in the device tree.

Once the device has been added what is left is to push the changes to your remote(github) by using the git push command. This can be done by first using git add -A which lets all the new files and changes to be tracked. Then we use the git commit -am ” message “. E.g git commit -am “Add defy to the mix”. This adds a commit message which will appear on our remote branch with the new changes. Finally we use git push origin <branch name> to push the changes to our remote. E.g git push origin jellybean

Additionally look at some device setups on the rom’s github page and see if any changes are needed to make your device configuration compatible with the rom’s vendor tree. Usually none are need but it depends on how the person or team has setup their vendor tree.

Now this part is the longest and can be the most annoying process as we need to find the changes that are necessary to ensure the device boots when the rom has been compiled. This can be done in a number of ways but the best will be to kindly ask one of your device rom developer/s or member/s that have created the AOSProm device tree that is been used to port the rom you’re porting. Depending on what type of device you have if it has a locked or unlocked bootloader then changes will have to be cherry-picked or merged in different places such as frameworks_base, system_core, etc.
Refer back to the git guide in the requirements on how to use these commands like git cherry-pick, git merge. I can’t really guide you here as each device is different so this is the part where you need your brain at maximum capacity.

Here you will be cloning all the repos where changes need to happen from the rom’s github page you’re porting. Then cherry-picking and merging these changes. Remember to first add the remote with git remote add <name> before you start cherry-picking so the SHA number can be found.

Also remember to add your repos to the platform_mainfest or android(if it’s a CM based rom) Additionally, check your device maintainer’s setup to see if any additional repos any needed.
Once that has been resolved push the changes to your remote and make a new directory in your home directory then, repo init and repo sync, chose your device target with the lunch command and finally use mka to compile the rom. Pat yourself if it compile without errors.

Good Luck and Enjoy your hard work if it’s successful. However, if the unfortunate happens then report any issues here and me and the others members of XDA will try help out as this is XDA after all where we help each other, learn and expand our knowledge of Android.

For an example of what can be achieved look at some of my work and thank you for your time.

Definitioner

AOSP

The Android Open Source Project is the Google project which makes available the source code for Android, allowing anyone to build it for themselves. All Android ROMs are ultimately based on AOSP at some point in their development.

Repo

Repo is used within the Android source code to manage multiple git repositories. It can synchronise them all, and carry out other actions such as setting up your source tree, without having to manually define each repository needing downloaded

Git

The Git version control system is a distributed version control system, which tracks the changes made to some source code. Android and the Linux kernel make heavy use of git.
Git lets multiple authors collaborate on code, and share their changes quickly and easily.

ROM

ROM is literally “read-only memory” but its usage has changed over time. Today ROM can refer to the non-volatile area of a device’s flash memory on which read-only data resides or the packed image to be written to that flash area.

bootloader

The bootloader is firmware on the phone which runs on every startup. Sometimes it may be desirable to change the version of the bootloader, or to load a different bootloader entirely to enable different features or a completely different OS. The current version of the bootloader can be viewed by entering bootloader mode, the process of which is different for each and every device or manufacturer.