deapexer.go 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  1. // Copyright (C) 2021 The Android Open Source Project
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. package android
  15. import (
  16. "strings"
  17. "github.com/google/blueprint"
  18. )
  19. // Provides support for interacting with the `deapexer` module to which a `prebuilt_apex` module
  20. // will delegate the work to export files from a prebuilt '.apex` file.
  21. //
  22. // The actual processing that is done is quite convoluted but it is all about combining information
  23. // from multiple different sources in order to allow a prebuilt module to use a file extracted from
  24. // an apex file. As follows:
  25. //
  26. // 1. A prebuilt module, e.g. prebuilt_bootclasspath_fragment or java_import needs to use a file
  27. // from a prebuilt_apex/apex_set. It knows the path of the file within the apex but does not know
  28. // where the apex file is or what apex to use.
  29. //
  30. // 2. The connection between the prebuilt module and the prebuilt_apex/apex_set is created through
  31. // use of an exported_... property on the latter. That causes four things to occur:
  32. // a. A `deapexer` mopdule is created by the prebuilt_apex/apex_set to extract files from the
  33. // apex file.
  34. // b. A dependency is added from the prebuilt_apex/apex_set modules onto the prebuilt modules
  35. // listed in those properties.
  36. // c. An APEX variant is created for each of those prebuilt modules.
  37. // d. A dependency is added from the prebuilt modules to the `deapexer` module.
  38. //
  39. // 3. The prebuilt_apex/apex_set modules do not know which files are available in the apex file.
  40. // That information could be specified on the prebuilt_apex/apex_set modules but without
  41. // automated generation of those modules it would be expensive to maintain. So, instead they
  42. // obtain that information from the prebuilt modules. They do not know what files are actually in
  43. // the apex file either but they know what files they need from it. So, the
  44. // prebuilt_apex/apex_set modules obtain the files that should be in the apex file from those
  45. // modules and then pass those onto the `deapexer` module.
  46. //
  47. // 4. The `deapexer` module's ninja rule extracts all the files from the apex file into an output
  48. // directory and checks that all the expected files are there. The expected files are declared as
  49. // the outputs of the ninja rule so they are available to other modules.
  50. //
  51. // 5. The prebuilt modules then retrieve the paths to the files that they needed from the `deapexer`
  52. // module.
  53. //
  54. // The files that are passed to `deapexer` and those that are passed back have a unique identifier
  55. // that links them together. e.g. If the `deapexer` is passed something like this:
  56. // javalib/core-libart.jar -> javalib/core-libart.jar
  57. // it will return something like this:
  58. // javalib/core-libart.jar -> out/soong/.....deapexer.../javalib/core-libart.jar
  59. //
  60. // The reason why the `deapexer` module is separate from the prebuilt_apex/apex_set is to avoid
  61. // cycles. e.g.
  62. // prebuilt_apex "com.android.art" depends upon java_import "core-libart":
  63. // This is so it can create an APEX variant of the latter and obtain information about the
  64. // files that it needs from the apex file.
  65. // java_import "core-libart" depends upon `deapexer` module:
  66. // This is so it can retrieve the paths to the files it needs.
  67. // The information exported by the `deapexer` module, access it using `DeapxerInfoProvider`.
  68. type DeapexerInfo struct {
  69. apexModuleName string
  70. // map from the name of an exported file from a prebuilt_apex to the path to that file. The
  71. // exported file name is the apex relative path, e.g. javalib/core-libart.jar.
  72. //
  73. // See Prebuilt.ApexInfoMutator for more information.
  74. exports map[string]WritablePath
  75. }
  76. // ApexModuleName returns the name of the APEX module that provided the info.
  77. func (i DeapexerInfo) ApexModuleName() string {
  78. return i.apexModuleName
  79. }
  80. // PrebuiltExportPath provides the path, or nil if not available, of a file exported from the
  81. // prebuilt_apex that created this ApexInfo.
  82. //
  83. // The exported file is identified by the apex relative path, e.g. "javalib/core-libart.jar".
  84. //
  85. // See apex/deapexer.go for more information.
  86. func (i DeapexerInfo) PrebuiltExportPath(apexRelativePath string) WritablePath {
  87. path := i.exports[apexRelativePath]
  88. return path
  89. }
  90. // Provider that can be used from within the `GenerateAndroidBuildActions` of a module that depends
  91. // on a `deapexer` module to retrieve its `DeapexerInfo`.
  92. var DeapexerProvider = blueprint.NewProvider(DeapexerInfo{})
  93. // NewDeapexerInfo creates and initializes a DeapexerInfo that is suitable
  94. // for use with a prebuilt_apex module.
  95. //
  96. // See apex/deapexer.go for more information.
  97. func NewDeapexerInfo(apexModuleName string, exports map[string]WritablePath) DeapexerInfo {
  98. return DeapexerInfo{
  99. apexModuleName: apexModuleName,
  100. exports: exports,
  101. }
  102. }
  103. type deapexerTagStruct struct {
  104. blueprint.BaseDependencyTag
  105. }
  106. // Mark this tag so dependencies that use it are excluded from APEX contents.
  107. func (t deapexerTagStruct) ExcludeFromApexContents() {}
  108. var _ ExcludeFromApexContentsTag = DeapexerTag
  109. // A tag that is used for dependencies on the `deapexer` module.
  110. var DeapexerTag = deapexerTagStruct{}
  111. // RequiredFilesFromPrebuiltApex must be implemented by modules that require files to be exported
  112. // from a prebuilt_apex/apex_set.
  113. type RequiredFilesFromPrebuiltApex interface {
  114. // RequiredFilesFromPrebuiltApex returns a list of the file paths (relative to the root of the
  115. // APEX's contents) that the implementing module requires from within a prebuilt .apex file.
  116. //
  117. // For each file path this will cause the file to be extracted out of the prebuilt .apex file, and
  118. // the path to the extracted file will be stored in the DeapexerInfo using the APEX relative file
  119. // path as the key, The path can then be retrieved using the PrebuiltExportPath(key) method.
  120. RequiredFilesFromPrebuiltApex(ctx BaseModuleContext) []string
  121. }
  122. // Marker interface that identifies dependencies on modules that may require files from a prebuilt
  123. // apex.
  124. type RequiresFilesFromPrebuiltApexTag interface {
  125. blueprint.DependencyTag
  126. // Method that differentiates this interface from others.
  127. RequiresFilesFromPrebuiltApex()
  128. }
  129. // FindDeapexerProviderForModule searches through the direct dependencies of the current context
  130. // module for a DeapexerTag dependency and returns its DeapexerInfo. If a single nonambiguous
  131. // deapexer module isn't found then errors are reported with ctx.ModuleErrorf and nil is returned.
  132. func FindDeapexerProviderForModule(ctx ModuleContext) *DeapexerInfo {
  133. var di *DeapexerInfo
  134. ctx.VisitDirectDepsWithTag(DeapexerTag, func(m Module) {
  135. c := ctx.OtherModuleProvider(m, DeapexerProvider).(DeapexerInfo)
  136. p := &c
  137. if di != nil {
  138. // If two DeapexerInfo providers have been found then check if they are
  139. // equivalent. If they are then use the selected one, otherwise fail.
  140. if selected := equivalentDeapexerInfoProviders(di, p); selected != nil {
  141. di = selected
  142. return
  143. }
  144. ctx.ModuleErrorf("Multiple installable prebuilt APEXes provide ambiguous deapexers: %s and %s",
  145. di.ApexModuleName(), p.ApexModuleName())
  146. }
  147. di = p
  148. })
  149. if di != nil {
  150. return di
  151. }
  152. ai := ctx.Provider(ApexInfoProvider).(ApexInfo)
  153. ctx.ModuleErrorf("No prebuilt APEX provides a deapexer module for APEX variant %s", ai.ApexVariationName)
  154. return nil
  155. }
  156. // removeCompressedApexSuffix removes the _compressed suffix from the name if present.
  157. func removeCompressedApexSuffix(name string) string {
  158. return strings.TrimSuffix(name, "_compressed")
  159. }
  160. // equivalentDeapexerInfoProviders checks to make sure that the two DeapexerInfo structures are
  161. // equivalent.
  162. //
  163. // At the moment <x> and <x>_compressed APEXes are treated as being equivalent.
  164. //
  165. // If they are not equivalent then this returns nil, otherwise, this returns the DeapexerInfo that
  166. // should be used by the build, which is always the uncompressed one. That ensures that the behavior
  167. // of the build is not dependent on which prebuilt APEX is visited first.
  168. func equivalentDeapexerInfoProviders(p1 *DeapexerInfo, p2 *DeapexerInfo) *DeapexerInfo {
  169. n1 := removeCompressedApexSuffix(p1.ApexModuleName())
  170. n2 := removeCompressedApexSuffix(p2.ApexModuleName())
  171. // If the names don't match then they are not equivalent.
  172. if n1 != n2 {
  173. return nil
  174. }
  175. // Select the uncompressed APEX.
  176. if n1 == removeCompressedApexSuffix(n1) {
  177. return p1
  178. } else {
  179. return p2
  180. }
  181. }