blob: 6a93f6087c9af3b0253c1c499bdb6a8da4d05393 [file] [log] [blame]
Paul Duffin064b70c2020-11-02 17:32:38 +00001// 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 (
Paul Duffin5556c5f2022-06-09 17:32:21 +000018 "strings"
19
Paul Duffin064b70c2020-11-02 17:32:38 +000020 "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.
Paul Duffin5466a362021-06-07 10:25:31 +010025//
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:
Paul Duffinb4bbf2c2021-06-17 15:59:07 +010060// javalib/core-libart.jar -> javalib/core-libart.jar
Paul Duffin5466a362021-06-07 10:25:31 +010061// it will return something like this:
Paul Duffinb4bbf2c2021-06-17 15:59:07 +010062// javalib/core-libart.jar -> out/soong/.....deapexer.../javalib/core-libart.jar
Paul Duffin5466a362021-06-07 10:25:31 +010063//
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.
Paul Duffin064b70c2020-11-02 17:32:38 +000071
72// The information exported by the `deapexer` module, access it using `DeapxerInfoProvider`.
73type DeapexerInfo struct {
Martin Stjernholm44825602021-09-17 01:44:12 +010074 apexModuleName string
75
Paul Duffin064b70c2020-11-02 17:32:38 +000076 // map from the name of an exported file from a prebuilt_apex to the path to that file. The
Paul Duffinb4bbf2c2021-06-17 15:59:07 +010077 // exported file name is the apex relative path, e.g. javalib/core-libart.jar.
Paul Duffin064b70c2020-11-02 17:32:38 +000078 //
79 // See Prebuilt.ApexInfoMutator for more information.
Jiakai Zhang204356f2021-09-09 08:12:46 +000080 exports map[string]WritablePath
Paul Duffin064b70c2020-11-02 17:32:38 +000081}
82
Martin Stjernholm44825602021-09-17 01:44:12 +010083// ApexModuleName returns the name of the APEX module that provided the info.
84func (i DeapexerInfo) ApexModuleName() string {
85 return i.apexModuleName
86}
87
Paul Duffin064b70c2020-11-02 17:32:38 +000088// PrebuiltExportPath provides the path, or nil if not available, of a file exported from the
89// prebuilt_apex that created this ApexInfo.
90//
Paul Duffinb4bbf2c2021-06-17 15:59:07 +010091// The exported file is identified by the apex relative path, e.g. "javalib/core-libart.jar".
Paul Duffin064b70c2020-11-02 17:32:38 +000092//
93// See apex/deapexer.go for more information.
Jiakai Zhang204356f2021-09-09 08:12:46 +000094func (i DeapexerInfo) PrebuiltExportPath(apexRelativePath string) WritablePath {
Paul Duffinb4bbf2c2021-06-17 15:59:07 +010095 path := i.exports[apexRelativePath]
Paul Duffin064b70c2020-11-02 17:32:38 +000096 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.
Martin Stjernholm44825602021-09-17 01:44:12 +0100107func NewDeapexerInfo(apexModuleName string, exports map[string]WritablePath) DeapexerInfo {
Paul Duffin064b70c2020-11-02 17:32:38 +0000108 return DeapexerInfo{
Martin Stjernholm44825602021-09-17 01:44:12 +0100109 apexModuleName: apexModuleName,
110 exports: exports,
Paul Duffin064b70c2020-11-02 17:32:38 +0000111 }
112}
113
114type deapexerTagStruct struct {
115 blueprint.BaseDependencyTag
116}
117
Paul Duffin5466a362021-06-07 10:25:31 +0100118// Mark this tag so dependencies that use it are excluded from APEX contents.
119func (t deapexerTagStruct) ExcludeFromApexContents() {}
120
121var _ ExcludeFromApexContentsTag = DeapexerTag
122
Paul Duffin064b70c2020-11-02 17:32:38 +0000123// A tag that is used for dependencies on the `deapexer` module.
124var DeapexerTag = deapexerTagStruct{}
Paul Duffin5466a362021-06-07 10:25:31 +0100125
126// RequiredFilesFromPrebuiltApex must be implemented by modules that require files to be exported
127// from a prebuilt_apex/apex_set.
128type RequiredFilesFromPrebuiltApex interface {
Paul Duffinb4bbf2c2021-06-17 15:59:07 +0100129 // 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.
Paul Duffin5466a362021-06-07 10:25:31 +0100131 //
Paul Duffinb4bbf2c2021-06-17 15:59:07 +0100132 // 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
Paul Duffin5466a362021-06-07 10:25:31 +0100136}
Paul Duffinfef55002021-06-17 14:56:05 +0100137
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}
Martin Stjernholm44825602021-09-17 01:44:12 +0100146
147// FindDeapexerProviderForModule searches through the direct dependencies of the current context
Martin Stjernholm43c44b02021-06-30 16:35:07 +0100148// 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.
Martin Stjernholm44825602021-09-17 01:44:12 +0100150func FindDeapexerProviderForModule(ctx ModuleContext) *DeapexerInfo {
151 var di *DeapexerInfo
152 ctx.VisitDirectDepsWithTag(DeapexerTag, func(m Module) {
Paul Duffin5556c5f2022-06-09 17:32:21 +0000153 c := ctx.OtherModuleProvider(m, DeapexerProvider).(DeapexerInfo)
154 p := &c
Martin Stjernholm43c44b02021-06-30 16:35:07 +0100155 if di != nil {
Paul Duffin5556c5f2022-06-09 17:32:21 +0000156 // 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 }
Martin Stjernholm43c44b02021-06-30 16:35:07 +0100162 ctx.ModuleErrorf("Multiple installable prebuilt APEXes provide ambiguous deapexers: %s and %s",
163 di.ApexModuleName(), p.ApexModuleName())
164 }
Paul Duffin5556c5f2022-06-09 17:32:21 +0000165 di = p
Martin Stjernholm44825602021-09-17 01:44:12 +0100166 })
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}
Paul Duffin5556c5f2022-06-09 17:32:21 +0000174
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}