Introduction: Unlocking Your Android’s Full Potential with LineageOS 21

Welcome to the ultimate guide for setting up your development environment to build LineageOS 21 from source on Ubuntu. LineageOS, the most popular custom Android ROM, offers a pure, enhanced Android experience, free from OEM bloatware and with a focus on privacy, performance, and community-driven features. Building it yourself gives you unparalleled control over your device’s software, from customizing the kernel to including specific features or security patches.

This expert-level tutorial is designed for developers, enthusiasts, and anyone eager to dive deep into Android’s open-source ecosystem. We’ll cover every step, from preparing your Ubuntu machine to successfully compiling your first LineageOS 21 (Android 14) build. Get ready to transform your device into a truly personal Android experience.

Why Build LineageOS from Source?

• Full Customization: Modify the OS to your exact specifications.
• Latest Security: Apply the very latest Android security patches directly.
• Deeper Understanding: Gain invaluable insight into the Android Open Source Project (AOSP) and custom ROM development.
• Support for Older Devices: Breathe new life into devices no longer supported by their manufacturers.

Prerequisites: Preparing Your Ubuntu Workstation

Before embarking on this journey, ensure your Ubuntu system meets the necessary requirements for a smooth and efficient build process. LineageOS 21 (based on Android 14) is a demanding build, requiring substantial resources.

Hardware Recommendations:

• Operating System: Ubuntu 22.04 LTS (Jammy Jellyfish) is highly recommended. While other distributions might work, Ubuntu offers the most straightforward setup.
• Processor: A modern multi-core CPU (Intel i7/i9 or AMD Ryzen 7/9) is ideal. The more cores, the faster your compilation will be.
• RAM: Minimum 16GB, but 32GB or more is strongly recommended for optimal performance, especially when using `ccache`.
• Storage: At least 250GB of free SSD space is an absolute must. NVMe SSDs will significantly speed up compile times compared to SATA SSDs. Hard Disk Drives (HDDs) are not suitable for building Android.
• Internet Connection: A fast and stable internet connection is crucial for downloading the several hundred gigabytes of source code.

Setting Up Essential Packages and Tools

First, update your system and install all necessary build dependencies. Open a terminal (Ctrl+Alt+T) and execute the following commands:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git-core gnupg flex bison build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libsdl1.2-dev libxml2 libxml2-utils libxslt1-dev rsync pngcrush schedtool libncurses5 libncurses5-dev libncursesw5-dev x11proto-core-dev libx11-dev libgl1-mesa-dev libglu1-mesa-dev libglapi-mesa-dev libtinfo5 python3 python3-pip openjdk-17-jdk
sudo apt install -y android-sdk-platform-tools-common # For adb/fastboot udev rules

Confirm Java 17 is the default JDK:

java -version
javac -version

If not, you may need to set it:

sudo update-alternatives --config java
sudo update-alternatives --config javac

Configuring `repo` and Git

The `repo` tool, built on Git, manages the many Git repositories that make up the Android source tree. You’ll need to set it up and configure your Git identity.

1. Install `repo`:

   mkdir -p ~/bin
   PATH=~/bin:$PATH
   curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
   chmod a+x ~/bin/repo

2. Configure Git identity:

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

Initializing `ccache` (Optional but Highly Recommended)

`ccache` (compiler cache) significantly speeds up subsequent builds by caching compilation results. Given the size of the Android source, this is almost mandatory.

1. Create a `ccache` directory:

   mkdir -p ~/android/ccache

2. Set `ccache` environment variables and size limit:

   Add these lines to your `~/.bashrc` or `~/.zshrc` file. Then run `source ~/.bashrc` (or `~/.zshrc`).

   export USE_CCACHE=1
   export CCACHE_DIR=~/android/ccache
   export CCACHE_EXEC=/usr/bin/ccache

   Set a cache size (e.g., 50GB, adjust based on your free SSD space):

   ccache -M 50G

Downloading the LineageOS 21 Source Code

