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