Mastering Android Customization: A Deep Dive into Building and Troubleshooting LineageOS with revWhiteShadow

Welcome to revWhiteShadow, your dedicated hub for insightful explorations into the ever-evolving world of Android customization. Today, we embark on an in-depth journey into the intricate process of building LineageOS, a paramount custom ROM known for its commitment to user privacy, open-source principles, and extensive device support. Our mission at revWhiteShadow is to provide you with the most comprehensive and detailed guidance, enabling you to navigate the complexities of this process and achieve a flawless custom ROM experience. We understand that the path to a successfully built LineageOS can be paved with technical challenges, and it is our distinct purpose to equip you with the knowledge to outrank any common troubleshooting articles you might encounter elsewhere. Prepare to delve deep into the nuances of the build process, with a particular focus on the common pitfalls and their effective resolutions.

Understanding the Foundations of LineageOS Builds

Before we dissect the troubleshooting aspects, it’s crucial to establish a firm understanding of what goes into building LineageOS. This open-source operating system is built upon the Android Open Source Project (AOSP), offering a cleaner, more customizable, and often more performant experience than stock Android. The build process itself is a complex undertaking, involving the compilation of thousands of individual components, libraries, and applications. It requires a robust development environment, specific prerequisite software, and a deep understanding of the Android build system, primarily powered by Soong and Makefiles.

At its core, building LineageOS involves several key stages:

  • Environment Setup: This is arguably the most critical initial step. It involves installing necessary packages, configuring your build environment (typically a Linux distribution), and synchronizing the LineageOS source code.
  • Device-Specific Configurations: Each Android device requires a unique set of configurations to function correctly with LineageOS. These are contained within device-specific trees, which include kernel sources, device blobs (proprietary drivers), and device configuration files.
  • Compilation: This is the core process where the source code is transformed into a flashable ROM image. This stage is resource-intensive, demanding significant CPU power and RAM.
  • Packaging and Flashing: Once compiled, the ROM is packaged into a flashable ZIP file, which can then be installed on a compatible device using a custom recovery like TWRP.

Our focus today will be on the hurdles you might face during the compilation and packaging stages, providing you with the expert insights needed to overcome them.

The journey of building a custom ROM is rarely without its hiccups. Developers and enthusiasts alike often encounter specific errors that can halt the build process. We’ve meticulously gathered and analyzed the most prevalent issues, offering detailed explanations and actionable solutions.

#### Addressing the “module manifest_input.classifier-service does not exist” Error

This particular error message often signals a fundamental dependency issue within your device’s configuration. The line “This error arises on devices that require a vendor directory to be populated before breakfast will succeed, as noted in the warning section. Extract proprietary blobs and continue,” from the provided snippet, is a critical clue.

The Root Cause: Incomplete Proprietary Blobs

The Android ecosystem relies heavily on proprietary, closed-source hardware drivers and firmware – commonly referred to as “blobs.” These are essential for the proper functioning of hardware components like the camera, Wi-Fi, Bluetooth, and sensors. LineageOS, being an open-source project, cannot legally redistribute these blobs directly. Instead, it provides scripts to extract them from a working, stock firmware image of your target device.

When you encounter the module manifest_input.classifier-service does not exist error, it frequently means that the build system cannot locate critical files or modules that are expected to be present. This often stems from an incomplete or unsuccessful extraction of these proprietary blobs. The breakfast command, which prepares your build environment for a specific device, relies on these extracted blobs to properly configure the build.