Now, let’s get the vast LineageOS source code onto your machine. This process can take several hours depending on your internet speed.

1. Create a working directory:

   mkdir -p ~/android/lineage
   cd ~/android/lineage

2. Initialize the LineageOS repository:

   repo init -u https://github.com/LineageOS/android.git -b lineage-21

   The `-b lineage-21` flag ensures you’re pulling the Android 14 based LineageOS 21 branch.

3. Synchronize the repositories:

   repo sync -c -j$(nproc --all)

   The `-c` flag fetches only the current branch, saving space. `-j$(nproc –all)` uses all available CPU cores for parallel downloads, speeding up the process. This step will download hundreds of gigabytes of data.

Device-Specific Setup and Proprietary Blobs

Once the source code is downloaded, you need to prepare the device-specific files. LineageOS cannot be built entirely from open-source code due to proprietary hardware drivers (blobs) required by your device. These typically come from your device’s stock firmware.

1. Source the build environment:

   source build/envsetup.sh

2. Choose your device:

   Use the `breakfast` command with your device’s codename. You can find this codename on the LineageOS wiki or in the device’s `device/lineage/` folder within the source tree.

   breakfast <codename>

   For example, for a Google Pixel 7 (`panther`):

   breakfast panther

   This command prepares your build environment for your specific device and attempts to fetch official device trees, kernel, and vendor repositories if they exist on the LineageOS GitHub.

3. Extract Proprietary Blobs:

   For most devices, you’ll need to extract proprietary files from your device’s stock firmware or a running LineageOS installation. This usually involves:

   • Flashing the latest stock firmware (if not already on it).
   • Booting into your device with ADB enabled.
   • Connecting your device to your build machine.
   • Navigating to the device’s vendor directory in your source tree (e.g., `cd vendor/lineage/panther`).
   • Executing the `extract-files.sh` script:

   ./extract-files.sh

   This script pulls the necessary proprietary files directly from your connected device and places them in the correct location within your source tree. Follow any on-screen prompts for ADB authorization on your device.

   Alternatively, for devices with prebuilt vendor repositories, `breakfast` might pull these for you automatically, or you might need to use `repo sync` again after device tree initialization.

Building LineageOS 21

With all prerequisites met and source code, including proprietary blobs, in place, you are ready to start the compilation process.

1. Ensure you are in the root of your LineageOS source directory:

   cd ~/android/lineage

2. Source the build environment (if you closed the terminal):

   source build/envsetup.sh

3. Initiate the build:

   Use the `brunch` command with your device’s codename. This command will first run `breakfast` (if not already run) and then start the actual compilation.

   brunch <codename>

   For example:

   brunch panther

   The first build will take a considerable amount of time (several hours) as `ccache` will be populated. Subsequent builds, especially after minor changes, will be much faster thanks to `ccache`.

4. Monitor the build process:

   You will see a stream of compilation messages. A successful build will conclude with a message indicating the location of the generated `.zip` file, typically in `out/target/product/<codename>/`. This `.zip` file is your flashable LineageOS ROM.

Flashing Your Custom Build (Brief Overview)

Once your build is complete, you’ll have a `lineage-21.0-<timestamp>-UNOFFICIAL-<codename>.zip` file. To flash it, you’ll typically:

• Reboot your device into a custom recovery like TWRP or Lineage Recovery.
• Wipe necessary partitions (data, cache, system, vendor, etc., as per device-specific instructions).
• Flash your generated LineageOS `.zip` file.
• (Optional) Flash GApps or other add-ons if desired.
• Reboot your device.

Always refer to the official LineageOS installation instructions for your specific device on the LineageOS Wiki for detailed flashing steps, as they can vary.

Conclusion

Congratulations! You’ve successfully navigated the complex process of setting up a LineageOS 21 build environment and compiled your very own custom ROM based on Android 14. This achievement not only grants you a highly optimized and personalized Android experience but also provides invaluable insights into the intricacies of mobile operating system development. With this knowledge, you are no longer just a user, but a contributor to the vibrant open-source Android community. Happy building!