1# Manifest Split 2 3## Overview 4 5Split manifests are Android repo manifests that contain the minimum set of 6projects necessary to build a given target. If a project isn't used for building 7the target, it shouldn't be in the split manifest. This smaller manifest can be 8used to sync the Android source tree and build the specific target. This sync 9should be faster and smaller than a sync of a full manifest because it is 10syncing less projects. 11 12The `treble_manifest_split` tool is used to automatically create a split 13manifest from a full manifest using dependency information from the source tree 14and the build outputs. The tool attempts to infer as many dependencies as it 15can, but some will be missed due to implicit dependencies in the build system 16and source tree. This is solved by manually fine-tuning a tool configuration XML 17specific to your target. 18 19## Example for aosp_arm64 20 21### 1. Run a full build using a full manifest 22 23The `treble_manifest_split` tool needs the ninja build graph and deps log from a 24completed build in order to have a full view of the dependency graph. While the 25build graph is created at the beginning of a ninja build, the deps log is not 26complete until the build finishes. 27 28Use standard Android build commands to build your target. 29 30### 2. Use the treble_manifest_split tool 31 32```shell 33# Change to the directory where you ran the full build. 34cd /path/to/android 35 36# Set command line variables for the Android target you are using and the build 37# target that should be buildable from your split manifest. 38ANDROID_TARGET=aosp_arm64-userdebug 39BUILD_TARGET=droid 40 41# Build treble_manifest_split as a python binary. 42lunch $ANDROID_TARGET 43m treble_manifest_split 44 45# Create the split manifest using a sample config XML specific to aosp_arm64. 46out/host/linux-x86/bin/treble_manifest_split \ 47 --manifest .repo/manifests/default.xml \ 48 --split-manifest split_default.xml \ 49 --debug-file debug.json \ 50 --config tools/treble/split/sample_config.xml \ 51 $BUILD_TARGET 52``` 53 54### 3. Build using the split manifest 55 56You should test that the split manifest created by the tool can be used to build 57the partial target files package. 58 591. Initialize a new repo directory using the steps in 60 https://source.android.com/setup/build/downloading#initializing-a-repo-client. 611. Replace the `.repo/manifests/default.xml` full manifest with the 62 newly-generated split manifest. 631. Use standard `repo sync` commands to sync your repo. 641. Attempt a build of your target. 65 66### 4. Fix build errors 67 68Build errors may arise due to missing dependencies that were previously provided 69by now-removed projects. These dependencies may be implicit in the source code, 70or an explicit dependency type that is not yet able to be automatically detected 71by the tool. 72 731. Find the dependency source project in your full-manifest repo directory. 741. Update your config XML to manually add projects to your split manifest. 75 76 - For example, the following line in `sample_config.xml` in this tool 77 directory specifies a project that should be included in the split 78 manifest even if the tool doesn't automatically detect that it is 79 necessary. 80 81 ``` 82 <add_project name="platform/external/python/cpython3" /> 83 ``` 84 851. Regenerate the split manifest using `treble_manifest_split` in your 86 full-manifest directory. Remember to pass the path of your config XML to the 87 script's `--config` flag. 88 89### 5. Compare built artifacts 90 91A successful build alone is not sufficient to have full confidence in the split 92manifest. You should diff the output artifacts of the split-manifest build 93against the output artifacts of the full-manifest build. 94 95Suggestions for viewing diffs: 96 97- Use an external directory diffing tool on the output directories for each 98 partition, such as `out/target/product/<device>/system`. 99- Use `development/vndk/tools/image-diff-tool/diff.py` on output directories, 100 or on a zipped target-files archive if you are creating `dist` builds. 101 102The following may cause differences between output artifacts: 103 104- Non-hermetic inputs used in the module build rule, such as timestamps. Can 105 be fixed by removing the timestamp from the build rule. 106- An implicit and optional source dependency. Can be fixed by manually adding 107 the project that defines the missing source. 108