kleaf: Add docs about customizing workspace.android-t-qpr1-beta-1_r0.3android-gs-raviole-5.10-android13-qpr1-beta

Add docs to explain how to use a customized
WORKSPACE file in the repo root, though not
recommended.

Bug: 240531712
Test: bazel run docs_server

Change-Id: Iad14a5df226b9e37d9442803aac28ab44bd6e404
Signed-off-by: Yifan Hong <elsk@google.com>

7 files changed, 122 insertions, 3 deletions

diff --git a/kleaf/BUILD.bazel b/kleaf/BUILD.bazel
index 730bc3f..6b0dcd6 100644
--- a/kleaf/BUILD.bazel
+++ b/kleaf/BUILD.bazel
@@ -128,15 +128,20 @@ docs(
         "key_value_repo.bzl",
         "print_debug.bzl",
         "update_source_file.bzl",
+        "workspace.bzl",
+        "workspace_epilog.bzl",
     ],
     default = "kernel.bzl",
     deps = [
         "//build/bazel_common_rules/dist",
         "//build/bazel_common_rules/exec",
+        "//build/bazel_common_rules/workspace",
         "//build/kernel/kleaf/artifact_tests",
         "//build/kernel/kleaf/impl",
+        "@bazel_skylib//:workspace",
         "@bazel_skylib//lib:dicts",
         "@bazel_skylib//lib:paths",
+        "@bazel_skylib//lib:unittest",
         "@bazel_skylib//rules:common_settings",
         "@kernel_toolchain_info//:dict",
     ],
diff --git a/kleaf/README.md b/kleaf/README.md
index 24b533d..5fbb25d 100644
--- a/kleaf/README.md
+++ b/kleaf/README.md
@@ -22,6 +22,8 @@
 
 [Building against downloaded prebuilts](docs/download_prebuilt.md)
 
+[Customize workspace](docs/workspace.md)
+
 [Cheatsheet](docs/cheatsheet.md)
 
 ### Configurations
