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 exports map[string]WritablePath 79 80 // name of the java libraries exported from the apex 81 // e.g. core-libart 82 exportedModuleNames []string 83 84 // name of the java libraries exported from the apex that should be dexpreopt'd with the .prof 85 // file embedded in the apex 86 dexpreoptProfileGuidedExportedModuleNames []string 87} 88 89// ApexModuleName returns the name of the APEX module that provided the info. 90func (i DeapexerInfo) ApexModuleName() string { 91 return i.apexModuleName 92} 93 94// PrebuiltExportPath provides the path, or nil if not available, of a file exported from the 95// prebuilt_apex that created this ApexInfo. 96// 97// The exported file is identified by the apex relative path, e.g. "javalib/core-libart.jar". 98// 99// See apex/deapexer.go for more information. 100func (i DeapexerInfo) PrebuiltExportPath(apexRelativePath string) WritablePath { 101 path := i.exports[apexRelativePath] 102 return path 103} 104 105func (i DeapexerInfo) GetExportedModuleNames() []string { 106 return i.exportedModuleNames 107} 108 109// NewDeapexerInfo creates and initializes a DeapexerInfo that is suitable 110// for use with a prebuilt_apex module. 111// 112// See apex/deapexer.go for more information. 113func NewDeapexerInfo(apexModuleName string, exports map[string]WritablePath, moduleNames []string) DeapexerInfo { 114 return DeapexerInfo{ 115 apexModuleName: apexModuleName, 116 exports: exports, 117 exportedModuleNames: moduleNames, 118 } 119} 120 121func (i *DeapexerInfo) GetDexpreoptProfileGuidedExportedModuleNames() []string { 122 return i.dexpreoptProfileGuidedExportedModuleNames 123} 124 125func (i *DeapexerInfo) AddDexpreoptProfileGuidedExportedModuleNames(names ...string) { 126 i.dexpreoptProfileGuidedExportedModuleNames = append(i.dexpreoptProfileGuidedExportedModuleNames, names...) 127} 128 129type deapexerTagStruct struct { 130 blueprint.BaseDependencyTag 131} 132 133// Mark this tag so dependencies that use it are excluded from APEX contents. 134func (t deapexerTagStruct) ExcludeFromApexContents() {} 135 136var _ ExcludeFromApexContentsTag = DeapexerTag 137 138// A tag that is used for dependencies on the `deapexer` module. 139var DeapexerTag = deapexerTagStruct{} 140 141// RequiredFilesFromPrebuiltApex must be implemented by modules that require files to be exported 142// from a prebuilt_apex/apex_set. 143type RequiredFilesFromPrebuiltApex interface { 144 // RequiredFilesFromPrebuiltApex returns a list of the file paths (relative to the root of the 145 // APEX's contents) that the implementing module requires from within a prebuilt .apex file. 146 // 147 // For each file path this will cause the file to be extracted out of the prebuilt .apex file, and 148 // the path to the extracted file will be stored in the DeapexerInfo using the APEX relative file 149 // path as the key, The path can then be retrieved using the PrebuiltExportPath(key) method. 150 RequiredFilesFromPrebuiltApex(ctx BaseModuleContext) []string 151 152 // Returns true if a transitive dependency of an apex should use a .prof file to guide dexpreopt 153 UseProfileGuidedDexpreopt() bool 154} 155 156// Marker interface that identifies dependencies on modules that may require files from a prebuilt 157// apex. 158type RequiresFilesFromPrebuiltApexTag interface { 159 blueprint.DependencyTag 160 161 // Method that differentiates this interface from others. 162 RequiresFilesFromPrebuiltApex() 163} 164 165// removeCompressedApexSuffix removes the _compressed suffix from the name if present. 166func removeCompressedApexSuffix(name string) string { 167 return strings.TrimSuffix(name, "_compressed") 168} 169 170// equivalentDeapexerInfoProviders checks to make sure that the two DeapexerInfo structures are 171// equivalent. 172// 173// At the moment <x> and <x>_compressed APEXes are treated as being equivalent. 174// 175// If they are not equivalent then this returns nil, otherwise, this returns the DeapexerInfo that 176// should be used by the build, which is always the uncompressed one. That ensures that the behavior 177// of the build is not dependent on which prebuilt APEX is visited first. 178func equivalentDeapexerInfoProviders(p1 *DeapexerInfo, p2 *DeapexerInfo) *DeapexerInfo { 179 n1 := removeCompressedApexSuffix(p1.ApexModuleName()) 180 n2 := removeCompressedApexSuffix(p2.ApexModuleName()) 181 182 // If the names don't match then they are not equivalent. 183 if n1 != n2 { 184 return nil 185 } 186 187 // Select the uncompressed APEX. 188 if n1 == removeCompressedApexSuffix(n1) { 189 return p1 190 } else { 191 return p2 192 } 193} 194