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