diff options
-rw-r--r-- | experiments/prepare_bazel_test_env/README.md | 264 |
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"]) +``` |