1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
// Copyright 2015 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.packages;
/**
* A class of aspects.
*
* <p>An aspect allows a rule to create actions in its dependencies, without their knowledge. It can
* be viewed as the ability to attach shadow targets to transitive dependencies or a way to run
* visitations of certain parts of the transitive closure of a rule in such a way that can be cached
* (even partially) and reused between different configured targets requiring the same aspect. Some
* examples where aspects are useful:
*
* <ul>
* <li>Converting the .jar files in the transitive closure of an Android binary to dexes
* <li>Emitting Java sources for a <code>proto_library</code> and the messages it depends on
* <li>Collecting all the dependencies of a rule to make sure that it does not contain a forbidden
* one
* </ul>
*
* <p>When a configured target requests that an aspect be attached to one of its dependencies, the
* {@link com.google.devtools.build.lib.analysis.TransitiveInfoProvider}s generated by that aspects
* are merged with those of the actual dependency, that is, {@link
* com.google.devtools.build.lib.analysis.RuleContext#getPrerequisite( String,
* RuleConfiguredTarget.Mode)} will contain the transitive info providers produced both by the
* dependency and the aspects that are attached to it.
*
* <p>Configured targets can specify which aspects should be attached to some of their dependencies
* by specifying this in their {@link com.google.devtools.build.lib.analysis.RuleDefinition}: each
* attribute can have a list of aspects to be applied to the rules in that attribute and each aspect
* can specify which {@link com.google.devtools.build.lib.analysis.TransitiveInfoProvider}s it needs
* on a rule so that it can do meaningful work (for example, dexing only makes sense for configured
* targets that produce Java code).
*
* <p>Aspects can be defined natively, in Java ({@link NativeAspectClass}) or in Skylark ({@link
* SkylarkAspectClass}).
*
* <p>Bazel propagates aspects through a multistage process. The general pipeline is as follows:
*
* <pre>
* {@link AspectClass}
* |
* V
* {@code AspectDescriptor} <- {@link AspectParameters}
* \
* V
* {@link Aspect} <- {@link AspectDefinition} (might require loading Skylark files)
* |
* V
* {@code ConfiguredAspect} <- {@code ConfiguredTarget}
* </pre>
*
* <ul>
* <li>{@link AspectClass} is a moniker for "user" definition of the aspect, be it a native aspect
* or a Skylark aspect. It contains either a reference to the native class implementing the
* aspect or the location of the Skylark definition of the aspect in the source tree, i.e.
* label of .bzl file + symbol name.
* <li>{@link AspectParameters} is a (key,value) pair list that can be used to parameterize aspect
* classes
* <li>{@link AspectDescriptor} is a pair of {@code AspectClass} and {@link AspectParameters}. It
* uniquely identifies the aspect and can be used in SkyKeys.
* <li>{@link AspectDefinition} is a class encapsulating the aspect definition (what attributes
* aspoect has, and along which dependencies does it propagate.
* <li>{@link Aspect} is a fully instantiated instance of an Aspect after it is loaded. Getting an
* {@code Aspect} from {@code AspectDescriptor} for Skylark aspects requires adding a Skyframe
* dependency.
* <li>{@link com.google.devtools.build.lib.analysis.ConfiguredAspect} represents a result of
* application of an {@link Aspect} to a given {@link
* com.google.devtools.build.lib.analysis.ConfiguredTarget}.
* </ul>
*
* {@link AspectDescriptor}, or in general, a tuple of ({@link AspectClass}, {@link
* AspectParameters}) is an identifier that should be used in SkyKeys or in other contexts that need
* equality for aspects. See also {@link com.google.devtools.build.lib.skyframe.AspectFunction} for
* details on Skyframe treatment of Aspects.
*
* @see com.google.devtools.build.lib.analysis.RuleConfiguredTargetFactory
* @see com.google.devtools.build.lib.skyframe.AspectFunction
*/
public interface AspectClass {
/**
* Returns an aspect name.
*/
String getName();
default String getKey() {
return getName();
}
}
|
