Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 90785567 authored by Justin Yun's avatar Justin Yun
Browse files

Add detailed guide for file_list_diff error

Add README.md for more details and error resolution guide for the
file_list_diff tool. Guide users to read the REAMDE.md doc with the
error message to help them fix the errors.

Bug: 411254556
Test: m out/target/product/<product>/obj/PACKAGING/system_intermediates/file_diff.timestamp
Change-Id: If2ad3ba97ad86839d777c2b509f3e823105d3d13
parent 49c20850
Loading
Loading
Loading
Loading
+44 −0
Original line number Diff line number Diff line
# Resolving System Image File List Differences

The Android build system uses the `file_list_diff` tool to ensure consistency
between the lists of installed files in system images defined by Kati and Soong.
This check is crucial when transitioning to Soong-defined system images. If the
tool detects any discrepancies, the build will fail.

This document helps you understand and resolve the reported errors. There are
two main types of errors: files present only in the Kati-defined image
(`Kati only`) and files present only in the Soong-defined image (`Soong only`).

## Understanding and Fixing Errors

### Kati only installed files

This error indicates that certain system modules are included via
`PRODUCT_PACKAGES` in your device's Makefiles (`.mk` files) but are not
explicitly defined within the `android_system_image` module or its default
dependencies in `Android.bp`.

**To resolve this:**

* **Default System Modules:** If the module is defined in a common system
Makefile (like `base_system.mk`, `generic_system.mk`, etc.), ensure it's listed
in the `system_image_defaults` module within
`build/make/target/product/generic/Android.bp`.
* **Device-Specific Modules:** For modules specific to your device, add them to
the relevant `android_system_image` module defined in
`PRODUCT_SOONG_DEFINED_SYSTEM_IMAGE` for your target.

### Soong only installed files

This error means that certain system modules are present in the Soong-defined
system image (specified by `PRODUCT_SOONG_DEFINED_SYSTEM_IMAGE`) but are not
included in the `PRODUCT_PACKAGES` list for your target.

**To resolve this:**

* **Remove Incorrect Modules:** If these modules shouldn't be part of the system
image, remove them from the `android_system_image` module definition.
* **Add Missing Modules to Makefiles:** If these modules are indeed required,
add them to the appropriate `.mk` files, following the guidance in the "Kati
only installed files" section to ensure they are correctly included in both the
Kati and Soong definitions.
 No newline at end of file
+8 −5
Original line number Diff line number Diff line
@@ -42,17 +42,20 @@ def find_unique_items(kati_installed_files, soong_installed_files, system_module

    if unique_in_kati:
        print('')
        print(f'{COLOR_ERROR}Missing required modules in {system_module_name} module.{COLOR_NORMAL}')
        print(f'To resolve this issue, please add the modules to the Android.bp file for the {system_module_name} to install the following KATI only installed files.')
        print(f'You can find the correct Android.bp file using the command "gomod {system_module_name}".')
        print(f'{COLOR_ERROR}Missing required modules in the "{system_module_name}" module.{COLOR_NORMAL}')
        print(f'To resolve this issue, please add the modules to the Android.bp file for the "{system_module_name}" to install the following KATI only installed files.')
        print(f'You can find the Android.bp file using the command "gomod {system_module_name}".')
        print('See build/make/tools/filelistdiff/README.md for more details.')
        print(f'{COLOR_WARNING}KATI only installed file(s):{COLOR_NORMAL}')
        for item in sorted(unique_in_kati):
            print('  '+item)

    if unique_in_soong:
        print('')
        print(f'{COLOR_ERROR}Missing packages in base_system.mk.{COLOR_NORMAL}')
        print('Please add packages into build/make/target/product/base_system.mk or build/make/tools/filelistdiff/allowlist to install or skip the following Soong only installed files.')
        print(f'{COLOR_ERROR}Missing packages in PRODUCT_PACKAGES.{COLOR_NORMAL}')
        print(f'Please add packages into .mk files or remove them from the "{system_module_name}" module in Android.bp file.')
        print(f'You can find the Android.bp file using the command "gomod {system_module_name}".')
        print('See build/make/tools/filelistdiff/README.md for more details.')
        print(f'{COLOR_WARNING}Soong only installed file(s):{COLOR_NORMAL}')
        for item in sorted(unique_in_soong):
            print('  '+item)