diff --git a/kleaf/common_kernels.bzl b/kleaf/common_kernels.bzl
index 8aeb866..c4bc96b 100644
--- a/kleaf/common_kernels.bzl
+++ b/kleaf/common_kernels.bzl
@@ -277,9 +277,11 @@ def define_common_kernels(
 
     Args:
       branch: The value of `BRANCH` in `build.config`. If not set, it is loaded
-        from `common/build.config.constants` **in package `//common`**. Hence,
-        if `define_common_kernels()` is called in a different package, it must
-        be supplied.
+        from `common/build.config.constants` **in `//{common_kernel_packgae}`**
+        where `common_kernel_package` is supplied to `define_kleaf_workspace()`
+        in the `WORKSPACE` file. Usually, `common_kernel_package = "common"`.
+        Hence, if `define_common_kernels()` is called in a different package, it
+        must be supplied.
       target_configs: A dictionary, where keys are target names, and
         values are a dictionary of configurations to override the default
         configuration for this target.
diff --git a/kleaf/docs/impl.md b/kleaf/docs/impl.md
index ef339ba..cb20122 100644
--- a/kleaf/docs/impl.md
+++ b/kleaf/docs/impl.md
@@ -18,6 +18,7 @@ Make the following changes to the kernel manifest to support Bazel build.
       any more.
 * Add `tools/bazel` symlink to `build/kernel/kleaf/bazel.sh`
 * Add `WORKSPACE` symlink to `build/kernel/kleaf/bazel.WORKSPACE`
+  * See [workspace.md](workspace.md) for building with a custom workspace.
 * Dependent repositories for Bazel, including:
     * [prebuilts/bazel/linux-x86\_64](https://android.googlesource.com/platform/prebuilts/bazel/linux-x86_64/)
     * [prebuilts/jdk/jdk11](https://android.googlesource.com/platform/prebuilts/jdk/jdk11/)
diff --git a/kleaf/docs/workspace.md b/kleaf/docs/workspace.md
new file mode 100644
index 0000000..241ecad
--- /dev/null
+++ b/kleaf/docs/workspace.md
@@ -0,0 +1,84 @@
+# Customize Workspace
+
+## Using the provided `WORKSPACE` file (recommended)
+
+Usually, the common kernel is checked out to `common/`. In this case, it is
+recommended to use `build/kernel/kleaf/bazel.WORKSPACE` as the `WORKSPACE`
+file.
+
+To make use of the provided `WORKSPACE` file, define `WORKSPACE` in the repo
+manifest as symbolic link that points to `build/kernel/kleaf/bazel.WORKSPACE`.
+
+## Using a customized `WORKSPACE` file
+
+If the common kernel is checked out to a path other than `common`, you need to
+provide a customized `WORKSPACE` file.
+
+The customized `WORKSPACE` file should look similar to
+`build/kernel/kleaf/bazel.WORKSPACE`, except for `define_kleaf_workspace()`
+being called with argument `common_kernel_package` set the path to the common
+kernel source tree.
+
+For example, refer to the following structure in the source tree:
+
+```text
+<repo_root>
+  |- .repo/manifests/default.xml
+  |
+  |- aosp/
+  |  `- <common kernel source tree>
+  |
+  |- build/kernel/kleaf/bazel.WORKSPACE
+  |
+  |- private/tuna/
+  |  |- BUILD.bazel
+  |  `- bazel.WORKSPACE
+  |
+  `- WORKSPACE -> private/tuna/bazel.WORKSPACE
+```
+
+Sample manifest in `.repo/manifests/default.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+    <remote name="aosp" fetch=".."
+            review="https://android-review.googlesource.com/"/>
+    <remote name="device_repo_remote" fetch=".."/>
+
+    <!-- Common kernel is checked out to aosp/ -->
+    <project path="aosp" name="kernel/common" remote="aosp"
+             revision="android-mainline">
+        <!-- links omitted -->
+    </project>
+
+    <project path="build/kernel" name="kernel/build" remote="aosp"
+             revision="android-mainline">
+        <!-- drop the WORKSPACE link -->
+        <!-- linkfile src="kleaf/bazel.WORKSPACE" dest="WORKSPACE" / -->
+        <!-- other links omitted -->
+    </project>
+
+    <!-- device kernel configs & modules -->
+    <project path="private/tuna" name="private/tuna" remote="device_repo_remote"
+             revision="tuna-mainline">
+        <!-- Create the custom WORKSPACE link -->
+        <linkfile src="bazel.WORKSPACE" dest="WORKSPACE"/>
+    </project>
+    <!-- other projects omitted -->
+</manifest>
+```
+
+Sample workspace file in `private/tuna/bazel.WORKSPACE`:
+
+```python
+# Call with common_kernel_package = path to the common kernel source tree
+load("//build/kernel/kleaf:workspace.bzl", "define_kleaf_workspace")
+define_kleaf_workspace(common_kernel_package = "aosp")
+
+# Optional epilog for analysis testing.
+# https://bazel.build/rules/testing
+load("//build/kernel/kleaf:workspace_epilog.bzl",
+     "define_kleaf_workspace_epilog")
+define_kleaf_workspace_epilog()
+```
diff --git a/kleaf/workspace.bzl b/kleaf/workspace.bzl
index 3ff1366..7150a5a 100644
--- a/kleaf/workspace.bzl
+++ b/kleaf/workspace.bzl
@@ -22,6 +22,20 @@ load("//build/kernel/kleaf:download_repo.bzl", "download_artifacts_repo")
 load("//build/kernel/kleaf:key_value_repo.bzl", "key_value_repo")
 
 def define_kleaf_workspace(common_kernel_package = None):
+    """Common macro for defining repositories in a Kleaf workspace.
+
+    **This macro must only be called from `WORKSPACE` or `WORKSPACE.bazel`
+    files, not `BUILD` or `BUILD.bazel` files!**
+
+    If [`define_kleaf_workspace_epilog`](#define_kleaf_workspace_epilog) is
+    called, it must be called after `define_kleaf_workspace` is called.
+
+    Args:
+      common_kernel_package: The path to the common kernel source tree. By
+        default, it is `"common"`.
+
+        Do not provide the trailing `/`.
+    """
     if common_kernel_package == None:
         common_kernel_package = "common"
 
diff --git a/kleaf/workspace_epilog.bzl b/kleaf/workspace_epilog.bzl
index f3dbfa4..28291bc 100644
--- a/kleaf/workspace_epilog.bzl
+++ b/kleaf/workspace_epilog.bzl
@@ -15,4 +15,15 @@
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 def define_kleaf_workspace_epilog():
+    """Optional epilog macro for defining repositories in a Kleaf workspace.
+
+    **This macro must only be called from `WORKSPACE` or `WORKSPACE.bazel`
+    files, not `BUILD` or `BUILD.bazel` files!**
+
+    The epilog macro is needed if you are running
+    [Bazel analysis tests](https://bazel.build/rules/testing).
+
+    If called, it must be called after
+    [`define_kleaf_workspace`](#define_kleaf_workspace) is called.
+    """
     bazel_skylib_workspace()