The Solution: Thorough Blob Extraction

  1. Verify Your Device Tree: Ensure you have downloaded and correctly placed the device-specific tree for your particular device model. These trees are typically found in lineageos/device/<manufacturer>/<codename>.
  2. Locate the Extraction Script: Within your device tree, there will usually be a script designed to extract proprietary blobs. This script is often named extract-files.sh or a similar variant.
  3. Connect Your Device and Enter ADB: Connect your target Android device to your computer via USB, ensuring that Android Debug Bridge (ADB) is properly configured and authorized on your device.
  4. Execute the Extraction Script: Navigate to your device tree directory in your terminal and run the extraction script. For example, you might execute:
    ./extract-files.sh
    This script will attempt to pull the necessary files from your connected device and place them in the vendor/<manufacturer>/<codename> directory within your LineageOS source tree.
  5. Crucial Check: Vendor Directory Contents: After running the script, meticulously examine the vendor/<manufacturer>/<codename> directory. You are looking for a comprehensive set of files and subdirectories, including .mk files, .rc files, and crucially, shared object (.so) files. If this directory appears sparse or empty, the extraction likely failed.
  6. Troubleshooting Extraction Failures:
    • ADB Authorization: Double-check that ADB is authorized on your device. A common oversight is not confirming the authorization prompt on the device screen.
    • Device State: Ensure your device is booted into a system from which ADB can pull files. A custom recovery might not always provide the necessary environment. Booting into the stock ROM or a previously installed LineageOS build is usually recommended.
    • Device-Specific Issues: Some devices have unique requirements or quirks in their extraction scripts. Consult device-specific forums or wikis for any known issues or alternative extraction methods.
    • Alternative Blob Sources: In rare cases, if you cannot extract blobs from your device, you might need to find pre-extracted blob repositories. However, proceed with caution, as these are not officially sanctioned and could introduce compatibility or security concerns. Websites like XDA Developers or dedicated GitHub repositories are often where these are shared. The reference to https://gist.github.com/fourkbomb/261ced58cd029c5f7742350aafdd9825 themuppets points to such community-maintained resources.

By ensuring a complete and successful extraction of proprietary blobs, you provide the build system with the necessary components to resolve the module manifest_input.classifier-service does not exist error and proceed with your LineageOS build.

#### Resolving “common.mk: error: missing libthermalclient (or other library or .so file)”

This error, as exemplified by the specific message "vendor.qti.hardware.display.composer-service (EXECUTABLES android-arm64) missing libthermalclient (SHARED_LIBRARIES android-arm64)", points to a dependency that the build system cannot find.

The Core Problem: Unmet Library Dependencies

The Android build system is highly interconnected. Executables and libraries often depend on other shared libraries (.so files) to function correctly. When the build process encounters a situation where a required library is missing, it halts with an error like this. The common.mk file, often located in hardware-specific directories, is a common place where these dependencies are defined.

The Solutions: Managing Missing Dependencies

There are a few primary ways to approach this, ranging from temporary workarounds to more fundamental fixes:

  1. The ALLOW_MISSING_DEPENDENCIES=true Flag (Use with Caution): The snippet suggests setting ALLOW_MISSING_DEPENDENCIES=true in your environment. This is a build system override that tells the compiler to proceed even if it detects missing dependencies.

    • How to Use: You can export this variable in your terminal before running the mka (or make) command:
      export ALLOW_MISSING_DEPENDENCIES=true
mka
    • The Caveat: While this can allow the build to complete, it is not a true solution. It merely postpones the problem. The missing library will likely cause runtime crashes or prevent certain features from working on your device. This should only be used for diagnostic purposes to see if the build can progress, or if you are absolutely certain the missing dependency is non-critical for your specific use case.

  2. Ensuring Complete Blob Extraction (Revisited): Just as with the previous error, the most common underlying cause for missing .so files is incomplete proprietary blob extraction. The libthermalclient mentioned in the example is a prime candidate for being a proprietary library.

    • Action: Revisit the steps outlined in the solution for the module manifest_input.classifier-service does not exist error. Ensure your vendor directory is fully populated with all necessary .so files.

  3. Correcting Device-Specific Makefiles: In some instances, the device configuration files themselves might have incorrect entries or refer to libraries that are not properly included in the build or extracted blobs.

    • Action: If you are comfortable with delving into the device configuration (.mk and .bp files within your device tree), you can inspect these for any apparent misconfigurations related to the missing library. However, this requires a deeper understanding of the build system and the specific device’s hardware.

  4. Leveraging Community Resources: As the error mentions, finding alternative or known-good blobs from community sources like the “themuppets” repository can be a viable solution if your own extraction methods fail.

    • Action: If you suspect your blobs are incomplete or corrupted, try sourcing them from a trusted community repository for your specific device. This often involves replacing the contents of your vendor/ directory with the files from the community source.

