Document bootImageConfig and bootImageVariant structs
Add warnings to the structs to explain how they are supposed to be used
and deprecate fields that are used incorrectly.
Bug: 245956352
Test: m nothing
Change-Id: I090698287b96fd37102b88beb5d7252977bddc54
diff --git a/java/dexpreopt_bootjars.go b/java/dexpreopt_bootjars.go
index 4e416fc..62386e3 100644
--- a/java/dexpreopt_bootjars.go
+++ b/java/dexpreopt_bootjars.go
@@ -228,6 +228,11 @@
}
// Target-independent description of a boot image.
+//
+// WARNING: All fields in this struct should be initialized in the genBootImageConfigs function.
+// Failure to do so can lead to data races if there is no synchronization enforced ordering between
+// the writer and the reader. Fields which break this rule are marked as deprecated and should be
+// removed and replaced with something else, e.g. providers.
type bootImageConfig struct {
// If this image is an extension, the image that it extends.
extends *bootImageConfig
@@ -268,12 +273,18 @@
zip android.WritablePath
// Rules which should be used in make to install the outputs.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
profileInstalls android.RuleBuilderInstalls
// Path to the license metadata file for the module that built the profile.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
profileLicenseMetadataFile android.OptionalPath
// Path to the image profile file on host (or empty, if profile is not generated).
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
profilePathOnHost android.Path
// Target-dependent fields.
@@ -284,6 +295,8 @@
}
// Target-dependent description of a boot image.
+//
+// WARNING: The warning comment on bootImageConfig applies here too.
type bootImageVariant struct {
*bootImageConfig
@@ -314,14 +327,28 @@
primaryImagesDeps android.Paths
// Rules which should be used in make to install the outputs on host.
- installs android.RuleBuilderInstalls
- vdexInstalls android.RuleBuilderInstalls
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
+ installs android.RuleBuilderInstalls
+
+ // Rules which should be used in make to install the vdex outputs on host.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
+ vdexInstalls android.RuleBuilderInstalls
+
+ // Rules which should be used in make to install the unstripped outputs on host.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
unstrippedInstalls android.RuleBuilderInstalls
// Rules which should be used in make to install the outputs on device.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
deviceInstalls android.RuleBuilderInstalls
// Path to the license metadata file for the module that built the image.
+ //
+ // Deprecated: Not initialized correctly, see struct comment.
licenseMetadataFile android.OptionalPath
}