diff --git a/java/hiddenapi.go b/java/hiddenapi.go index 71f1e576d..c7dac8fec 100644 --- a/java/hiddenapi.go +++ b/java/hiddenapi.go @@ -28,10 +28,40 @@ var hiddenAPIGenerateCSVRule = pctx.AndroidStaticRule("hiddenAPIGenerateCSV", bl }, "outFlag", "stubAPIFlags") type hiddenAPI struct { - bootDexJarPath android.Path - flagsCSVPath android.Path - indexCSVPath android.Path + // The path to the dex jar that is in the boot class path. If this is nil then the associated + // module is not a boot jar, but could be one of the -hiddenapi modules that provide additional + // annotations for the boot dex jar but which do not actually provide a boot dex jar + // themselves. + bootDexJarPath android.Path + + // The path to the CSV file that contains mappings from Java signature to various flags derived + // from annotations in the source, e.g. whether it is public or the sdk version above which it + // can no longer be used. + // + // It is created by the Class2NonSdkList tool which processes the .class files in the class + // implementation jar looking for UnsupportedAppUsage and CovariantReturnType annotations. The + // tool also consumes the hiddenAPISingletonPathsStruct.stubFlags file in order to perform + // consistency checks on the information in the annotations and to filter out bridge methods + // that are already part of the public API. + flagsCSVPath android.Path + + // The path to the CSV file that contains mappings from Java signature to the value of properties + // specified on UnsupportedAppUsage annotations in the source. + // + // Like the flagsCSVPath file this is also created by the Class2NonSdkList in the same way. + // Although the two files could potentially be created in a single invocation of the + // Class2NonSdkList at the moment they are created using their own invocation, with the behavior + // being determined by the property that is used. metadataCSVPath android.Path + + // The path to the CSV file that contains mappings from Java signature to source location + // information. + // + // It is created by the merge_csv tool which processes the class implementation jar, extracting + // all the files ending in .uau (which are CSV files) and merges them together. The .uau files are + // created by the unsupported app usage annotation processor during compilation of the class + // implementation jar. + indexCSVPath android.Path } func (h *hiddenAPI) flagsCSV() android.Path { diff --git a/java/hiddenapi_singleton.go b/java/hiddenapi_singleton.go index 4bd255cbf..ccb874506 100644 --- a/java/hiddenapi_singleton.go +++ b/java/hiddenapi_singleton.go @@ -28,9 +28,64 @@ func init() { } type hiddenAPISingletonPathsStruct struct { - flags android.OutputPath - index android.OutputPath - metadata android.OutputPath + // The path to the CSV file that contains the flags that will be encoded into the dex boot jars. + // + // It is created by the generate_hiddenapi_lists.py tool that is passed the stubFlags along with + // a number of additional files that are used to augment the information in the stubFlags with + // manually curated data. + flags android.OutputPath + + // The path to the CSV index file that contains mappings from Java signature to source location + // information for all Java elements annotated with the UnsupportedAppUsage annotation in the + // source of all the boot jars. + // + // It is created by the merge_csv tool which merges all the hiddenAPI.indexCSVPath files that have + // been created by the rest of the build. That includes the index files generated for + // -hiddenapi modules. + index android.OutputPath + + // The path to the CSV metadata file that contains mappings from Java signature to the value of + // properties specified on UnsupportedAppUsage annotations in the source of all the boot jars. + // + // It is created by the merge_csv tool which merges all the hiddenAPI.metadataCSVPath files that + // have been created by the rest of the build. That includes the metadata files generated for + // -hiddenapi modules. + metadata android.OutputPath + + // The path to the CSV metadata file that contains mappings from Java signature to flags obtained + // from the public, system and test API stubs. + // + // This is created by the hiddenapi tool which is given dex files for the public, system and test + // API stubs (including product specific stubs) along with dex boot jars, so does not include + // -hiddenapi modules. For each API surface (i.e. public, system, test) it records which + // members in the dex boot jars match a member in the dex stub jars for that API surface and then + // outputs a file containing the signatures of all members in the dex boot jars along with the + // flags that indicate which API surface it belongs, if any. + // + // e.g. a dex member that matches a member in the public dex stubs would have flags + // "public-api,system-api,test-api" set (as system and test are both supersets of public). A dex + // member that didn't match a member in any of the dex stubs is still output it just has an empty + // set of flags. + // + // The notion of matching is quite complex, it is not restricted to just exact matching but also + // follows the Java inheritance rules. e.g. if a method is public then all overriding/implementing + // methods are also public. If an interface method is public and a class inherits an + // implementation of that method from a super class then that super class method is also public. + // That ensures that any method that can be called directly by an App through a public method is + // visible to that App. + // + // Propagating the visibility of members across the inheritance hierarchy at build time will cause + // problems when modularizing and unbundling as it that propagation can cross module boundaries. + // e.g. Say that a private framework class implements a public interface and inherits an + // implementation of one of its methods from a core platform ART class. In that case the ART + // implementation method needs to be marked as public which requires the build to have access to + // the framework implementation classes at build time. The work to rectify this is being tracked + // at http://b/178693149. + // + // This file (or at least those items marked as being in the public-api) is used by hiddenapi when + // creating the metadata and flags for the individual modules in order to perform consistency + // checks and filter out bridge methods that are part of the public API. The latter relies on the + // propagation of visibility across the inheritance hierarchy. stubFlags android.OutputPath }