The missing libthermalclient error underscores the importance of dependency management in the Android build process. Prioritize ensuring all proprietary blobs are correctly extracted, as this is the most frequent culprit.

#### Troubleshooting AssertionError: Failed to execute: out/soong/host/linux-x86/bin/mke2fs -O ^has_journal...

This error indicates a problem with the mke2fs tool, which is used to create Linux file systems, specifically the ext4 file system commonly used for Android partitions. The core of the issue lies in the incompatibility between the mke2fs version used during the build and certain configuration options.

The Underlying Conflict: mke2fs and orphan_file

The error message, “e2fsprogs disabled orphan_file in version 1.47.0, so it either must be downgraded for the old command to succeed, or the option orphan_file should be removed from /etc/mke2fs.conf on the machine you’re building on, since the bundled mke2fs reads the host’s config file,” clearly articulates the problem.

  • mke2fs: This is a utility essential for creating and formatting file systems.
  • orphan_file: This is an option that was historically used by mke2fs. However, in version 1.47.0 and later of the e2fsprogs package (which provides mke2fs), the orphan_file feature was disabled due to security and design considerations.
  • The Conflict: LineageOS builds, especially older ones or those with configurations that haven’t been updated, might still be using commands or configurations that rely on the orphan_file option. When your build environment’s mke2fs (which is often a version installed on your host Linux system) is 1.47.0 or newer, it encounters this disabled option and fails.

The Solutions: Aligning mke2fs Functionality

You have two primary avenues to resolve this:

  1. Downgrading e2fsprogs on Your Host System: This involves installing an older version of the e2fsprogs package on the Linux machine where you are performing the build.

    • How to Downgrade (Example for Arch Linux): The provided link https://archive.archlinux.org/packages/e/e2fsprogs/e2fsprogs-1.46.0-1-x86_64.pkg.tar.zst points to a specific older version. If you are using a Debian/Ubuntu-based system, the process would involve finding a compatible .deb package from an older repository or compiling it from source.
    • Process:
      • Download the appropriate older package for your distribution.
      • Use your distribution’s package manager to uninstall the current e2fsprogs and install the older version. For instance, on Arch Linux, you might use sudo pacman -U /path/to/e2fsprogs-1.46.0-1-x86_64.pkg.tar.zst.
      • Important: Be aware that downgrading core system packages can sometimes lead to other system issues. It’s advisable to perform this in a virtual machine or a dedicated build environment if you are concerned about your host system’s stability.

  2. Modifying the Host System’s mke2fs.conf: This approach involves configuring your host system’s mke2fs to ignore or handle the orphan_file option gracefully. The mke2fs tool reads its configuration from /etc/mke2fs.conf.

    • How to Modify:
      • Open the configuration file with root privileges:
        sudo nano /etc/mke2fs.conf
      • Locate the section related to [options] or [defaults] or specifically the [mkfs.ext4] section.
      • Find the line orphan_file and comment it out by adding a # at the beginning of the line, or remove it entirely.
      • Save the file and exit the editor.
    • Example:
      [options]
# The following options are enabled by default.
# Can be overridden by the command line.
# fs_type =
# block_size = 1024
# inode_size = 256
# reserved_blocks =
# lazy_itable_init = 1
# fast_commit_percentage = 0
# discard = 0
# nodiscard = 0
# inode_ratio = 8192
# junk_bits = 1
# 64bit = 1
# extents = 1
# uninit_bg = 1
# dir_index = 1
# ^has_journal = 1  <-- This might be the line causing issues, or orphan_file
# ^flex_bg = 1
# ^safe_links = 1
# ^large_file = 1
# ^huge_file = 0
# ^ext_bitmap = 1
# filetype = 1
# flex_meta_bg = 0
# ^metadata_csum = 0
# ^64bit_inodes = 0
# ^block_bitmap_csum = 0
# ^inode_table_csum = 0
# ^flex_metadata = 0
# ^direct_io = 0
# orphan_file = # <-- Comment out or remove this line if it exists

