aosp12/tools/treble/split/README.md

Manifest Split

Overview

Split manifests are Android repo manifests that contain the minimum set of projects necessary to build a given target. If a project isn't used for building the target, it shouldn't be in the split manifest. This smaller manifest can be used to sync the Android source tree and build the specific target. This sync should be faster and smaller than a sync of a full manifest because it is syncing less projects.

The treble_manifest_split tool is used to automatically create a split manifest from a full manifest using dependency information from the source tree and the build outputs. The tool attempts to infer as many dependencies as it can, but some will be missed due to implicit dependencies in the build system and source tree. This is solved by manually fine-tuning a tool configuration XML specific to your target.

Example for aosp_arm64

1. Run a full build using a full manifest

The treble_manifest_split tool needs the ninja build graph and deps log from a completed build in order to have a full view of the dependency graph. While the build graph is created at the beginning of a ninja build, the deps log is not complete until the build finishes.

Use standard Android build commands to build your target.

2. Use the treble_manifest_split tool

# Change to the directory where you ran the full build.
cd /path/to/android

# Set command line variables for the Android target you are using and the build
# target that should be buildable from your split manifest.
ANDROID_TARGET=aosp_arm64-userdebug
BUILD_TARGET=droid

# Build treble_manifest_split as a python binary.
lunch $ANDROID_TARGET
m treble_manifest_split

# Create the split manifest using a sample config XML specific to aosp_arm64.
out/host/linux-x86/bin/treble_manifest_split \
  --manifest .repo/manifests/default.xml \
  --split-manifest split_default.xml \
  --debug-file debug.json \
  --config tools/treble/split/sample_config.xml \
  $BUILD_TARGET

3. Build using the split manifest

You should test that the split manifest created by the tool can be used to build the partial target files package.

1. Initialize a new repo directory using the steps in https://source.android.com/setup/build/downloading#initializing-a-repo-client.
2. Replace the .repo/manifests/default.xml full manifest with the newly-generated split manifest.
3. Use standard repo sync commands to sync your repo.
4. Attempt a build of your target.

4. Fix build errors

Build errors may arise due to missing dependencies that were previously provided by now-removed projects. These dependencies may be implicit in the source code, or an explicit dependency type that is not yet able to be automatically detected by the tool.

1. Find the dependency source project in your full-manifest repo directory.

2. Update your config XML to manually add projects to your split manifest.

   • For example, the following line in sample_config.xml in this tool directory specifies a project that should be included in the split manifest even if the tool doesn't automatically detect that it is necessary.

       <add_project name="platform/external/python/cpython3" />
   

3. Regenerate the split manifest using treble_manifest_split in your full-manifest directory. Remember to pass the path of your config XML to the script's --config flag.

5. Compare built artifacts

A successful build alone is not sufficient to have full confidence in the split manifest. You should diff the output artifacts of the split-manifest build against the output artifacts of the full-manifest build.

Suggestions for viewing diffs:

• Use an external directory diffing tool on the output directories for each partition, such as out/target/product/<device>/system.
• Use development/vndk/tools/image-diff-tool/diff.py on output directories, or on a zipped target-files archive if you are creating dist builds.

The following may cause differences between output artifacts:

• Non-hermetic inputs used in the module build rule, such as timestamps. Can be fixed by removing the timestamp from the build rule.
• An implicit and optional source dependency. Can be fixed by manually adding the project that defines the missing source.