Add a doc about `dex_preopt_check`.
The doc lists some possible causes of a `dex_preopt_check` error, which
can be useful for developers to understand how to debug the error.
Bug: 232542678
Test: m nothing
Change-Id: I2e9868a6a470e41e8c3743c045e0cf4cf7367efa
diff --git a/core/OWNERS b/core/OWNERS
index dae34ff..980186c 100644
--- a/core/OWNERS
+++ b/core/OWNERS
@@ -1,4 +1,4 @@
-per-file dex_preopt*.* = ngeoffray@google.com,skvadrik@google.com
+per-file *dex_preopt*.* = ngeoffray@google.com,skvadrik@google.com
per-file verify_uses_libraries.sh = ngeoffray@google.com,skvadrik@google.com
# For version updates
diff --git a/core/tasks/README.dex_preopt_check.md b/core/tasks/README.dex_preopt_check.md
new file mode 100644
index 0000000..b0baa9e
--- /dev/null
+++ b/core/tasks/README.dex_preopt_check.md
@@ -0,0 +1,43 @@
+# `dex_preopt_check`
+
+`dex_preopt_check` is a build-time check to make sure that all system server
+jars are dexpreopted. When the check fails, you will see the following error
+message:
+
+```
+FAILED:
+build/make/core/tasks/dex_preopt_check.mk:13: warning: Missing compilation artifacts. Dexpreopting is not working for some system server jars
+Offending entries:
+```
+
+Possible causes are:
+
+1. There is an APEX/SDK mismatch. (E.g., the APEX is built from source while
+ the SDK is built from prebuilt.)
+
+1. The `systemserverclasspath_fragment` is not added as
+ `systemserverclasspath_fragments` of the corresponding `apex` module, or not
+ added as `exported_systemserverclasspath_fragments` of the corresponding
+ `prebuilt_apex`/`apex_set` module when building from prebuilt.
+
+1. The expected version of the system server java library is not preferred.
+ (E.g., the `java_import` module has `prefer: false` when building from
+ prebuilt.)
+
+1. Dexpreopting is disabled for the system server java library. This can be due
+ to various reasons including but not limited to:
+
+ - The java library has `dex_preopt: { enabled: false }` in the Android.bp
+ file.
+
+ - The java library is listed in `DEXPREOPT_DISABLED_MODULES` in a Makefile.
+
+ - The java library is missing `installable: true` in the Android.bp
+ file when building from source.
+
+ - Sanitizer is enabled.
+
+1. `PRODUCT_SYSTEM_SERVER_JARS`, `PRODUCT_APEX_SYSTEM_SERVER_JARS`,
+ `PRODUCT_STANDALONE_SYSTEM_SERVER_JARS`, or
+ `PRODUCT_APEX_STANDALONE_SYSTEM_SERVER_JARS` has an extra entry that is not
+ needed by the product.
diff --git a/core/tasks/dex_preopt_check.mk b/core/tasks/dex_preopt_check.mk
index bfa1ec5..5fd60c8 100644
--- a/core/tasks/dex_preopt_check.mk
+++ b/core/tasks/dex_preopt_check.mk
@@ -12,7 +12,8 @@
ifneq (,$(filter services,$(PRODUCT_PACKAGES)))
$(call maybe-print-list-and-error,\
$(filter-out $(ALL_DEFAULT_INSTALLED_MODULES),$(DEXPREOPT_SYSTEMSERVER_ARTIFACTS)),\
- Missing compilation artifacts. Dexpreopting is not working for some system server jars \
+ Missing compilation artifacts. Dexpreopting is not working for some system server jars. See \
+ https://cs.android.com/android/platform/superproject/+/master:build/make/core/tasks/README.dex_preopt_check.md \
)
endif
endif