Adds a README and canonical example for treble_manifest_split.android-s-beta-2android-s-beta-1

Also updates the default ninja path to a valid path.

Bug: 186258929
Test: Follow the steps provided in the README to create a split
      manifest for aosp_arm64.
Change-Id: Ia5f7f2937f8b3d813678eea388bd16ec4a12e32f

3 files changed, 141 insertions, 1 deletions

diff --git a/split/README.md b/split/README.md
new file mode 100644
index 0000000..db3e7de
--- /dev/null
+++ b/split/README.md
@@ -0,0 +1,107 @@
+# 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
+
+```shell
+# 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.
+1.  Replace the `.repo/manifests/default.xml` full manifest with the
+    newly-generated split manifest.
+1.  Use standard `repo sync` commands to sync your repo.
+1.  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.
+1.  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" />
+    ```
+
+1.  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.
diff --git a/split/manifest_split.py b/split/manifest_split.py
index f329958..d5f9b95 100644
--- a/split/manifest_split.py
+++ b/split/manifest_split.py
@@ -619,7 +619,7 @@ def main(argv):
   repo_list_file = None
   ninja_build_file = None
   module_info_file = None
-  ninja_binary = "ninja"
+  ninja_binary = "prebuilts/build-tools/linux-x86/bin/ninja"
   kati_stamp_file = None
   overlays = []
   installed_prebuilts = []
diff --git a/split/sample_config.xml b/split/sample_config.xml
new file mode 100644
index 0000000..b9318ff
--- /dev/null
+++ b/split/sample_config.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<config>
+    <!-- treble_manifest_split config for aosp_arm64. -->
+
+    <!-- ============================================================= -->
+
+    <!-- Add projects that provide modules required for build success, but
+         are not detected automatically by the tool. -->
+
+    <!-- Lots of modules require py3-stdlib -->
+    <add_project name="platform/external/python/cpython3" />
+
+    <!-- bionic/libc:libc_jemalloc_wrapper requires libjemalloc5 -->
+    <add_project name="platform/external/jemalloc_new" />
+
+    <!-- libcore/ojluni:ojluni-phony requires art-notices-for-framework-stubs-jar -->
+    <add_project name="platform/prebuilts/module_sdk/art" />
+
+    <!-- Provides executable "as", needed by clang for some modules. -->
+    <add_project name="platform/prebuilts/gcc/linux-x86/arm/arm-linux-androideabi-4.9" />
+
+    <!-- ============================================================= -->
+
+    <!-- Remove some device projects that the tool included due to Kati makefile
+         scanning, but are not required to build aosp_arm64. -->
+    <remove_project name="device/generic/goldfish" />
+    <remove_project name="device/generic/goldfish-opengl" />
+    <remove_project name="device/google/atv" />
+    <remove_project name="device/google/trout" />
+    <remove_project name="device/ti/beagle-x15" />
+
+</config>
+