From a8df7e1c5bfce9115293ddd3bee9682c3c2c5728 Mon Sep 17 00:00:00 2001 From: Paul Duffin Date: Tue, 4 Oct 2022 15:21:47 +0100 Subject: [PATCH] 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 --- java/dexpreopt_bootjars.go | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/java/dexpreopt_bootjars.go b/java/dexpreopt_bootjars.go index 4e416fc82..62386e35f 100644 --- a/java/dexpreopt_bootjars.go +++ b/java/dexpreopt_bootjars.go @@ -228,6 +228,11 @@ func init() { } // 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 @@ type bootImageConfig struct { 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 @@ type bootImageConfig struct { } // Target-dependent description of a boot image. +// +// WARNING: The warning comment on bootImageConfig applies here too. type bootImageVariant struct { *bootImageConfig @@ -314,14 +327,28 @@ type bootImageVariant struct { 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 }