Hello all and welcome to my first how-to guide
I began the process of learning about ROM about 4 months ago (so excuse this post if there are any inaccuracies and please feel free to correct me in the comments - I will absolutely update this post to ensure it has the best information)
Whilst I was trying to learn, I noticed there was a lack of information regarding how the actual build process works. Many roms will provide instructions allowing you to build your own unofficial version for one of their official devices, but very rarely do they inform you as to how you may do this for a device not officially supported.
This is what I shall try and explain here.
Building for a newer version of android is another challenge, so this guide will focus on building an unsupported rom from device sources that support the same version of android (e.g building Lineage oreo from AOSCP oreo sources etc)
Requirements
Set up your PC for building
Firstly, allocate Jack enough memory to complete the build process by running
And adding that line to your ~/.bashrc file
Also (optional) enable ccache by running
and adding that to your ~/.bashrc
If you choose to use ccache, also allocate a set amount of memory to use with
Where $ is a value of your choice between 50 and 100
First things first, we need to download the main source code for the target rom
Firstly you need to sync the sources from the manifest of your chosen rom. This will normally be called android, or manifest (or something similar) and will contain some xml files layed out like the example local manifest below
Find this repo and copy the link. Then move to the location you wish the entire android code to be stored, and then perform the following command
e.g. for lineage 15.1 it would be
Finally, run "repo sync" to download the source code. It is very large (approximately 30GB) so it will take a while. Should you need to cancel this, a simple CTRL+C will stop it, and it will continue from where it stopped next time you run repo sync
Now we need to understand which components we need to build a custom rom.
We need (anything inside the <> needs to be replaced with relevant information for your device)
To sync these, you should create a local manifest in the <android source>/.repo/local_manifests/ folder. Name it anything you like (make sure it's an xml file) and fill it out like so
After adding this manifest, re-run repo sync to pull the extra repos
Understanding the device tree.
Inside the device tree (model specific one if there are more than one) there will be a file with a naming scheme along the lines of <rom brand>.mk (e.g. lineage.mk). This is the starting file for your device and is detected when you begin a build for your device. (Pie roms are currently using AndroidProducts.mk as a placeholder containing a link to this file). It contains links to the common configuration of your device (phone, tablet etc) at the top, and also specifies the name of the product (normally <rom>_<device model>) which is part of the command used to build the device.
There will also be some build prop overrides - these contain information like the device name and the build fingerprint (used to verify to google what device you are - lots of devices leave this as the last stock fingerprint to pass google CTS)
In most device trees, there will also be a <rom>.dependencies file. This contains all the additional repos needed to build for your particular device. This file is parsed automatically if you use the official methods and use the breakfast command. If you do it manually, they must be added to a local manifest.
The <device model>.mk file is what defines what open source packages need to be built in the build. Devices either include everything in this file or they can link to a product folder in which every .mk file is included.
BoardConfig(Common).mk includes configuration options for the device, and often links to config files to inform the builder of certain flags that need to be applied for the build. Similarly to the <device model>.mk, this is often linked to a board folder containing configurations
The kernel
The kernel is a massive topic and one that I cannot explain in depth here. However, for rom building it is useful to know that the defconfigs used to build a kernel are located in kernel/<chipset/device model>/arch/<arm or arm64 depending on device>/configs and the one used is normally in the format <rom>_<device model>_defconfig (e.g my lineage one is lineageos_h815_defconfig). Should you wish to change the name, simply change the name and alter the defconfig name in the BoardConfig.mk for your particular device.
So...to the main part - how do you build a rom.
Essentially there are a few main commands that are spoken about
Then you need to go into the device tree and modify
"brunch <rom>_<device model>-userdebug"
This will hopefully begin the build and assuming everything is setup correctly, should continue through to finish building the rom of your choice
If you have any questions/issues with this process, I will be happy to answer to the best of my ability
Also, big thanks to the LineageOS guide for giving me a basis upon which to base this guide on
I began the process of learning about ROM about 4 months ago (so excuse this post if there are any inaccuracies and please feel free to correct me in the comments - I will absolutely update this post to ensure it has the best information)
Whilst I was trying to learn, I noticed there was a lack of information regarding how the actual build process works. Many roms will provide instructions allowing you to build your own unofficial version for one of their official devices, but very rarely do they inform you as to how you may do this for a device not officially supported.
This is what I shall try and explain here.
Building for a newer version of android is another challenge, so this guide will focus on building an unsupported rom from device sources that support the same version of android (e.g building Lineage oreo from AOSCP oreo sources etc)
Requirements
- A relatively fast PC with a least 4 cores (less may work but it will take a long time)
- At least 8GB ram
- A swap-file set up in the event that your ram is fully filled
- A significant amount of storage (each build can take 150-200GB)
Set up your PC for building
Firstly, allocate Jack enough memory to complete the build process by running
Code:
export ANDROID_JACK_VM_ARGS="-Dfile.encoding=UTF-8 -XX:+TieredCompilation -Xmx4G"Also (optional) enable ccache by running
Code:
export USE_CCACHE=1If you choose to use ccache, also allocate a set amount of memory to use with
Code:
ccache -M $GFirst things first, we need to download the main source code for the target rom
Firstly you need to sync the sources from the manifest of your chosen rom. This will normally be called android, or manifest (or something similar) and will contain some xml files layed out like the example local manifest below
Find this repo and copy the link. Then move to the location you wish the entire android code to be stored, and then perform the following command
Code:
repo init -u <url of manifest repo>.git -b <branch you want to build>
Code:
repo init -u https://github.com/LineageOS/android.git -b lineage-15.1Finally, run "repo sync" to download the source code. It is very large (approximately 30GB) so it will take a while. Should you need to cancel this, a simple CTRL+C will stop it, and it will continue from where it stopped next time you run repo sync
Now we need to understand which components we need to build a custom rom.
We need (anything inside the <> needs to be replaced with relevant information for your device)
- A device tree. This contains all the information needed to configure the rom build to your device's needs. Often this comes as more than one repo (one for your exact device and one for the general model - e.g. for my LG G4 H815, we have the h815 repo and the g4-common repo). The format for these repos is generally android_device_<vendor>_<device model>
- A kernel. This contains all the drivers and more needed for your device to be able to run Android. Often these are named using your device's chipset name and follow the format android_kernel_<vendor>_<chipset>, although occasionally they can use your model name instead of the chipset.
- Proprietary blobs. These are the closed source blobs that come bundled in your OEM software and contain the non-OSS (open source software) drivers for your device. They normally come in a repo labeled proprietary_vendor_<vendor> which normally contains blobs for all the devices released by that vendor (that are supported).
- Any other repos specified by the dependencies file (more on that later)
To sync these, you should create a local manifest in the <android source>/.repo/local_manifests/ folder. Name it anything you like (make sure it's an xml file) and fill it out like so
Code:
<manifest>
<remote name="<your chosen name for this url>"
fetch="<url to your git organisation>"
revision="<branch if different to the one used in repo init (otherwise, miss out revision)>"
<project name="<name of repo inside git org>" path="<destination of the repo>" remote="<remote name chosen earlier>" revision="<revision if different to one specified above>" />
</manifest>After adding this manifest, re-run repo sync to pull the extra repos
Understanding the device tree.
Inside the device tree (model specific one if there are more than one) there will be a file with a naming scheme along the lines of <rom brand>.mk (e.g. lineage.mk). This is the starting file for your device and is detected when you begin a build for your device. (Pie roms are currently using AndroidProducts.mk as a placeholder containing a link to this file). It contains links to the common configuration of your device (phone, tablet etc) at the top, and also specifies the name of the product (normally <rom>_<device model>) which is part of the command used to build the device.
There will also be some build prop overrides - these contain information like the device name and the build fingerprint (used to verify to google what device you are - lots of devices leave this as the last stock fingerprint to pass google CTS)
In most device trees, there will also be a <rom>.dependencies file. This contains all the additional repos needed to build for your particular device. This file is parsed automatically if you use the official methods and use the breakfast command. If you do it manually, they must be added to a local manifest.
The <device model>.mk file is what defines what open source packages need to be built in the build. Devices either include everything in this file or they can link to a product folder in which every .mk file is included.
BoardConfig(Common).mk includes configuration options for the device, and often links to config files to inform the builder of certain flags that need to be applied for the build. Similarly to the <device model>.mk, this is often linked to a board folder containing configurations
The kernel
The kernel is a massive topic and one that I cannot explain in depth here. However, for rom building it is useful to know that the defconfigs used to build a kernel are located in kernel/<chipset/device model>/arch/<arm or arm64 depending on device>/configs and the one used is normally in the format <rom>_<device model>_defconfig (e.g my lineage one is lineageos_h815_defconfig). Should you wish to change the name, simply change the name and alter the defconfig name in the BoardConfig.mk for your particular device.
So...to the main part - how do you build a rom.
Essentially there are a few main commands that are spoken about
- "source build/envsetup.sh". This runs the builder script and loads all the custom commands.
- "breakfast". This simply pulls the device specific code from the official repos. You do not need this if you are building unofficially
- "brunch". This effectively performs breakfast, but assuming everything is synced correctly, it will finish without an issue. Then it will go on to begin the build. Normally brunch is run as brunch <rom name>_<device model>-userdebug (or eng if you are developing). User is used for OEM releases but most roms use userdebug as it is slightly more relaxed on conditions
Then you need to go into the device tree and modify
- The <rom>.mk file to now be renamed to your new rom.
- You need to enter that file and modify any stuff relating to your old ROM look for your new rom instead (device type configurations are normally the main one here).
- You need to remove any stuff inside your device tree relating to features not in your new rom.
"brunch <rom>_<device model>-userdebug"
This will hopefully begin the build and assuming everything is setup correctly, should continue through to finish building the rom of your choice
If you have any questions/issues with this process, I will be happy to answer to the best of my ability
Also, big thanks to the LineageOS guide for giving me a basis upon which to base this guide on
