Update README with additional instructions am: 7fc3494f6a am: 784267f9ed
Original change: https://android-review.googlesource.com/c/platform/build/pesto/+/1701745
Change-Id: Id7d703c461e55dc63ac00c1c30de8bd49adbb6f5
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"])
+```
