soong_ui's bazel.go: document/comment with tiny refactoring.
This patch adds information behind the Bazel USE_BAZEL=1 execution
pipeline.
Test: m
Bug: 173474588
Change-Id: I54bdd26fb14c8a371de0922d193419112e8c3ece
diff --git a/ui/build/bazel.go b/ui/build/bazel.go
index 7cc7caf..2d36f67 100644
--- a/ui/build/bazel.go
+++ b/ui/build/bazel.go
@@ -24,8 +24,8 @@
"android/soong/ui/metrics"
)
-// Main entry point to construct the Bazel build command line, environment variables
-// and post-processing steps (e.g. converge output directories)
+// Main entry point to construct the Bazel build command line, environment
+// variables and post-processing steps (e.g. converge output directories)
func runBazel(ctx Context, config Config) {
ctx.BeginTrace(metrics.RunBazel, "bazel")
defer ctx.EndTrace()
@@ -41,53 +41,86 @@
outputGroups = strings.Join(config.ninjaArgs, ",")
}
+ // Environment variables are the primary mechanism to pass information from
+ // soong_ui configuration or context to Bazel.
+ //
+ // Use *_NINJA variables to pass the root-relative path of the combined,
+ // kati-generated, soong-generated, and packaging Ninja files to Bazel.
+ // Bazel reads these from the lunch() repository rule.
config.environ.Set("COMBINED_NINJA", config.CombinedNinjaFile())
config.environ.Set("KATI_NINJA", config.KatiBuildNinjaFile())
config.environ.Set("PACKAGE_NINJA", config.KatiPackageNinjaFile())
config.environ.Set("SOONG_NINJA", config.SoongNinjaFile())
+ // `tools/bazel` is the default entry point for executing Bazel in the AOSP
+ // source tree.
bazelExecutable := filepath.Join("tools", "bazel")
cmd := Command(ctx, config, "bazel", bazelExecutable)
- if extra_startup_args, ok := cmd.Environment.Get("BAZEL_STARTUP_ARGS"); ok {
- cmd.Args = append(cmd.Args, strings.Fields(extra_startup_args)...)
+ // Append custom startup flags to the Bazel command. Startup flags affect
+ // the Bazel server itself, and any changes to these flags would incur a
+ // restart of the server, losing much of the in-memory incrementality.
+ if extraStartupArgs, ok := cmd.Environment.Get("BAZEL_STARTUP_ARGS"); ok {
+ cmd.Args = append(cmd.Args, strings.Fields(extraStartupArgs)...)
}
+ // Start constructing the `build` command.
actionName := "build"
cmd.Args = append(cmd.Args,
actionName,
+ // Use output_groups to select the set of outputs to produce from a
+ // ninja_build target.
"--output_groups="+outputGroups,
+ // Generate a performance profile
"--profile="+filepath.Join(shared.BazelMetricsFilename(config.OutDir(), actionName)),
"--slim_profile=true",
)
- if extra_build_args, ok := cmd.Environment.Get("BAZEL_BUILD_ARGS"); ok {
- cmd.Args = append(cmd.Args, strings.Fields(extra_build_args)...)
+ // Append custom build flags to the Bazel command. Changes to these flags
+ // may invalidate Bazel's analysis cache.
+ if extraBuildArgs, ok := cmd.Environment.Get("BAZEL_BUILD_ARGS"); ok {
+ cmd.Args = append(cmd.Args, strings.Fields(extraBuildArgs)...)
}
+ // Append the label of the default ninja_build target.
cmd.Args = append(cmd.Args,
"//:"+config.TargetProduct()+"-"+config.TargetBuildVariant(),
)
+ // Ensure that the PATH environment variable value used in the action
+ // environment is the restricted set computed from soong_ui, and not a
+ // user-provided one, for hermeticity reasons.
if pathEnvValue, ok := config.environ.Get("PATH"); ok {
cmd.Environment.Set("PATH", pathEnvValue)
cmd.Args = append(cmd.Args, "--action_env=PATH="+pathEnvValue)
}
+
cmd.Environment.Set("DIST_DIR", config.DistDir())
cmd.Environment.Set("SHELL", "/bin/bash")
+ // Print the full command line for debugging purposes.
ctx.Println(cmd.Cmd)
+
+ // Execute the command at the root of the directory.
cmd.Dir = filepath.Join(config.OutDir(), "..")
ctx.Status.Status("Starting Bazel..")
+
+ // Execute the build command.
cmd.RunAndStreamOrFatal()
+ // Post-processing steps start here. Once the Bazel build completes, the
+ // output files are still stored in the execution root, not in $OUT_DIR.
+ // Ensure that the $OUT_DIR contains the expected set of files by symlinking
+ // the files from the execution root's output direction into $OUT_DIR.
+
// Obtain the Bazel output directory for ninja_build.
infoCmd := Command(ctx, config, "bazel", bazelExecutable)
- if extra_startup_args, ok := infoCmd.Environment.Get("BAZEL_STARTUP_ARGS"); ok {
- infoCmd.Args = append(infoCmd.Args, strings.Fields(extra_startup_args)...)
+ if extraStartupArgs, ok := infoCmd.Environment.Get("BAZEL_STARTUP_ARGS"); ok {
+ infoCmd.Args = append(infoCmd.Args, strings.Fields(extraStartupArgs)...)
}
+ // Obtain the output directory path in the execution root.
infoCmd.Args = append(infoCmd.Args,
"info",
"output_path",