[defaults]
base_features = has_journal,ext_timer,filetype,sparse_super,large_file,flex_bg
immutable_bad_blocks = 1

[mkfs.ext4]
# The following options are enabled by default.
# Can be overridden by the command line.
# fs_type =
# block_size = 1024
# inode_size = 256
# reserved_blocks =
# lazy_itable_init = 1
# fast_commit_percentage = 0
# discard = 0
# nodiscard = 0
# inode_ratio = 8192
# junk_bits = 1
# 64bit = 1
# extents = 1
# uninit_bg = 1
# dir_index = 1
# ^has_journal = 1
# ^flex_bg = 1
# ^safe_links = 1
# ^large_file = 1
# ^huge_file = 0
# ^ext_bitmap = 1
# filetype = 1
# flex_meta_bg = 0
# ^metadata_csum = 0
# ^64bit_inodes = 0
# ^block_bitmap_csum = 0
# ^inode_table_csum = 0
# ^flex_metadata = 0
# ^direct_io = 0
# orphan_file = # <-- Comment out or remove this line if it exists
    • Impact: By commenting out or removing the orphan_file directive in mke2fs.conf, you prevent mke2fs from attempting to use this disabled option, thereby resolving the assertion error. This is often the less disruptive and more recommended solution as it doesn’t involve downgrading system packages.

Always re-run your build command after implementing either of these solutions to confirm the error has been resolved.

#### Debugging ExternalError: Failed to run command '['brillo_update_payload ...' and Partition Size Mismatches

This error is quite specific and relates to the dynamic partition management of modern Android devices, particularly those utilizing Google’s Dynamic Partitions. The error message, “Sum of sizes in google_dynamic_partitions_partition_list is 4883337216, which is greater than google_dynamic_partitions_size (4873781248),” highlights a critical imbalance.

The Core Issue: Exceeding Allocated Partition Space

Modern Android devices employ a system of dynamic partitions, which allows for more flexible allocation of storage space compared to the older fixed partition schemes. The brillo_update_payload command is part of the tooling used to manage these dynamic partitions, often during the update or build process.

The error occurs when the sum of the sizes of the individual partitions that LineageOS is trying to create (as listed in google_dynamic_partitions_partition_list) exceeds the total allocated size for dynamic partitions (google_dynamic_partitions_size). Essentially, you’re trying to fit more data than the designated space allows.

The Solutions: Reconciling Partition Sizes

This problem is often a consequence of changes made in the LineageOS build or the device-specific configurations, leading to larger partition requirements.

  1. Exporting WITH_GMS=true (A Potential, Though Controversial, Fix): The snippet mentions export WITH_GMS=true as a potential fix. GMS refers to Google Mobile Services (GMS), which includes the Google Play Store and other Google applications.

    • Why it might work: Including GMS can sometimes alter the build process or the resulting image size in a way that compensates for the partition size discrepancy. It’s possible that by including GMS, the build system might re-evaluate partition sizes or dependencies differently.
    • The Disadvantage: As the snippet rightly warns, “Some strongly discourage using this option even as a fix to this error.” This is because:
      • Not Purely Open Source: Including GMS means you are incorporating proprietary Google components, which goes against the core philosophy of many custom ROM users seeking a fully open-source experience.
      • Potential Side Effects: It might introduce other issues or dependencies related to Google services.
      • Doesn’t Address the Root Cause: It’s often a workaround rather than a solution to the underlying partition sizing problem.
    • How to Use: Export this variable before building:
      export WITH_GMS=true
