Build LineageOS for your phone

LineageOS: Building your ROM is one of the most rewarding experiences you can have. Imagine having your own version of Android on your own phone!


Hopefully this guide will help you boot into a standard Android device, unlock the bootloader (if necessary), and then download the necessary tools and latest source code for LineageOS (based on Google’s Android OS) for your device. You can use them to create LineageOS and LineageOS recovery images from source code and then install both on your device.


It is difficult to say how much experience it will take to follow these instructions. While this guide is certainly not for the very, very, very uninitiated, these steps shouldn’t require a PhD in software development either. Some readers will have no difficulty and will navigate the steps easily. Others may struggle with the most basic operation. Because people’s experiences, backgrounds, and intuitions vary, it may be a good idea to read carefully to see if you’re comfortable or freaking out.


Remember that you take every risk to try, but you will reap the rewards! Booting into a new OS that you’ve baked at home is quite satisfying :). And once you’re an Android construction ninja, you no longer have to wait for anyone to do your “nightly” builds for you. You have the ability to create a complete operating system from code to running device whenever you want.

What you need?

  1. Rooted Android Phone
  2. A relatively new 64-bit computer (Linux, macOS, or Windows) with a decent amount of RAM and about 200GB of free space (more if you enable CCache or Build for multiple devices). The less RAM you have, the longer it takes to compile. Aim for 16GB of RAM or more, enabling ZRAM can help. Using SSDs leads to considerably faster build times than conventional hard drives.
  3. A decent internet connection and reliable power.
  4. Some familiarity with basic Android functionality and terminology. It can be helpful to know some basic command line concepts like cd, which means “change directory”, the concept of directory hierarchies and that they are separated by / in Linux, etc

Building LineageOS

1. Installing the required tools

In this example, I am using Arch Linux to build LineageOS for my Samsung Galaxy Note 10+.

We start with installing all the necessary programs to compile our build.

yay -S multilib-devel ccache maven gradle gcc repo gnupg gperf sdl wxgtk2 squashfs-tools curl ncurses zlib schedtool perl-switch zip unzip libxslt bc rsync ccache lib32-zlib lib32-ncurses lib32-readline ncurses5-compat-libs lib32-ncurses5-compat-libs lib32-gcc-libs gnupg flex bison gperf sdl wxgtk2 squashfs-tools curl ncurses zlib schedtool perl-switch libxslt python2-virtualenv bc rsync lib32-zlib lib32-ncurses lib32-readline xml2 lzop pngcrush imagemagick
 android-tools heimdall

2. Set up directories

You’ll need to set up lineage directory in your build environment.

mkdir -p ~/android/lineage

3. Configure git

Since Repo requires you to sign in to sync Android, run the following commands to configure your Git identity:

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

4. Turning on caching for faster builds

Use ccache if you want to speed up subsequent builds by running:

export USE_CCACHE=1
export CCACHE_EXEC=/usr/bin/ccache

Then specify the maximum amount of space you want the cache to use by typing:

ccache -M 50G

where 50G corresponds to 50GB of cache. This must be done once.

Anywhere from 25GB to 100GB, build speed increases significantly (for example, a typical build time can be reduced from 1 hour to 20 minutes).

If you are only compiling for one device, 25GB-50GB is fine. If you plan to compile for multiple devices that do not use the same kernel source, consider using 75GB-100GB. This space will be used permanently on your disk, so keep this in mind.

5. Initialize the LineageOS repo

For my Galaxy Note 10+, only LineageOS 18.1(Android 11) is built officially so we will go with that.

We will initialize repo for that with this command:

cd ~/android/lineage
repo init -u https://github.com/LineageOS/android.git -b lineage-18.1

6. Sync the LineageOS sources

To start downloading the source code to your computer, enter:

repo sync
NOTE: This may take a while depending on your internet speed. Go  have a beer / coffee / tea / nap in the meantime!
TIP: The repo sync command is used to update the latest source code from LineageOS and Google. Remember it, as you may want to do it every few days to keep your code base fresh and up-to-date. But note, if you make any changes, running repo sync may wipe them away!

7. Prepare the device-specific code

After downloading the source code, make sure you are in the source code root directory (cd ~/android /lineage), then enter

source build/envsetup.sh
breakfast d2s

This will download the device specific and kernel configuration for your device.

IMPORTANT: Some devices require a provider directory to be completed before breakfast is successful. If you get an error  about provider makefiles here, go to Extracting proprietary blobs. The first instance of breakfast should be a success, and when it is finished you can re-run the breakfast.

8. Extract proprietary blobs

NOTE: This step requires  a device that is already running the latest version of LineageOS depending on the branch you want to create for. If you don't have access to such a device, see Extracting proprietary blobs from an installable zip file.

Now make sure your Galaxy Note 10+ is connected to your computer via USB cable, ADB and Root are activated and it is in the ~/android/lineage/device/samsung/d2s folder. Then run the Extractfiles.sh script:

./extract-files.sh

9. Start the build

Time to build! Now enter:

croot
brunch bacon

Depending on your PC hardware, the build should take 1-10 hours.

10. Installing the LineageOS build

Assuming the build completed without errors (it will be obvious when it completes), type the following in the Terminal window where the build ran:

cd $OUT

There you will find all the files that have been created. The two most interesting files are:

  1. recovery.img, the recovery image to install LineageOS
  2. lineage-18.1-20211017-UNOFFICIAL-d2s.zip, the ROM zip itself

What’s next

You did it ! Welcome to the elite home builders club. You have rebuilt your operating system from scratch. You are the master of your domain… and I hope you learned a little along the way and had fun too.

1 thought on “Build LineageOS for your phone”

Leave a Comment