From 743513c83072bc0e5f6cc3b4b0567d1e53afeb62 Mon Sep 17 00:00:00 2001
From: Martin Stjernholm <mast@google.com>
Date: Mon, 5 Jul 2021 20:53:57 +0100
Subject: [PATCH] Document how APEXes are identified in the boot jar variables.

Test: n/a - comment changes only
Bug: 191269918
Change-Id: Ib82ee24be13274051590be5e207883e4fbc9e6ae
---
 core/envsetup.mk |  7 +++++--
 core/product.mk  | 17 ++++++++++++-----
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/core/envsetup.mk b/core/envsetup.mk
index 8c25086a41..bb1aa1edab 100644
--- a/core/envsetup.mk
+++ b/core/envsetup.mk
@@ -293,8 +293,11 @@ endef
 #################################################################
 # Set up minimal BOOTCLASSPATH list of jars to build/execute
 # java code with dalvikvm/art.
-# Jars present in the ART apex. These should match exactly the list of
-# Java libraries in the ART apex build rule.
+# Jars present in the ART apex. These should match exactly the list of Java
+# libraries in art-bootclasspath-fragment. The APEX variant name
+# (com.android.art) is the same regardless which Soong module provides the ART
+# APEX. See the long comment in build/soong/java/dexprepopt_bootjars.go for
+# details.
 ART_APEX_JARS := \
     com.android.art:core-oj \
     com.android.art:core-libart \
diff --git a/core/product.mk b/core/product.mk
index 015fe44ba9..7e8445e3d0 100644
--- a/core/product.mk
+++ b/core/product.mk
@@ -213,12 +213,18 @@ _product_list_vars += PRODUCT_RESTRICT_VENDOR_FILES
 # The list of product-specific kernel header dirs
 _product_list_vars += PRODUCT_VENDOR_KERNEL_HEADERS
 
-# A list of module names of BOOTCLASSPATH (jar files)
+# A list of module names in BOOTCLASSPATH (jar files). Each module may be
+# prefixed with "<apex>:", which identifies the APEX that provides it. APEXes
+# are identified by their "variant" names, i.e. their `apex_name` values in
+# Soong, which default to the `name` values. The prefix can also be "platform:"
+# or "system_ext:", and defaults to "platform:" if left out. See the long
+# comment in build/soong/java/dexprepopt_bootjars.go for details.
 _product_list_vars += PRODUCT_BOOT_JARS
 
-# A list of extra BOOTCLASSPATH jars (to be appended after common jars).
-# Products that include device-specific makefiles before AOSP makefiles should use this
-# instead of PRODUCT_BOOT_JARS, so that device-specific jars go after common jars.
+# A list of extra BOOTCLASSPATH jars (to be appended after common jars),
+# following the same format as PRODUCT_BOOT_JARS. Products that include
+# device-specific makefiles before AOSP makefiles should use this instead of
+# PRODUCT_BOOT_JARS, so that device-specific jars go after common jars.
 _product_list_vars += PRODUCT_BOOT_JARS_EXTRA
 
 _product_single_value_vars += PRODUCT_SUPPORTS_BOOT_SIGNER
@@ -389,7 +395,8 @@ _product_single_value_vars += PRODUCT_BUILD_VENDOR_BOOT_IMAGE
 _product_single_value_vars += PRODUCT_BUILD_VBMETA_IMAGE
 _product_single_value_vars += PRODUCT_BUILD_SUPER_EMPTY_IMAGE
 
-# List of boot jars delivered via apex
+# List of boot jars delivered via updatable APEXes, following the same format as
+# PRODUCT_BOOT_JARS.
 _product_list_vars += PRODUCT_UPDATABLE_BOOT_JARS
 
 # If set, device uses virtual A/B.