mka
    • Recommendation: Use this option only if other methods fail and you understand the implications of including GMS.

  2. Reducing BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE: This is a more direct and often preferred approach. The BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE is a build variable that dictates how much space is reserved for the system image, and by extension, influences the overall dynamic partition allocation.

    • The Strategy: By decreasing this value, you free up space within the total allocated dynamic partition size, allowing the other partitions to fit. The amount you need to decrease it by is approximately the difference between the sum of your partition sizes and the total dynamic partition size indicated in the error.
    • Where to Find and Modify: This setting is typically found in a device-specific configuration file. Common locations include:
      • lineage/device/<manufacturer>/<codename>/BoardConfigLineage.mk
      • lineage/device/<manufacturer>/<codename>/BoardConfig.mk
      • Files that these primary BoardConfig files include (e.g., device/google/redbull/BoardConfigLineage.mk is mentioned as an example for Google devices).
    • Example Modification: Let’s say your error shows Sum of sizes = 4883337216 and google_dynamic_partitions_size = 4873781248. The difference is 4883337216 - 4873781248 = 9555968 bytes. You would then locate the line setting BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE and reduce it by at least this amount.
      • Original: BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE := 175235072 (This is an example, the actual value might vary)
      • Modified: Calculate the new value. If the original was 175235072, and you need to reduce by 9555968, the new value would be 175235072 - 9555968 = 165679104.
      • New Line: BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE := 165679104
    • Precision: It’s often recommended to reduce it by a slightly larger margin to ensure ample space. Experimentation may be necessary.
    • Important: After making this change, you will need to clean your build output to ensure the new setting is properly applied. You can usually do this by running:
      mka clean
# or
make clean
      Then, re-run your build command.

  3. Re-evaluating Device-Specific Trees and Vendor Blobs: Sometimes, the issue might be that the device tree itself or the extracted blobs are outdated or not fully compatible with the current LineageOS version you are building.

    • Action: Ensure you are using the latest stable versions of your device tree and vendor blobs, and that they are specifically maintained for the LineageOS version you are targeting. Community forums are invaluable for this.

The brillo_update_payload error is a direct challenge to the storage management within modern Android. By carefully adjusting partition reservation sizes or, cautiously, considering GMS inclusion, you can resolve these discrepancies and successfully build your LineageOS ROM.

Beyond the Errors: Maintaining a Robust Build Environment

Successfully navigating these common errors is a significant step towards mastering LineageOS builds. However, maintaining a healthy and efficient build environment is an ongoing process.

#### Keeping Your Source Code Updated

The LineageOS project is constantly evolving. Regularly synchronizing your source code with the latest changes is crucial for incorporating bug fixes, new features, and updated device support.

  • Command: Use the repo sync command in your LineageOS source directory.
    repo sync -j$(nproc)
    The -j$(nproc) flag utilizes all available CPU cores for a faster sync.

#### Managing Build Cache and Dependencies

The build process generates a significant cache. While this speeds up subsequent builds, it can sometimes become corrupted or outdated, leading to unexpected errors.

  • Cleaning Build Output: As mentioned earlier, mka clean or make clean removes all compiled artifacts, forcing a full rebuild.
  • Cache Management: For more persistent issues, you might need to explore cleaning specific cache directories within your source tree.

#### Utilizing Community Resources Effectively

The LineageOS community is one of its greatest strengths. Forums like XDA Developers and dedicated Telegram groups are invaluable resources for troubleshooting.

  • Search First: Before asking for help, thoroughly search existing threads for similar issues.
  • Provide Details: When you do need to ask for assistance, provide as much detail as possible: your device, the exact error message, the steps you’ve already taken, and your build environment details.

Conclusion: Your Path to Custom ROM Mastery with revWhiteShadow

Building LineageOS is a rewarding experience that grants you unparalleled control over your Android device. While the process can present technical challenges, understanding the common errors and their solutions, as detailed here on revWhiteShadow, is the key to a successful build. From ensuring the integrity of proprietary blobs to correctly managing partition sizes and resolving library dependencies, we’ve provided a comprehensive guide designed to empower you.

At revWhiteShadow, our commitment is to deliver the most detailed and accurate information to help you outrank any generic guides. By internalizing these troubleshooting steps and maintaining a meticulous approach to your build environment, you are well on your way to a flawless LineageOS installation and a deeper understanding of the Android ecosystem. Continue to explore, experiment, and build with confidence.