Update README with additional instructions

Add instructions for both using the script as well as expanding the
script to make it easier for those who find the script to use it.

Test: N/A
Change-Id: I0ab87d75b40f1c0ff8f5b797442842a30707a32c

1 files changed, 261 insertions, 3 deletions

diff --git a/experiments/prepare_bazel_test_env/README.md b/experiments/prepare_bazel_test_env/README.md
index 896a715..7f0de8f 100644
--- a/experiments/prepare_bazel_test_env/README.md
+++ b/experiments/prepare_bazel_test_env/README.md
@@ -1,5 +1,263 @@
 # Overview
 
-The `prepare_bazel_test_env` script is a proof-of-concept script
-to create a simulated Bazel environment within the Android source
-tree using targets build by the Soong build system.
+The `prepare_bazel_test_env` script is a proof-of-concept script to create a
+simulated Bazel environment within the Android source tree using targets build
+by the Soong build system.
+
+# Supported Modules
+
+The script currently support generation of a Bazel environment to run the
+following Soong test modules:
+
+*   `//platform_testing/tests/example/native:hello_world_test`
+*   `//platform_testing/tests/example/jarhosttest: HelloWorldHostTest`
+*   `//platform_testing/tests/example/instrumentation: HelloWorldTests`
+
+Additionally, the system supports running the Tradefed console directly through
+the `//tools/tradefederation/core:tradefed` target.
+
+# Usage
+
+There are three actions that the script can perform, which are supplied as the
+first argument to the script: generate, sync, and clean, discussed below. All
+the commands below are written with the `-v` flag for verbose output, however
+this can be safely removed if desired.
+
+## Generate
+
+**Command Line**: `bazel run //build/pesto/experiments/prepare_bazel_test_env --
+-v generate`
+
+The generate command builds the required targets for a Bazel environment via
+Soong, then stages this environment and associated dependencies at
+`out/pesto-environment/` .
+
+The generate command performs the following actions:
+
+1.  Builds a set of modules (defined in the packaged templates in the
+    `data/templates` directory) via Soong
+2.  Creates a prebuilts directory at `out/pesto-environment/prebuilts` which
+    contains symlinks to the Android Build environment provided directories
+    (`ANDROID_HOST_OUT`, `ANDROID_HOST_OUT_TESTCASES`, `ANDROID_PRODUCT_OUT`,
+    `ANDROID_TARGET_OUT_TESTCASES`), and will later be linked to by a
+    `.soong_prebuilts` symlink that is placed adjacent to generated BUILD files.
+3.  Generates a Bazel environment at `out/pesto-environment/gen` using the
+    packaged environment to determine the locations of files, which are placed
+    in locations relative to the source tree root. For example, the
+    `out/pesto-environment/gen/tools/tradefederation/core/BUILD.bazel`
+    corresponds to a file that will eventually live at
+    `tools/tradefederation/core/BUILD.bazel`.
+4.  For each BUILD file that is staged, place a `.soong_prebuilts` symlink that
+    links to the aforementioned `prebuilts` directory.
+
+After generation, the environment create can serve as a standalone Bazel
+environment, or can be synced to the source tree using the sync command,
+discussed below.
+
+## Sync
+
+**Command Line**: `bazel run //build/pesto/experiments/prepare_bazel_test_env --
+-v sync`
+
+The sync command scans the staging directory at `out/pesto-environment/gen` for
+all files and then creates symlinks in the source tree that point at these
+files, additionally each synced BUILD file is provided local access to the
+`prebuilts` directory through a `.soong_prebuilts` symlink.
+
+The sync command performs the following actions:
+
+1.  Iterates through all files in the staged `out/pesto-environment/gen`
+    directory and create a symlink in the source tree to each file at the proper
+    location, overwriting file in the tree if it exists. For example, the sync
+    action would create a symlink at `packages/modules/adb/BUILD.bazel` that
+    links to `out/pesto-environment/gen/packages/modules/adb/BUILD.bazel`.
+2.  Create a `.soong_prebuilts` directory in every location in the source tree
+3.  where a BUILD file is placed, providing local access to the Soong staging
+4.  directories.
+
+After synchronization, the Bazel environment has been merged with the source
+tree and can be used directly from within the source tree. Additionally, after
+synchronization, subsequent calls to the generate command will propogate
+automatically to the source tree.
+
+## Clean
+
+**Command Line**: `bazel run //build/pesto/experiments/prepare_bazel_test_env --
+-v clean`
+
+The clean command removes all files that have been created in the tree, and also
+cleans up the environment directory at `out/pesto-environment` .
+
+The clean command performs the following actions:
+
+1.  For each file packaged with the script, remove the corresponding file from
+    the source tree.
+2.  For each BUILD file packaged with the script, remove the corresponding
+    `.soong_prebuilts` directory for the source tree.
+3.  Remove the `out/pesto-environment` directory.
+
+After clean, the environment should be removed from the tree. However, as some
+files may have been overwritten, certain repositories may need to be reset. The
+`build/bazel/rules/BUILD.bazel` file is a notable example that needs to be
+manually reset.
+
+# Adding New Modules.
+
+Adding support for an additional module depends on the type of module to be
+added. Each is discussed below. Of note, all files should be added in the
+`templates` directory and end in the `.template` file extension unless the file
+is a static, non-Bazel file.
+
+## Test Modules (without existing Test Rules)
+
+For targets needing a new test rule, if the test is a Tradefed run test, use the
+existing test rules as a template, otherwise a custom Bazel rule can be added.
+
+An example rule is provided at
+`templates/build/bazel/rules/cc_test.bzl.template` . For a new rule that
+leverages Tradefed, use the above rule as an example of how to package
+dependencies and test artifacts into the runfiles for the test. For each
+Tradefed rule, the required dependencies should be included as private
+attributes, for use by the rule implementation.
+
+```
+cc_test = rule(
+    _cc_test_impl,
+    attrs = {{
+        "_adb": attr.label(
+            default = Label("//packages/modules/adb"),
+            allow_single_file = True,
+        ),
+        "_tradefed_launcher": attr.label(
+            default = Label("//tools/tradefederation/core:atest_tradefed"),
+            allow_single_file = True,
+        ),
+        "_tradefed_script_help": attr.label(
+            default = Label("//tools/tradefederation/core:atest_script_help"),
+        ),
+        "_tradefed_jars": attr.label(
+            default = Label("//tools/tradefederation/core:tradefed_lib"),
+        ),
+        "_template": attr.label(
+            default = Label(
+                "//build/bazel/rules:tf_test_executable.sh.template",
+            ),
+            allow_single_file = True,
+        ),
+        "_launcher": attr.label(default = Label("//build/bazel/rules:cc_tf_test_launcher")),
+        "deps": attr.label_list(allow_files = True),
+    }},
+    executable = True,
+    test = True,
+)
+```
+
+Additionally, the Soong produced artifacts should also be included as runfiles
+so they can be seen during Tradefed execution. Including a target as runfiles
+here, ensures that the target shows up during execution. Furthermore, it ensures
+that Bazel knows when to rebuild/rerun a test when artifacts change.
+
+```
+runfiles = ctx.runfiles(
+        files = ctx.files._launcher,
+        transitive_files = depset(
+            transitive = [
+                depset(ctx.files.deps),
+                depset(ctx.files._adb),
+                depset(ctx.files._tradefed_launcher),
+                depset(ctx.files._tradefed_script_help),
+                depset(ctx.files._tradefed_jars),
+            ],
+        ),
+    )
+```
+
+Finally, the test rule should use the tf_test_executable.sh file as its
+executable and provide the proper substitutions to this file, which can be seen
+in the above example rule. The tf_test_executable.sh handles setting important
+variables needed by Tradefed before test execution in a Bazel environment.
+
+```
+ctx.actions.expand_template(
+    template = ctx.file._template,
+    output = script,
+    substitutions = {{
+        "{{module_name}}": ctx.label.name,
+        "{{module_path}}": ctx.label.package,
+        "{{tradefed_launcher_module_path}}": ctx.attr._tradefed_launcher.label.package,
+        "{{tradefed_jars_module_path}}": ctx.attr._tradefed_jars.label.package,
+        "{{path_additions}}": ctx.attr._adb.label.package,
+        "{{launcher_path}}": "{{}}/{{}}".format(
+            ctx.attr._launcher.label.package,
+            ctx.attr._launcher.label.name,
+        ),
+    }},
+    is_executable = True,
+)
+```
+
+After the rule logic is added, follow the steps in the below section for how to
+add a test target leveraging the newly added rule.
+
+## Test Modules (with existing Test Rules)
+
+For targets where the test rule is already provided (i.e. `cc_test` ), adding a
+new test module requires only adding a new BUILD file (with associated import
+logic).
+
+All added BUILD templates should end in `.template` to ensure Bazel does not see
+these files as part of a package, and should contain the required Soong targets,
+defined like the following:
+
+```
+# SOONG_TARGET:CtsAppTestCases
+# SOONG_TARGET:org.apache.http.legacy
+```
+
+Refer to the
+`data/templates/platform_testing/tests/example/native/BUILD.bazel.template` as
+an example of how to import files into the Bazel environment using a genrule.
+The genrule logic in the example template is used to combine files from multiple
+locations into a single target and strip the Soong paths from the files imported
+to Bazel. The below genrule serves as a foundation and copies all files from
+srcs to the files listed in outs.
+
+```
+genrule(name="hello_world_test_prebuilt",
+        srcs=_LIB_SRCS + _TESTCASE_HOST_SRCS + _TESTCASE_DEVICE_SRCS,
+        outs=_LIB_OUTS + _TESTCASE_HOST_OUTS + _TESTCASE_DEVICE_OUTS,
+        cmd="""
+          src_files=($(SRCS))
+          out_files=($(OUTS))
+          for i in "$${{!src_files[@]}}"
+          do
+            src_file=$${{src_files[$$i]}}
+            out_file=$${{out_files[$$i]}}
+            mkdir -p $$(dirname $$src_file)
+            cp $$src_file $$out_file
+          done
+          """)
+```
+
+When referring to files imported from Bazel, use the `{prebuilts_dir_name}`
+substitution variable instead of referring to the `.soong_prebuilts` directory
+directly since this may change.
+
+```
+_LIB_SRCS = glob([
+    "{prebuilts_dir_name}/host/lib/**/*",
+    "{prebuilts_dir_name}/host/lib64/**/*"
+])
+```
+
+Then, the newly imported module can be referenced from an existing test rule as
+a dependency, as is done in the example template. Ensure that the test rule is
+imported, such as in the example file:
+
+```
+load("//build/bazel/rules:cc_test.bzl", "cc_test")
+.
+.
+.
+cc_test(name="hello_world_test", deps=[":hello_world_test_prebuilt"])
+```