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 "github.com/google/blueprint" 19) 20 21// Provides support for interacting with the `deapexer` module to which a `prebuilt_apex` module 22// will delegate the work to export files from a prebuilt '.apex` file. 23// 24// The actual processing that is done is quite convoluted but it is all about combining information 25// from multiple different sources in order to allow a prebuilt module to use a file extracted from 26// an apex file. As follows: 27// 28// 1. A prebuilt module, e.g. prebuilt_bootclasspath_fragment or java_import needs to use a file 29// from a prebuilt_apex/apex_set. It knows the path of the file within the apex but does not know 30// where the apex file is or what apex to use. 31// 32// 2. The connection between the prebuilt module and the prebuilt_apex/apex_set is created through 33// use of an exported_... property on the latter. That causes four things to occur: 34// a. A `deapexer` mopdule is created by the prebuilt_apex/apex_set to extract files from the 35// apex file. 36// b. A dependency is added from the prebuilt_apex/apex_set modules onto the prebuilt modules 37// listed in those properties. 38// c. An APEX variant is created for each of those prebuilt modules. 39// d. A dependency is added from the prebuilt modules to the `deapexer` module. 40// 41// 3. The prebuilt_apex/apex_set modules do not know which files are available in the apex file. 42// That information could be specified on the prebuilt_apex/apex_set modules but without 43// automated generation of those modules it would be expensive to maintain. So, instead they 44// obtain that information from the prebuilt modules. They do not know what files are actually in 45// the apex file either but they know what files they need from it. So, the 46// prebuilt_apex/apex_set modules obtain the files that should be in the apex file from those 47// modules and then pass those onto the `deapexer` module. 48// 49// 4. The `deapexer` module's ninja rule extracts all the files from the apex file into an output 50// directory and checks that all the expected files are there. The expected files are declared as 51// the outputs of the ninja rule so they are available to other modules. 52// 53// 5. The prebuilt modules then retrieve the paths to the files that they needed from the `deapexer` 54// module. 55// 56// The files that are passed to `deapexer` and those that are passed back have a unique identifier 57// that links them together. e.g. If the `deapexer` is passed something like this: 58// javalib/core-libart.jar -> javalib/core-libart.jar 59// it will return something like this: 60// javalib/core-libart.jar -> out/soong/.....deapexer.../javalib/core-libart.jar 61// 62// The reason why the `deapexer` module is separate from the prebuilt_apex/apex_set is to avoid 63// cycles. e.g. 64// prebuilt_apex "com.android.art" depends upon java_import "core-libart": 65// This is so it can create an APEX variant of the latter and obtain information about the 66// files that it needs from the apex file. 67// java_import "core-libart" depends upon `deapexer` module: 68// This is so it can retrieve the paths to the files it needs. 69 70// The information exported by the `deapexer` module, access it using `DeapxerInfoProvider`. 71type DeapexerInfo struct { 72 // map from the name of an exported file from a prebuilt_apex to the path to that file. The 73 // exported file name is the apex relative path, e.g. javalib/core-libart.jar. 74 // 75 // See Prebuilt.ApexInfoMutator for more information. 76 exports map[string]Path 77} 78 79// PrebuiltExportPath provides the path, or nil if not available, of a file exported from the 80// prebuilt_apex that created this ApexInfo. 81// 82// The exported file is identified by the apex relative path, e.g. "javalib/core-libart.jar". 83// 84// See apex/deapexer.go for more information. 85func (i DeapexerInfo) PrebuiltExportPath(apexRelativePath string) Path { 86 path := i.exports[apexRelativePath] 87 return path 88} 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`. 92var DeapexerProvider = blueprint.NewProvider(DeapexerInfo{}) 93 94// NewDeapexerInfo creates and initializes a DeapexerInfo that is suitable 95// for use with a prebuilt_apex module. 96// 97// See apex/deapexer.go for more information. 98func NewDeapexerInfo(exports map[string]Path) DeapexerInfo { 99 return DeapexerInfo{ 100 exports: exports, 101 } 102} 103 104type deapexerTagStruct struct { 105 blueprint.BaseDependencyTag 106} 107 108// Mark this tag so dependencies that use it are excluded from APEX contents. 109func (t deapexerTagStruct) ExcludeFromApexContents() {} 110 111var _ ExcludeFromApexContentsTag = DeapexerTag 112 113// A tag that is used for dependencies on the `deapexer` module. 114var DeapexerTag = deapexerTagStruct{} 115 116// RequiredFilesFromPrebuiltApex must be implemented by modules that require files to be exported 117// from a prebuilt_apex/apex_set. 118type RequiredFilesFromPrebuiltApex interface { 119 // RequiredFilesFromPrebuiltApex returns a list of the file paths (relative to the root of the 120 // APEX's contents) that the implementing module requires from within a prebuilt .apex file. 121 // 122 // For each file path this will cause the file to be extracted out of the prebuilt .apex file, and 123 // the path to the extracted file will be stored in the DeapexerInfo using the APEX relative file 124 // path as the key, The path can then be retrieved using the PrebuiltExportPath(key) method. 125 RequiredFilesFromPrebuiltApex(ctx BaseModuleContext) []string 126} 127 128// Marker interface that identifies dependencies on modules that may require files from a prebuilt 129// apex. 130type RequiresFilesFromPrebuiltApexTag interface { 131 blueprint.DependencyTag 132 133 // Method that differentiates this interface from others. 134 RequiresFilesFromPrebuiltApex() 135} 136