> aspects) {
this.type = type;
this.doc = doc;
this.transitionFactory = transitionFactory;
this.allowedRuleClassesForLabels = allowedRuleClassesForLabels;
this.allowedRuleClassesForLabelsWarning = allowedRuleClassesForLabelsWarning;
this.allowedFileTypesForLabels = allowedFileTypesForLabels;
this.validityPredicate = validityPredicate;
this.value = value;
this.valueSource = valueSource;
this.valueSet = valueSet;
this.propertyFlags = propertyFlags;
this.allowedValues = allowedValues;
this.requiredProviders = requiredProviders;
this.aspects = aspects;
}
public AttributeValueSource getValueSource() {
return valueSource;
}
public boolean isValueSet() {
return valueSet;
}
public Attribute build(String name) {
Preconditions.checkState(!name.isEmpty(), "name has not been set");
if (valueSource == AttributeValueSource.LATE_BOUND) {
Preconditions.checkState(isLateBound(name));
Preconditions.checkState(!transitionFactory.isSplit());
}
// TODO(bazel-team): Set the default to be no file type, then remove this check, and also
// remove all allowedFileTypes() calls without parameters.
// do not modify this.allowedFileTypesForLabels, instead create a copy.
FileTypeSet allowedFileTypesForLabels = this.allowedFileTypesForLabels;
if (type.getLabelClass() == LabelClass.DEPENDENCY) {
if (isPrivateAttribute(name) && allowedFileTypesForLabels == null) {
allowedFileTypesForLabels = FileTypeSet.ANY_FILE;
}
Preconditions.checkNotNull(
allowedFileTypesForLabels, "allowedFileTypesForLabels not set for %s", name);
} else if (type.getLabelClass() == LabelClass.OUTPUT) {
// TODO(bazel-team): Set the default to no file type and make explicit calls instead.
if (allowedFileTypesForLabels == null) {
allowedFileTypesForLabels = FileTypeSet.ANY_FILE;
}
}
return new Attribute(
name,
doc,
type,
propertyFlags,
value,
transitionFactory,
allowedRuleClassesForLabels,
allowedRuleClassesForLabelsWarning,
allowedFileTypesForLabels,
validityPredicate,
allowedValues,
requiredProviders,
aspects);
}
}
/**
* A fluent builder for the {@code Attribute} instances.
*
* All methods could be called only once per builder. The attribute already undocumented based
* on its name cannot be marked as undocumented.
*/
public static class Builder {
private final String name;
private final Type type;
private TransitionFactory transitionFactory =
NoTransition.createFactory();
private RuleClassNamePredicate allowedRuleClassesForLabels = ANY_RULE;
private RuleClassNamePredicate allowedRuleClassesForLabelsWarning = NO_RULE;
private FileTypeSet allowedFileTypesForLabels;
private ValidityPredicate validityPredicate = ANY_EDGE;
private Object value;
private String doc;
private AttributeValueSource valueSource = AttributeValueSource.DIRECT;
private boolean valueSet;
private Set propertyFlags = EnumSet.noneOf(PropertyFlag.class);
private PredicateWithMessage allowedValues = null;
private RequiredProviders.Builder requiredProvidersBuilder =
RequiredProviders.acceptAnyBuilder();
private AspectsListBuilder aspectsListBuilder = new AspectsListBuilder();
/**
* Creates an attribute builder with given name and type. This attribute is optional, uses
* target configuration and has a default value the same as its type default value. This
* attribute will be marked as undocumented if its name starts with the dollar sign ({@code $})
* or colon ({@code :}).
*
* @param name attribute name
* @param type attribute type
*/
public Builder(String name, Type type) {
this.name = Preconditions.checkNotNull(name);
this.type = Preconditions.checkNotNull(type);
if (isImplicit(name) || isLateBound(name)) {
setPropertyFlag(PropertyFlag.UNDOCUMENTED, "undocumented");
}
}
@CanIgnoreReturnValue
private Builder setPropertyFlag(PropertyFlag flag, String propertyName) {
Preconditions.checkState(
!propertyFlags.contains(flag), "'%s' flag is already set", propertyName);
propertyFlags.add(flag);
return this;
}
/**
* Sets the property flag of the corresponding name if exists, otherwise throws an Exception.
* Only meant to use from Starlark, do not use from Java.
*
* @throws EvalException if a property flag with the provided name does not exist or cannot be
* set.
*/
@CanIgnoreReturnValue
public Builder setPropertyFlag(String propertyName) throws EvalException {
PropertyFlag flag;
try {
flag = PropertyFlag.valueOf(propertyName);
} catch (IllegalArgumentException e) {
throw Starlark.errorf("unknown attribute flag '%s'", propertyName);
}
try {
setPropertyFlag(flag, propertyName);
} catch (IllegalStateException e) {
throw new EvalException(e);
}
return this;
}
/** Makes the built attribute mandatory. */
public Builder mandatory() {
return setPropertyFlag(PropertyFlag.MANDATORY, "mandatory");
}
/**
* Makes the built attribute non empty, meaning the attribute cannot have an empty list value.
* Only applicable for list type attributes.
*/
public Builder nonEmpty() {
Preconditions.checkNotNull(type.getListElementType(), "attribute '%s' must be a list", name);
return setPropertyFlag(PropertyFlag.NON_EMPTY, "non_empty");
}
/** Makes the built attribute producing a single artifact. */
public Builder singleArtifact() {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY,
"attribute '%s' must be a label-valued type",
name);
return setPropertyFlag(PropertyFlag.SINGLE_ARTIFACT, "single_artifact");
}
/**
* Forces silent ruleclass filtering on the label type attribute. This flag is introduced to
* handle plugins, do not use it in other cases.
*/
public Builder silentRuleClassFilter() {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
return setPropertyFlag(PropertyFlag.SILENT_RULECLASS_FILTER, "silent_ruleclass_filter");
}
/** Skip analysis time filetype check. Don't use it if avoidable. */
public Builder skipAnalysisTimeFileTypeCheck() {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
return setPropertyFlag(
PropertyFlag.SKIP_ANALYSIS_TIME_FILETYPE_CHECK, "skip_analysis_time_filetype_check");
}
/** Mark the built attribute as order-independent. */
public Builder orderIndependent() {
Preconditions.checkNotNull(type.getListElementType(), "attribute '%s' must be a list", name);
return setPropertyFlag(PropertyFlag.ORDER_INDEPENDENT, "order-independent");
}
/** Mark the built attribute as to use output_licenses for license checking. */
public Builder useOutputLicenses() {
Preconditions.checkState(BuildType.isLabelType(type), "must be a label type");
return setPropertyFlag(PropertyFlag.OUTPUT_LICENSES, "output_license");
}
/**
* Indicate the attribute uses uses a starlark-defined (non-analysis-test) configuration
* transition. Transitions for analysis testing are tracked separately: see {@link
* #hasAnalysisTestTransition()}.
*/
public Builder hasStarlarkDefinedTransition() {
return setPropertyFlag(
PropertyFlag.HAS_STARLARK_DEFINED_TRANSITION, "starlark-defined split transition");
}
/**
* Indicate the attribute uses uses a starlark-defined analysis-test configuration transition.
* Such a configuration transition may only be applied on rules with {@code analysis_test=true}.
*/
public Builder hasAnalysisTestTransition() {
return setPropertyFlag(
PropertyFlag.HAS_ANALYSIS_TEST_TRANSITION, "analysis-test split transition");
}
/** Defines the configuration transition for this attribute. */
@CanIgnoreReturnValue
public Builder cfg(TransitionFactory transitionFactory) {
Preconditions.checkNotNull(transitionFactory);
Preconditions.checkState(
NoTransition.isInstance(this.transitionFactory),
"the configuration transition is already set");
this.transitionFactory = transitionFactory;
return this;
}
/**
* Requires the attribute target to be executable; only for label or label list attributes.
* Defaults to {@code false}.
*/
public Builder exec() {
return setPropertyFlag(PropertyFlag.EXECUTABLE, "executable");
}
/**
* Indicates that the attribute (like srcs or hdrs) should be used as an input when calculating
* compile_one_dependency.
*/
public Builder direct_compile_time_input() {
return setPropertyFlag(PropertyFlag.DIRECT_COMPILE_TIME_INPUT, "direct_compile_time_input");
}
/**
* Makes the built attribute undocumented.
*
* @param reason explanation why the attribute is undocumented. This is not used but required
* for documentation
*/
public Builder undocumented(String reason) {
return setPropertyFlag(PropertyFlag.UNDOCUMENTED, "undocumented");
}
/**
* Set the doc string for the attribute.
*
* @param doc The doc string for this attribute.
*/
@CanIgnoreReturnValue
public Builder setDoc(String doc) {
this.doc = doc;
return this;
}
/**
* Sets the attribute default value. The type of the default value must match the type
* parameter. (e.g. list=[], integer=0, string="", label=null). The {@code defaultValue} must be
* immutable.
*
* If defaultValue is of type Label and is a target, that target will become an implicit
* dependency of the Rule; we will load the target (and its dependencies) if it encounters the
* Rule and build the target if needs to apply the Rule.
*/
@CanIgnoreReturnValue
public Builder value(TYPE defaultValue) {
Preconditions.checkState(!valueSet, "the default value is already set");
value = defaultValue;
valueSet = true;
return this;
}
/**
* Sets the attribute default value to a computed default value - use this when the default
* value is a function of other attributes of the Rule. The type of the computed default value
* for a mandatory attribute must match the type parameter: (e.g. list=[], integer=0, string="",
* label=null). The {@code defaultValue} implementation must be immutable.
*
* If the computed default returns a Label that is a target, that target will become an
* implicit dependency of this Rule; we will load the target (and its dependencies) if it
* encounters the Rule and build the target if needs to apply the Rule.
*/
@CanIgnoreReturnValue
public Builder value(ComputedDefault defaultValue) {
Preconditions.checkState(!valueSet, "the default value is already set");
value = defaultValue;
valueSource = AttributeValueSource.COMPUTED_DEFAULT;
valueSet = true;
return this;
}
/** Used for b/200065655#comment3. */
@CanIgnoreReturnValue
public Builder value(NativeComputedDefaultApi defaultValue) {
Preconditions.checkState(!valueSet, "the default value is already set");
value = defaultValue;
valueSource = AttributeValueSource.NATIVE_COMPUTED_DEFAULT;
valueSet = true;
return this;
}
/**
* Sets the attribute default value to a Starlark computed default template. Like a native
* Computed Default, this allows a Starlark-defined Rule Class to specify that the default value
* of an attribute is a function of other attributes of the Rule.
*
* During the loading phase, the computed default template will be specialized for each rule
* it applies to. Those rules' attribute values will not be references to {@link
* StarlarkComputedDefaultTemplate}s, but instead will be references to {@link
* StarlarkComputedDefault}s.
*
*
If the computed default returns a Label that is a target, that target will become an
* implicit dependency of this Rule; we will load the target (and its dependencies) if it
* encounters the Rule and build the target if needs to apply the Rule.
*/
@CanIgnoreReturnValue
public Builder value(StarlarkComputedDefaultTemplate starlarkComputedDefaultTemplate) {
Preconditions.checkState(!valueSet, "the default value is already set");
value = starlarkComputedDefaultTemplate;
valueSource = AttributeValueSource.COMPUTED_DEFAULT;
valueSet = true;
return this;
}
/**
* Sets the attribute default value to be late-bound, i.e., it is derived from the build
* configuration and/or the rule's configured attributes.
*/
@CanIgnoreReturnValue
public Builder value(LateBoundDefault defaultValue) {
Preconditions.checkState(!valueSet, "the default value is already set");
value = defaultValue;
valueSource = AttributeValueSource.LATE_BOUND;
valueSet = true;
return this;
}
/**
* See value(TYPE) above. This method is only meant for Starlark usage.
*
* The parameter {@code labelConverter} is relevant iff the default value is a Label string.
*
* @param parameterName The name of the attribute to use in error messages
*/
@CanIgnoreReturnValue
public Builder defaultValue(
Object defaultValue, LabelConverter labelConverter, @Nullable String parameterName)
throws ConversionException {
Preconditions.checkState(!valueSet, "the default value is already set");
value =
type.convert(
defaultValue,
((parameterName == null) ? "" : String.format("parameter '%s' of ", parameterName))
+ String.format("attribute '%s'", name),
labelConverter);
valueSet = true;
return this;
}
/** See value(TYPE) above. This method is only meant for Starlark usage. */
public Builder defaultValue(Object defaultValue) throws ConversionException {
return defaultValue(defaultValue, null, null);
}
/** Returns where the value of this attribute comes from. Useful only for Starlark. */
public AttributeValueSource getValueSource() {
return valueSource;
}
/** Switches on the capability of an attribute to be published to the rule's tag set. */
public Builder taggable() {
return setPropertyFlag(PropertyFlag.TAGGABLE, "taggable");
}
/**
* Disables dependency checks done by {@link
* com.google.devtools.build.lib.analysis.RuleContext.PrerequisiteValidator}.
*/
public Builder skipPrereqValidatorCheck() {
return setPropertyFlag(
PropertyFlag.SKIP_PREREQ_VALIDATOR_CHECKS, "skip_prereq_validator_checks");
}
/**
* Enforces constraint checking on this attribute even if default enforcement policy would skip
* it. If default policy checks the attribute, this is a no-op.
*
* Most attributes are enforced by default, so in the common case this call is unnecessary.
*
*
See {@link com.google.devtools.build.lib.analysis.constraints.ConstraintSemantics} for
* enforcement policy details.
*/
public Builder checkConstraints() {
Verify.verify(
!propertyFlags.contains(PropertyFlag.SKIP_CONSTRAINTS_OVERRIDE),
"constraint checking is already overridden to be skipped");
return setPropertyFlag(PropertyFlag.CHECK_CONSTRAINTS_OVERRIDE, "check_constraints");
}
/**
* Skips constraint checking on this attribute even if default enforcement policy would check
* it. If default policy skips the attribute, this is a no-op.
*
* See {@link com.google.devtools.build.lib.analysis.constraints.ConstraintSemantics} for
* enforcement policy details.
*/
public Builder dontCheckConstraints() {
Verify.verify(
!propertyFlags.contains(PropertyFlag.CHECK_CONSTRAINTS_OVERRIDE),
"constraint checking is already overridden to be checked");
return setPropertyFlag(PropertyFlag.SKIP_CONSTRAINTS_OVERRIDE, "dont_check_constraints");
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types for the
* labels occurring in the attribute.
*
* If the attribute contains Labels of any other rule type, then if they're in {@link
* #allowedRuleClassesForLabelsWarning}, the build continues with a warning. Else if they
* fulfill {@link #mandatoryBuiltinProvidersList}, the build continues without error. Else the
* build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabelsWarning} is set, only rules that
* fulfill {@link #mandatoryBuiltinProvidersList} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
public Builder allowedRuleClasses(Iterable allowedRuleClasses) {
return allowedRuleClasses(RuleClassNamePredicate.only(allowedRuleClasses));
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types for the
* labels occurring in the attribute.
*
* If the attribute contains Labels of any other rule type, then if they're in {@link
* #allowedRuleClassesForLabelsWarning}, the build continues with a warning. Else if they
* fulfill {@link #mandatoryBuiltinProvidersList}, the build continues without error. Else the
* build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabelsWarning} is set, only rules that
* fulfill {@link #mandatoryBuiltinProvidersList} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
@CanIgnoreReturnValue
public Builder allowedRuleClasses(RuleClassNamePredicate allowedRuleClasses) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
propertyFlags.add(PropertyFlag.STRICT_LABEL_CHECKING);
allowedRuleClassesForLabels = allowedRuleClasses;
return this;
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types for the
* labels occurring in the attribute.
*
* If the attribute contains Labels of any other rule type, then if they're in {@link
* #allowedRuleClassesForLabelsWarning}, the build continues with a warning. Else if they
* fulfill {@link #mandatoryBuiltinProvidersList}, the build continues without error. Else the
* build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabelsWarning} is set, only rules that
* fulfill {@link #mandatoryBuiltinProvidersList} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
public Builder allowedRuleClasses(String... allowedRuleClasses) {
return allowedRuleClasses(ImmutableSet.copyOf(allowedRuleClasses));
}
/**
* If this is a label or label-list attribute, then this sets the allowed file types for file
* labels occurring in the attribute. If the attribute contains labels that correspond to files
* of any other type, then an error is produced during the analysis phase.
*
* This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
@CanIgnoreReturnValue
public Builder allowedFileTypes(FileTypeSet allowedFileTypes) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY
|| type.getLabelClass() == LabelClass.GENQUERY_SCOPE_REFERENCE,
"must be a label-valued type");
propertyFlags.add(PropertyFlag.STRICT_LABEL_CHECKING);
allowedFileTypesForLabels = Preconditions.checkNotNull(allowedFileTypes);
return this;
}
/**
* If this is a label or label-list attribute, then this sets the allowed file types for file
* labels occurring in the attribute. If the attribute contains labels that correspond to files
* of any other type, then an error is produced during the analysis phase.
*
* This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
public Builder allowedFileTypes(FileType... allowedFileTypes) {
return allowedFileTypes(FileTypeSet.of(allowedFileTypes));
}
/**
* Allow all files for legacy compatibility. All uses of this method should be audited and then
* removed. In some cases, it's correct to allow any file, but mostly the set of files should be
* restricted to a reasonable set.
*/
public Builder legacyAllowAnyFileType() {
return allowedFileTypes(FileTypeSet.ANY_FILE);
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types with
* warning for the labels occurring in the attribute. This must be a disjoint set from {@link
* #allowedRuleClasses}.
*
* If the attribute contains Labels of any other rule type (other than this or those set in
* allowedRuleClasses()) and they fulfill {@link #mandatoryBuiltinProvidersList}}, the build
* continues without error. Else the build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabels} is set, only rules that fulfill
* {@link #mandatoryBuiltinProvidersList} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
public Builder allowedRuleClassesWithWarning(Collection allowedRuleClasses) {
return allowedRuleClassesWithWarning(RuleClassNamePredicate.only(allowedRuleClasses));
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types with
* warning for the labels occurring in the attribute. This must be a disjoint set from {@link
* #allowedRuleClasses}.
*
* If the attribute contains Labels of any other rule type (other than this or those set in
* allowedRuleClasses()) and they fulfill {@link #mandatoryBuiltinProvidersList}}, the build
* continues without error. Else the build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabels} is set, only rules that fulfill
* {@link #mandatoryBuiltinProvidersList} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
@CanIgnoreReturnValue
Builder allowedRuleClassesWithWarning(RuleClassNamePredicate allowedRuleClasses) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
propertyFlags.add(PropertyFlag.STRICT_LABEL_CHECKING);
allowedRuleClassesForLabelsWarning = allowedRuleClasses;
return this;
}
/**
* If this is a label or label-list attribute, then this sets the allowed rule types with
* warning for the labels occurring in the attribute. This must be a disjoint set from {@link
* #allowedRuleClasses}.
*
* If the attribute contains Labels of any other rule type (other than this or those set in
* allowedRuleClasses()) and they fulfill {@link #getRequiredProviders()}}, the build continues
* without error. Else the build fails during analysis.
*
*
If neither this nor {@link #allowedRuleClassesForLabels} is set, only rules that fulfill
* {@link #getRequiredProviders()} build without error.
*
*
This only works on a per-target basis, not on a per-file basis; with other words, it works
* for 'deps' attributes, but not 'srcs' attributes.
*/
public Builder allowedRuleClassesWithWarning(String... allowedRuleClasses) {
return allowedRuleClassesWithWarning(ImmutableSet.copyOf(allowedRuleClasses));
}
/**
* Sets a list of lists of mandatory built-in providers. Every configured target occurring in
* this label type attribute has to provide all the providers from one of those lists, otherwise
* an error is produced during the analysis phase.
*/
@CanIgnoreReturnValue
final Builder mandatoryBuiltinProvidersList(
Iterable>> providersList) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
for (Iterable> providers : providersList) {
this.requiredProvidersBuilder.addBuiltinSet(ImmutableSet.copyOf(providers));
}
return this;
}
@CanIgnoreReturnValue
public Builder mandatoryBuiltinProviders(
Iterable> providers) {
if (providers.iterator().hasNext()) {
mandatoryBuiltinProvidersList(ImmutableList.of(providers));
}
return this;
}
/**
* Sets a list of sets of mandatory Starlark providers. Every configured target occurring in
* this label type attribute has to provide all the providers from one of those sets, or be one
* of {@link #allowedRuleClasses}, otherwise an error is produced during the analysis phase.
*/
@CanIgnoreReturnValue
public Builder mandatoryProvidersList(
Iterable> providersList) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
for (Iterable providers : providersList) {
this.requiredProvidersBuilder.addStarlarkSet(ImmutableSet.copyOf(providers));
}
return this;
}
@CanIgnoreReturnValue
public Builder mandatoryProviders(Iterable providers) {
if (providers.iterator().hasNext()) {
mandatoryProvidersList(ImmutableList.of(providers));
}
return this;
}
@CanIgnoreReturnValue
public Builder mandatoryProviders(StarlarkProviderIdentifier... providers) {
mandatoryProviders(Arrays.asList(providers));
return this;
}
public AspectsListBuilder getAspectsListBuilder() {
return aspectsListBuilder;
}
/**
* Asserts that a particular parameterized aspect probably needs to be computed for all direct
* dependencies through this attribute.
*
* @param evaluator function that extracts aspect parameters from rule. If it returns null, then
* the aspect will not be attached.
*/
@CanIgnoreReturnValue
public Builder aspect(
NativeAspectClass aspect, Function evaluator) {
aspectsListBuilder.addAspect(aspect, evaluator);
return this;
}
/**
* Asserts that a particular parameterized aspect probably needs to be computed for all direct
* dependencies through this attribute.
*/
@CanIgnoreReturnValue
public Builder aspect(NativeAspectClass aspect) {
aspectsListBuilder.addAspect(aspect);
return this;
}
/** Should only be used for deserialization. */
@CanIgnoreReturnValue
public Builder aspect(final Aspect aspect) {
aspectsListBuilder.addAspect(aspect);
return this;
}
/** Sets the predicate-like edge validity checker. */
@CanIgnoreReturnValue
public Builder validityPredicate(ValidityPredicate validityPredicate) {
propertyFlags.add(PropertyFlag.STRICT_LABEL_CHECKING);
this.validityPredicate = validityPredicate;
return this;
}
/** The value of the attribute must be one of allowedValues. */
@CanIgnoreReturnValue
public Builder allowedValues(PredicateWithMessage allowedValues) {
this.allowedValues = allowedValues;
propertyFlags.add(PropertyFlag.CHECK_ALLOWED_VALUES);
return this;
}
/**
* Makes the built attribute "non-configurable", i.e. its value cannot be influenced by the
* build configuration. Attributes are "configurable" unless explicitly opted out here.
*
* Non-configurability indicates an exceptional state: there exists Blaze logic that needs
* the attribute's value, has no access to configurations, and can't apply a workaround through
* an appropriate {@link AbstractAttributeMapper} implementation. Scenarios like this should be
* as uncommon as possible, so it's important we maintain clear documentation on what causes
* them and why users consequently can't configure certain attributes.
*
* @param reason why this attribute can't be configurable. This isn't used by Blaze - it's
* solely a documentation mechanism.
*/
public Builder nonconfigurable(String reason) {
Preconditions.checkState(!reason.isEmpty());
return setPropertyFlag(PropertyFlag.NONCONFIGURABLE, "nonconfigurable");
}
public Builder tool(String reason) {
Preconditions.checkState(
type.getLabelClass() == LabelClass.DEPENDENCY, "must be a label-valued type");
Preconditions.checkState(!reason.isEmpty());
return setPropertyFlag(PropertyFlag.IS_TOOL_DEPENDENCY, "is_tool_dependency");
}
/** Marks the built attribute as defined in Starlark. */
@CanIgnoreReturnValue
public Builder starlarkDefined() {
return setPropertyFlag(PropertyFlag.STARLARK_DEFINED, "starlark_defined");
}
/** Returns an {@link ImmutableAttributeFactory} that can be invoked to create attributes. */
public ImmutableAttributeFactory buildPartial() {
Preconditions.checkState(
!allowedRuleClassesForLabels.consideredOverlapping(allowedRuleClassesForLabelsWarning),
"allowedRuleClasses %s and allowedRuleClassesWithWarning %s "
+ "may not contain the same rule classes",
allowedRuleClassesForLabels,
allowedRuleClassesForLabelsWarning);
return new ImmutableAttributeFactory(
type,
doc,
Sets.immutableEnumSet(propertyFlags),
valueSet ? value : type.getDefaultValue(),
transitionFactory,
allowedRuleClassesForLabels,
allowedRuleClassesForLabelsWarning,
allowedFileTypesForLabels,
validityPredicate,
valueSource,
valueSet,
allowedValues,
requiredProvidersBuilder.build(),
aspectsListBuilder.getAspectsDetails());
}
/**
* Creates the attribute. Uses name, type, optionality, configuration type and the default value
* configured by the builder.
*/
public Attribute build() {
return build(this.name);
}
/**
* Creates the attribute. Uses type, optionality, configuration type and the default value
* configured by the builder. Use the name passed as an argument. This function is used by
* Starlark where the name is provided only when we build. We don't want to modify the builder,
* as it is shared in a multithreaded environment.
*/
public Attribute build(String name) {
return buildPartial().build(name);
}
}
/**
* A strategy for dealing with too many computations, used when creating lookup tables for {@link
* ComputedDefault}s.
*
* @param The type of exception this strategy throws if too many computations are
* attempted.
*/
interface ComputationLimiter {
void onComputationCount(int count) throws ExceptionT;
}
/**
* An implementation of {@link ComputationLimiter} that never throws. For use with
* natively-defined {@link ComputedDefault}s, which are limited in the number of configurable
* attributes they depend on, not on the number of different combinations of possible inputs.
*/
/** Exception for computed default attributes that depend on too many configurable attributes. */
private static class TooManyConfigurableAttributesException extends Exception {
TooManyConfigurableAttributesException(int max) {
super(
String.format(
"Too many configurable attributes to compute all possible values: "
+ "Found more than %d possible values.",
max));
}
}
private static class FixedComputationLimiter
implements ComputationLimiter {
/** Upper bound of the number of combinations of values for a computed default attribute. */
private static final int COMPUTED_DEFAULT_MAX_COMBINATIONS = 64;
private static final FixedComputationLimiter INSTANCE = new FixedComputationLimiter();
@Override
public void onComputationCount(int count) throws TooManyConfigurableAttributesException {
if (count > COMPUTED_DEFAULT_MAX_COMBINATIONS) {
throw new TooManyConfigurableAttributesException(COMPUTED_DEFAULT_MAX_COMBINATIONS);
}
}
}
/**
* Specifies how values of {@link ComputedDefault} attributes are computed based on the values of
* other attributes.
*
* The {@code TComputeException} type parameter allows the two specializations of this class to
* describe whether and how their computations throw. For natively defined computed defaults,
* computation does not throw, but for Starlark-defined computed defaults, computation may throw
* {@link InterruptedException}.
*/
private abstract static class ComputationStrategy {
abstract Object compute(AttributeMap map) throws TComputeException;
/**
* Returns a lookup table mapping from:
*
*
* tuples of values that may be assigned by {@code rule} to attributes with names in
* {@code dependencies} (note that there may be more than one such tuple for any given
* rule, if any of the dependencies are configurable)
*
*
* to:
*
*
* the value {@link #compute(AttributeMap)} evaluates to when the provided {@link
* AttributeMap} contains the values specified by that assignment, or {@code null} if the
* {@link ComputationStrategy} failed to evaluate.
*
*
* The lookup table contains a tuple for each possible assignment to the {@code dependencies}
* attributes. The meaning of each tuple is well-defined because {@code dependencies} is
* ordered.
*
*
This is useful because configurable attributes may have many possible values. During the
* loading phase a configurable attribute can't be resolved to a single value. Configuration
* information, needed to resolve such an attribute, is only available during analysis. However,
* any labels that a ComputedDefault attribute may evaluate to must be loaded during the loading
* phase.
*/
Map, T> computeValuesForAllCombinations(
List dependencies,
Type type,
Rule rule,
ComputationLimiter limiter)
throws TComputeException, TLimitException {
AggregatingAttributeMapper mapper = AggregatingAttributeMapper.of(rule);
// This will hold every (value1, value2, ..) combination of the declared dependencies.
// Collect those combinations.
List> depMaps = mapper.visitAttributes(dependencies, limiter);
// For each combination, call compute() on a specialized AttributeMap providing those
// values.
Map, T> valueMap = Maps.newHashMapWithExpectedSize(depMaps.size());
for (Map depMap : depMaps) {
AttributeMap attrMap = mapper.createMapBackedAttributeMap(depMap);
Object value = compute(attrMap);
List key = createDependencyAssignmentTuple(dependencies, attrMap);
valueMap.put(key, type.cast(value));
}
return valueMap;
}
/**
* Given an {@link AttributeMap}, containing an assignment to each attribute in {@code
* dependencies}, this returns a list of the assigned values, ordered as {@code dependencies} is
* ordered.
*/
static List createDependencyAssignmentTuple(
List dependencies, AttributeMap attrMap) {
ArrayList tuple = new ArrayList<>(dependencies.size());
for (String attrName : dependencies) {
Type attrType = attrMap.getAttributeType(attrName);
tuple.add(attrMap.get(attrName, attrType));
}
return tuple;
}
}
/**
* A computed default is a default value for a Rule attribute that is a function of other
* attributes of the rule.
*
* Attributes whose defaults are computed are first initialized to the default for their type,
* and then the computed defaults are evaluated after all non-computed defaults have been
* initialized. There is no defined order among computed defaults, so they must not depend on each
* other.
*
*
If a computed default reads the value of another attribute, at least one of the following
* must be true:
*
*
* The other attribute must be declared in the computed default's constructor
* The other attribute must be non-configurable ({@link Builder#nonconfigurable}
*
*
* The reason for enforced declarations is that, since attribute values might be configurable,
* a computed default that depends on them may itself take multiple values. Since we have no
* access to a target's configuration at the time these values are computed, we need the ability
* to probe the default's *complete* dependency space. Declared dependencies allow us to do so
* sanely. Non-configurable attributes don't have this problem because their value is fixed and
* known even without configuration information.
*
*
Implementations of this interface must be immutable.
*/
public abstract static class ComputedDefault implements StarlarkValue {
private final ImmutableList dependencies;
/**
* Create a computed default that can read all non-configurable attribute values and no
* configurable attribute values.
*/
protected ComputedDefault() {
this(ImmutableList.of());
}
/**
* Create a computed default that can read all non-configurable attributes values and one
* explicitly specified configurable attribute value
*/
protected ComputedDefault(String depAttribute) {
this(ImmutableList.of(depAttribute));
}
/**
* Create a computed default that can read all non-configurable attributes values and two
* explicitly specified configurable attribute values.
*/
protected ComputedDefault(String depAttribute1, String depAttribute2) {
this(ImmutableList.of(depAttribute1, depAttribute2));
}
/**
* Creates a computed default that can read all non-configurable attributes and some explicitly
* specified configurable attribute values.
*
* This constructor should not be used by native {@link ComputedDefault} functions. The limit
* of at-most-two depended-on configurable attributes is intended, to limit the exponential
* growth of possible values. {@link StarlarkComputedDefault} uses this, but is limited by
* {@link FixedComputationLimiter#COMPUTED_DEFAULT_MAX_COMBINATIONS}.
*/
ComputedDefault(ImmutableList dependencies) {
// Order is important for #createDependencyAssignmentTuple.
this.dependencies = Ordering.natural().immutableSortedCopy(dependencies);
}
List getPossibleValues(Type type, Rule rule) {
final ComputedDefault owner = ComputedDefault.this;
if (dependencies.isEmpty()) {
AggregatingAttributeMapper mapper = AggregatingAttributeMapper.of(rule);
Object value = owner.getDefault(mapper.createMapBackedAttributeMap(ImmutableMap.of()));
return Lists.newArrayList(type.cast(value));
}
ComputationStrategy strategy =
new ComputationStrategy<>() {
@Override
public Object compute(AttributeMap map) {
return owner.getDefault(map);
}
};
// Note that this uses ArrayList instead of something like ImmutableList because some
// values may be null.
return new ArrayList<>(
strategy.computeValuesForAllCombinations(dependencies, type, rule, count -> {}).values());
}
/** The list of configurable attributes this ComputedDefault declares it may read. */
public ImmutableList dependencies() {
return dependencies;
}
/**
* Return true if {@link #getDefault} can be safely called with a RawAttributeMapper.
*
* Notably, this means {@link #getDefault} does not call {@link AttributeMap#get} on any
* configurable attributes as they could potentially contain a SelectorList. In practice, only
* call get on {@link Attribute.Builder#nonconfigurable} attributes unless you really know what
* you are doing.
*/
public boolean resolvableWithRawAttributes() {
return false;
}
/**
* Returns the value this {@link ComputedDefault} evaluates to, given the inputs contained in
* {@code rule}.
*/
@Nullable
public abstract Object getDefault(AttributeMap rule);
}
/**
* A Starlark-defined computed default, which can be precomputed for a specific {@link Rule} by
* calling {@link #computePossibleValues}, which returns a {@link StarlarkComputedDefault} that
* contains a lookup table.
*/
public static final class StarlarkComputedDefaultTemplate {
private final Type type;
private final StarlarkCallbackHelper callback;
private final ImmutableList dependencies;
/**
* Creates a new StarlarkComputedDefaultTemplate that allows the computation of attribute values
* via a callback function during loading phase.
*
* @param type The type of the value of this attribute.
* @param dependencies A list of all names of other attributes that are accessed by this
* attribute.
* @param callback A function to compute the actual attribute value.
*/
public StarlarkComputedDefaultTemplate(
Type type, ImmutableList dependencies, StarlarkCallbackHelper callback) {
this.type = Preconditions.checkNotNull(type);
// Order is important for #createDependencyAssignmentTuple.
this.dependencies =
Ordering.natural().immutableSortedCopy(Preconditions.checkNotNull(dependencies));
this.callback = Preconditions.checkNotNull(callback);
}
/**
* Returns a {@link StarlarkComputedDefault} containing a lookup table specifying the output of
* this {@link StarlarkComputedDefaultTemplate}'s callback given each possible assignment {@code
* rule} might make to the attributes specified by {@link #dependencies}.
*
* If the rule is missing an attribute specified by {@link #dependencies}, or if there are
* too many possible assignments, or if any evaluation fails, this throws {@link
* CannotPrecomputeDefaultsException}.
*
*
May only be called after all non-{@link ComputedDefault} attributes have been set on the
* {@code rule}.
*/
StarlarkComputedDefault computePossibleValues(
Attribute attr, final Rule rule, final EventHandler eventHandler)
throws InterruptedException, CannotPrecomputeDefaultsException {
final StarlarkComputedDefaultTemplate owner = StarlarkComputedDefaultTemplate.this;
final String msg =
String.format(
"Cannot compute default value of attribute '%s' in rule '%s': ",
attr.getPublicName(), rule.getLabel());
final AtomicReference caughtEvalExceptionIfAny = new AtomicReference<>();
ComputationStrategy strategy =
new ComputationStrategy<>() {
@Nullable
@Override
public Object compute(AttributeMap map) throws InterruptedException {
try {
return owner.computeValue(eventHandler, map);
} catch (EvalException ex) {
caughtEvalExceptionIfAny.compareAndSet(null, ex);
return null;
}
}
};
ImmutableList.Builder> dependencyTypesBuilder = ImmutableList.builder();
Map, Object> lookupTable;
try {
for (String dependency : dependencies) {
Attribute attribute = rule.getRuleClassObject().getAttributeByNameMaybe(dependency);
if (attribute == null) {
throw new AttributeNotFoundException(
String.format("No such attribute %s in rule %s", dependency, rule.getLabel()));
}
dependencyTypesBuilder.add(attribute.getType());
}
lookupTable =
new HashMap<>(
strategy.computeValuesForAllCombinations(
dependencies, attr.getType(), rule, FixedComputationLimiter.INSTANCE));
if (caughtEvalExceptionIfAny.get() != null) {
throw caughtEvalExceptionIfAny.get();
}
} catch (AttributeNotFoundException
| TooManyConfigurableAttributesException
| EvalException ex) {
String error = msg + ex.getMessage();
rule.reportError(error, eventHandler);
throw new CannotPrecomputeDefaultsException(error);
}
return new StarlarkComputedDefault(dependencies, dependencyTypesBuilder.build(), lookupTable);
}
private Object computeValue(EventHandler eventHandler, AttributeMap rule)
throws EvalException, InterruptedException {
Map attrValues = new HashMap<>();
for (String attrName : rule.getAttributeNames()) {
Attribute attr = rule.getAttributeDefinition(attrName);
if (!attr.hasComputedDefault()) {
Object value = rule.get(attrName, attr.getType());
if (!Starlark.isNullOrNone(value)) {
// Some attribute values are not valid Starlark values:
// visibility is an ImmutableList, for example.
attrValues.put(attr.getName(), Starlark.fromJava(value, /*mutability=*/ null));
}
}
}
return invokeCallback(eventHandler, attrValues);
}
private Object invokeCallback(EventHandler eventHandler, Map attrValues)
throws EvalException, InterruptedException {
Structure attrs =
StructProvider.STRUCT.create(
attrValues, "No such regular (non computed) attribute '%s'.");
Object result = callback.call(eventHandler, attrs);
try {
return type.cast((result == Starlark.NONE) ? type.getDefaultValue() : result);
} catch (ClassCastException ex) {
throw Starlark.errorf("expected '%s', but got '%s'", type, Starlark.type(result));
}
}
private static class AttributeNotFoundException extends Exception {
private AttributeNotFoundException(String message) {
super(message);
}
}
static class CannotPrecomputeDefaultsException extends Exception {
private CannotPrecomputeDefaultsException(String message) {
super(message);
}
}
}
/**
* A class for computed attributes defined in Starlark.
*
* Unlike {@link ComputedDefault}, instances of this class contain a pre-computed table of all
* possible assignments of depended-on attributes and what the Starlark function evaluates to, and
* {@link #getPossibleValues(Type, Rule)} and {@link #getDefault(AttributeMap)} do lookups in that
* table.
*/
static final class StarlarkComputedDefault extends ComputedDefault {
private final ImmutableList> dependencyTypes;
private final Map, Object> lookupTable;
/**
* Creates a new StarlarkComputedDefault containing a lookup table.
*
* @param dependencies A list of all names of other attributes that are accessed by this
* attribute.
* @param dependencyTypes A list of requiredAttributes' types.
* @param lookupTable An exhaustive mapping from requiredAttributes assignments to values this
* computed default evaluates to.
*/
StarlarkComputedDefault(
ImmutableList dependencies,
ImmutableList> dependencyTypes,
Map, Object> lookupTable) {
super(Preconditions.checkNotNull(dependencies));
this.dependencyTypes = Preconditions.checkNotNull(dependencyTypes);
this.lookupTable = Preconditions.checkNotNull(lookupTable);
}
ImmutableList> getDependencyTypes() {
return dependencyTypes;
}
Map, Object> getLookupTable() {
return lookupTable;
}
@Override
public Object getDefault(AttributeMap rule) {
List key = ComputationStrategy.createDependencyAssignmentTuple(dependencies(), rule);
Preconditions.checkState(
lookupTable.containsKey(key),
"Error in rule '%s': precomputed value missing for dependencies: %s. Available keys: %s.",
rule.getLabel(),
Iterables.toString(key),
Iterables.toString(lookupTable.keySet()));
return lookupTable.get(key);
}
@Override
List getPossibleValues(Type type, Rule rule) {
List result = new ArrayList<>(lookupTable.size());
for (Object obj : lookupTable.values()) {
result.add(type.cast(obj));
}
return result;
}
}
static class SimpleLateBoundDefault
extends LateBoundDefault {
private final Resolver resolver;
private SimpleLateBoundDefault(
Class fragmentClass,
Function defaultValueEvaluator,
Resolver resolver) {
super(fragmentClass, defaultValueEvaluator);
this.resolver = resolver;
}
@Override
public ValueT resolve(Rule rule, AttributeMap attributes, FragmentT input) {
return resolver.resolve(rule, attributes, input);
}
}
// TODO(b/65746853): Remove documentation about accepting BuildConfigurationValue when uses are
// cleaned
// up.
/**
* Provider of values for late-bound attributes. See {@link
* Attribute.Builder#value(LateBoundDefault)}.
*
* Use sparingly - having different values for attributes during loading and analysis can
* confuse users.
*
* @param The type of value that is used to compute this value. This is usually a
* subclass of BuildConfigurationValue.Fragment. It may also be Void to receive null, or
* BuildConfigurationValue itself to receive the entire configuration.
* @param The type of value returned by this class. Must be either {@link Void}, a {@link
* Label}, or a {@link List} of {@link Label} objects.
*/
@Immutable
public abstract static class LateBoundDefault implements StarlarkValue {
/**
* Functional interface for computing the value of a late-bound attribute.
*
* Implementations of this interface must be immutable.
*/
@FunctionalInterface
public interface Resolver {
ValueT resolve(Rule rule, AttributeMap attributeMap, FragmentT input);
}
private final Function defaultValueEvaluator;
private final Class fragmentClass;
/**
* Creates a new LateBoundDefault which always returns the given value.
*
* This is used primarily for matching names with late-bound attributes on other rules and
* for testing. Use normal default values if the name does not matter.
*/
@VisibleForTesting
public static LabelLateBoundDefault fromConstantForTesting(Label defaultValue) {
return new LabelLateBoundDefault<>(
Void.class,
(rule) -> Preconditions.checkNotNull(defaultValue),
(rule, attributes, unused) -> defaultValue) {};
}
/**
* Creates a new LateBoundDefault which always returns null.
*
* This is used primarily for matching names with late-bound attributes on other rules and
* for testing. Use normal default values if the name does not matter.
*/
@SuppressWarnings("unchecked") // bivariant implementation
public static LateBoundDefault alwaysNull() {
return (LateBoundDefault) AlwaysNullLateBoundDefault.INSTANCE;
}
LateBoundDefault(Class fragmentClass, Function defaultValueEvaluator) {
this.defaultValueEvaluator = defaultValueEvaluator;
this.fragmentClass = fragmentClass;
}
/**
* Returns the input type that the attribute expects. This is almost always a configuration
* fragment to be retrieved from the target's configuration (or the exec configuration).
*
* It may also be {@link Void} to receive null. This is rarely necessary, but can be used,
* e.g., if the attribute is named to match an attribute in another rule which is late-bound.
*
*
It may also be BuildConfigurationValue to receive the entire configuration. This is
* deprecated, and only necessary when the default is computed from methods of
* BuildConfigurationValue itself.
*/
public final Class getFragmentClass() {
return fragmentClass;
}
/** The default value for the attribute that is set during the loading phase. */
public ValueT getDefault(@Nullable Rule rule) {
return defaultValueEvaluator.apply(rule);
}
/**
* The actual value for the attribute for the analysis phase, which depends on the build
* configuration. Note that configurations transitions are applied after the late-bound
* attribute was evaluated.
*
* @param rule the rule being evaluated
* @param attributes interface for retrieving the values of the rule's other attributes
* @param input the configuration fragment to evaluate with
*/
public abstract ValueT resolve(Rule rule, AttributeMap attributes, FragmentT input);
}
/**
* An abstract {@link LateBoundDefault} class so that {@code StarlarkLateBoundDefault} can derive
* from {@link LateBoundDefault} without compromising the type-safety of the second generic
* parameter to {@link LateBoundDefault}.
*/
public abstract static class AbstractLabelLateBoundDefault
extends LateBoundDefault {
protected AbstractLabelLateBoundDefault(Class fragmentClass, Label defaultValue) {
super(fragmentClass, (Function & Serializable) (rule) -> defaultValue);
}
}
@AutoCodec.VisibleForSerialization
static class AlwaysNullLateBoundDefault extends SimpleLateBoundDefault {
@SerializationConstant @AutoCodec.VisibleForSerialization
static final AlwaysNullLateBoundDefault INSTANCE = new AlwaysNullLateBoundDefault();
private AlwaysNullLateBoundDefault() {
super(Void.class, (rule) -> null, (rule, attributes, unused) -> null);
}
}
/** A {@link LateBoundDefault} for a {@link Label}. */
public static class LabelLateBoundDefault
extends SimpleLateBoundDefault {
@VisibleForTesting
protected LabelLateBoundDefault(
Class fragmentClass,
Function defaultValueEvaluator,
Resolver resolver) {
super(fragmentClass, defaultValueEvaluator, resolver);
}
/**
* Creates a new LabelLateBoundDefault which uses the rule, its configured attributes, and a
* fragment of the target configuration.
*
* Note that the configuration fragment here does not take into account any transitions that
* are on the attribute with this LabelLateBoundDefault as its value. The configuration will be
* the same as the configuration given to the target bearing the attribute.
*
*
Nearly all LateBoundDefaults should use this constructor or {@link
* LabelListLateBoundDefault#fromTargetConfiguration}. There are few situations where it isn't
* the appropriate option.
*
*
If you want to decide an attribute's value based on the value of its other attributes, use
* a subclass of {@link ComputedDefault}. The only time you should need {@link
* LabelListLateBoundDefault#fromRuleAndAttributesOnly} is if you need access to three or more
* configurable attributes, or if you need to match names with a late-bound attribute on another
* rule.
*
*
If you have a constant-valued attribute, but you need it to have the same name as an
* attribute on another rule which is late-bound, use {@link #alwaysNull}.
*
* @param fragmentClass The fragment to receive from the target configuration. May also be
* BuildConfigurationValue.class to receive the entire configuration (deprecated) - in this
* case, you must only use methods of BuildConfigurationValue itself, and not use any
* fragments.
* @param defaultValue The default {@link Label} to return at loading time, when the
* configuration is not available.
* @param resolver A function which will compute the actual value with the configuration.
*/
public static LabelLateBoundDefault fromTargetConfiguration(
Class fragmentClass, Label defaultValue, Resolver resolver) {
return fromTargetConfigurationWithRuleBasedDefault(
fragmentClass, (Function & Serializable) (rule) -> defaultValue, resolver);
}
/**
* Variant of {@link #fromTargetConfiguration} that can read the rule instance to determine the
* default value (e.g. by reading an attribute).
*
* Has a different name than {@link #fromTargetConfiguration} because many callers to {@link
* #fromTargetConfiguration} pass a null value to the {@code defaultValue} parameter, which
* makes a proper method overload ambiguous.
*/
public static
LabelLateBoundDefault fromTargetConfigurationWithRuleBasedDefault(
Class fragmentClass,
Function defaultValueEvaluator,
Resolver resolver) {
Preconditions.checkArgument(
!fragmentClass.equals(Void.class),
"Use fromRuleAndAttributesOnly to specify a LateBoundDefault which does not use "
+ "configuration.");
return new LabelLateBoundDefault<>(fragmentClass, defaultValueEvaluator, resolver);
}
}
/** A {@link LateBoundDefault} for a {@link List} of {@link Label} objects. */
public static class LabelListLateBoundDefault
extends SimpleLateBoundDefault> {
private LabelListLateBoundDefault(
Class fragmentClass, Resolver> resolver) {
super(
fragmentClass,
(Function> & Serializable) (rule) -> ImmutableList.of(),
resolver);
}
public static LabelListLateBoundDefault fromTargetConfiguration(
Class fragmentClass, Resolver> resolver) {
Preconditions.checkArgument(
!fragmentClass.equals(Void.class),
"Use fromRuleAndAttributesOnly to specify a LateBoundDefault which does not use "
+ "configuration.");
return new LabelListLateBoundDefault<>(fragmentClass, resolver);
}
/**
* Creates a new LabelListLateBoundDefault which uses only the rule and its configured
* attributes.
*
* This should only be necessary in very specialized cases. In almost all cases, you don't
* need this method, just use {@link ComputedDefault}.
*
*
This is used primarily for computing values based on three or more configurable attributes
* and/or matching names with late-bound attributes on other rules.
*
* @param resolver A function which will compute the actual value with the configuration.
*/
public static LabelListLateBoundDefault fromRuleAndAttributesOnly(
Resolver> resolver) {
return new LabelListLateBoundDefault<>(Void.class, resolver);
}
}
private final String name;
private final String doc;
private final Type type;
private final Set propertyFlags;
// Exactly one of these conditions is true:
// 1. defaultValue == null.
// 2. defaultValue instanceof ComputedDefault &&
// type.isValid(defaultValue.getDefault())
// 3. defaultValue instanceof StarlarkComputedDefaultTemplate &&
// type.isValid(defaultValue.computePossibleValues().getDefault())
// 4. type.isValid(defaultValue).
// 5. defaultValue instanceof LateBoundDefault &&
// type.isValid(defaultValue.getDefault(configuration))
// (We assume a hypothetical Type.isValid(Object) predicate.)
private final Object defaultValue;
private final TransitionFactory transitionFactory;
/**
* For label or label-list attributes, this predicate returns which rule classes are allowed for
* the targets in the attribute.
*/
private final RuleClassNamePredicate allowedRuleClassesForLabels;
/**
* For label or label-list attributes, this predicate returns which rule classes are allowed for
* the targets in the attribute with warning.
*/
private final RuleClassNamePredicate allowedRuleClassesForLabelsWarning;
/**
* For label or label-list attributes, this predicate returns which file types are allowed for
* targets in the attribute that happen to be file targets (rather than rules).
*/
private final FileTypeSet allowedFileTypesForLabels;
/**
* This predicate-like object checks if the edge between two rules using this attribute is valid
* in the dependency graph. Returns null if valid, otherwise an error message.
*/
private final ValidityPredicate validityPredicate;
private final PredicateWithMessage allowedValues;
private final RequiredProviders requiredProviders;
private final ImmutableList> aspects;
private final int hashCode;
/**
* Constructs a rule attribute with the specified name, type and default value.
*
* @param name the name of the attribute
* @param type the type of the attribute
* @param defaultValue the default value to use for this attribute if none is specified in rule
* declaration in the BUILD file. Must be null, or of type "type". May be an instance of
* ComputedDefault, in which case its getDefault() method must return an instance of "type",
* or null. Must be immutable.
* @param transitionFactory the configuration transition for this attribute (which must be of type
* LABEL, LABEL_LIST, NODEP_LABEL or NODEP_LABEL_LIST).
*/
private Attribute(
String name,
String doc,
Type type,
Set propertyFlags,
Object defaultValue,
TransitionFactory transitionFactory,
RuleClassNamePredicate allowedRuleClassesForLabels,
RuleClassNamePredicate allowedRuleClassesForLabelsWarning,
FileTypeSet allowedFileTypesForLabels,
ValidityPredicate validityPredicate,
PredicateWithMessage allowedValues,
RequiredProviders requiredProviders,
ImmutableList> aspects) {
Preconditions.checkArgument(
NoTransition.isInstance(transitionFactory)
|| type.getLabelClass() == LabelClass.DEPENDENCY
|| type.getLabelClass() == LabelClass.NONDEP_REFERENCE,
"Configuration transitions can only be specified for label or label list attributes");
Preconditions.checkArgument(
isLateBound(name) == (defaultValue instanceof LateBoundDefault),
"late bound attributes require a default value that is late bound (and vice versa): %s",
name);
this.name = name;
this.doc = doc;
this.type = type;
this.propertyFlags = propertyFlags;
this.defaultValue = defaultValue;
this.transitionFactory = transitionFactory;
this.allowedRuleClassesForLabels = allowedRuleClassesForLabels;
this.allowedRuleClassesForLabelsWarning = allowedRuleClassesForLabelsWarning;
this.allowedFileTypesForLabels = allowedFileTypesForLabels;
this.validityPredicate = validityPredicate;
this.allowedValues = allowedValues;
this.requiredProviders = requiredProviders;
this.aspects = aspects;
this.hashCode =
Objects.hash(
name,
doc,
type,
propertyFlags,
defaultValue,
transitionFactory,
allowedRuleClassesForLabels,
allowedRuleClassesForLabelsWarning,
allowedFileTypesForLabels,
validityPredicate,
allowedValues,
requiredProviders,
aspects);
}
/** Returns the name of this attribute. */
public String getName() {
return name;
}
/** Returns the doc string for that attribute, if any. */
public String getDoc() {
return doc;
}
/**
* Returns the public name of this attribute. This is the name we use in Starlark code and we can
* use it to display to the end-user. Implicit and late-bound attributes start with '_' (instead
* of '$' or ':').
*/
public String getPublicName() {
return getStarlarkName(name);
}
/**
* Returns the logical type of this attribute. (May differ from the actual representation as a
* value in the build interpreter; for example, an attribute may logically be a list of labels,
* but be represented as a list of strings.)
*/
public Type getType() {
return type;
}
private boolean getPropertyFlag(PropertyFlag flag) {
return propertyFlags.contains(flag);
}
/** Returns true if this parameter is mandatory. */
public boolean isMandatory() {
return getPropertyFlag(PropertyFlag.MANDATORY);
}
/** Returns true if this list parameter cannot have an empty list as a value. */
public boolean isNonEmpty() {
return getPropertyFlag(PropertyFlag.NON_EMPTY);
}
/** Returns true if this label parameter must produce a single artifact. */
public boolean isSingleArtifact() {
return getPropertyFlag(PropertyFlag.SINGLE_ARTIFACT);
}
/** Returns true if this label type parameter is checked by silent ruleclass filtering. */
public boolean isSilentRuleClassFilter() {
return getPropertyFlag(PropertyFlag.SILENT_RULECLASS_FILTER);
}
/** Returns true if this label type parameter skips the analysis time filetype check. */
public boolean isSkipAnalysisTimeFileTypeCheck() {
return getPropertyFlag(PropertyFlag.SKIP_ANALYSIS_TIME_FILETYPE_CHECK);
}
/** Returns true if this parameter is order-independent. */
public boolean isOrderIndependent() {
return getPropertyFlag(PropertyFlag.ORDER_INDEPENDENT);
}
/** Returns true if output_licenses should be used for checking licensing. */
public boolean useOutputLicenses() {
return getPropertyFlag(PropertyFlag.OUTPUT_LICENSES);
}
/**
* Returns true if this attribute uses a starlark-defined, non analysis-test configuration
* transition. Starlark-defined analysis-test configuration transitions are handled separately.
* See {@link #hasAnalysisTestTransition}.
*/
public boolean hasStarlarkDefinedTransition() {
return getPropertyFlag(PropertyFlag.HAS_STARLARK_DEFINED_TRANSITION);
}
/**
* Returns true if this attributes uses Starlark-defined configuration transition designed
* specifically for rules which run analysis tests.
*/
public boolean hasAnalysisTestTransition() {
return getPropertyFlag(PropertyFlag.HAS_ANALYSIS_TEST_TRANSITION);
}
/**
* Returns the configuration transition factory for this attribute for label or label list
* attributes. For other attributes it will always return {@code NONE}.
*/
public TransitionFactory getTransitionFactory() {
return transitionFactory;
}
/**
* Returns whether the target is required to be executable for label or label list attributes. For
* other attributes it always returns {@code false}.
*/
public boolean isExecutable() {
return getPropertyFlag(PropertyFlag.EXECUTABLE);
}
/** Returns {@code true} iff the rule is a direct input for an action. */
public boolean isDirectCompileTimeInput() {
return getPropertyFlag(PropertyFlag.DIRECT_COMPILE_TIME_INPUT);
}
/** Returns {@code true} iff this attribute requires documentation. */
public boolean isDocumented() {
return !getPropertyFlag(PropertyFlag.UNDOCUMENTED);
}
/**
* Returns {@code true} iff this attribute should be published to the rule's tag set. Note that
* not all Type classes support tag conversion.
*/
public boolean isTaggable() {
return getPropertyFlag(PropertyFlag.TAGGABLE);
}
public boolean isStrictLabelCheckingEnabled() {
return getPropertyFlag(PropertyFlag.STRICT_LABEL_CHECKING);
}
/** Returns true if the value of this attribute should be a part of a given set. */
public boolean checkAllowedValues() {
return getPropertyFlag(PropertyFlag.CHECK_ALLOWED_VALUES);
}
public boolean performPrereqValidatorCheck() {
return !getPropertyFlag(PropertyFlag.SKIP_PREREQ_VALIDATOR_CHECKS);
}
public boolean checkConstraintsOverride() {
return getPropertyFlag(PropertyFlag.CHECK_CONSTRAINTS_OVERRIDE);
}
public boolean skipConstraintsOverride() {
return getPropertyFlag(PropertyFlag.SKIP_CONSTRAINTS_OVERRIDE);
}
/** Returns true if this attribute's value can be influenced by the build configuration. */
public boolean isConfigurable() {
// Output types are excluded because of Rule#populateExplicitOutputFiles.
return type.getLabelClass() != LabelClass.OUTPUT
&& !getPropertyFlag(PropertyFlag.NONCONFIGURABLE);
}
/**
* Returns true if this attribute is used as a tool dependency, either because the attribute
* declares it directly (with {@link Attribute.Builder#tool}), or because the value's {@link
* TransitionFactory} declares it.
*
* Non-dependency attributes will always return {@code false}.
*/
public boolean isToolDependency() {
if (type.getLabelClass() != LabelClass.DEPENDENCY) {
return false;
}
if (getPropertyFlag(PropertyFlag.IS_TOOL_DEPENDENCY)) {
return true;
}
return transitionFactory.isTool();
}
/**
* Returns true if this attribute was defined using Starlark's {@code attrs} module.
*
*
This may be used as a hint by documentation generators; for example, in the documentation
* for a Starlark rule, we may want to fully document the Starlark-defined attributes set via
* {@code rule(attrs=...)}), but skip or abbreviate documentation for implicitly added
* non-Starlark attributes like "tags" and "testonly".
*/
public boolean starlarkDefined() {
return getPropertyFlag(PropertyFlag.STARLARK_DEFINED);
}
/**
* Returns a predicate that evaluates to true for rule classes that are allowed labels in this
* attribute. If this is not a label or label-list attribute, the returned predicate always
* evaluates to true.
*
*
NOTE: This may return Predicates.alwaysTrue() as a sentinel meaning "do the right
* thing", rather than actually allowing all rule classes in that attribute. Others parts of bazel
* code check for that specific instance.
*/
public Predicate getAllowedRuleClassObjectPredicate() {
return allowedRuleClassesForLabels.asPredicateOfRuleClassObject();
}
public Predicate getAllowedRuleClassPredicate() {
return allowedRuleClassesForLabels.asPredicateOfRuleClass();
}
/**
* Returns a predicate that evaluates to true for rule classes that are allowed labels in this
* attribute with warning. If this is not a label or label-list attribute, the returned predicate
* always evaluates to true.
*/
public Predicate getAllowedRuleClassObjectWarningPredicate() {
return allowedRuleClassesForLabelsWarning.asPredicateOfRuleClassObject();
}
public Predicate getAllowedRuleClassWarningPredicate() {
return allowedRuleClassesForLabelsWarning.asPredicateOfRuleClass();
}
public RequiredProviders getRequiredProviders() {
return requiredProviders;
}
public FileTypeSet getAllowedFileTypesPredicate() {
return allowedFileTypesForLabels;
}
public ValidityPredicate getValidityPredicate() {
return validityPredicate;
}
public PredicateWithMessage getAllowedValues() {
return allowedValues;
}
public boolean hasAspects() {
return !aspects.isEmpty();
}
/** Returns the list of aspects required for dependencies through this attribute. */
public ImmutableList getAspects(Rule rule) {
if (aspects.isEmpty()) {
return ImmutableList.of();
}
ImmutableList.Builder builder = null;
for (AspectDetails aspect : aspects) {
Aspect a = aspect.getAspect(rule);
if (a != null) {
if (builder == null) {
builder = ImmutableList.builder();
}
builder.add(a);
}
}
return builder == null ? ImmutableList.of() : builder.build();
}
public ImmutableList getAspectClasses() {
ImmutableList.Builder result = ImmutableList.builder();
for (AspectDetails aspect : aspects) {
result.add(aspect.getAspectClass());
}
return result.build();
}
public ImmutableList> getAspectsDetails() {
return aspects;
}
/**
* Returns the default value of this attribute.
*
* The result may be null (although this is not a value in the build language).
*
*
During population of the rule's attribute dictionary, all non-computed defaults must be set
* before all computed ones.
*
* @param rule the rule this attribute is attached to, if one exists. Otherwise null. Aspect
* attributes, for example, aren't associated with rules. The {@link LabelLateBoundDefault}'s
* author is responsible for ensuring null inputs work properly: either {@link
* LateBoundDefault#getDefaultValue(Rule)} works on null inputs or the attribute is known to
* always be attached to rules.
*/
@Nullable
public Object getDefaultValue(@Nullable Rule rule) {
if (defaultValue instanceof LateBoundDefault) {
return ((LateBoundDefault) defaultValue).getDefault(rule);
} else {
return defaultValue;
}
}
/**
* Returns the default value of this attribute, even if it is a computed default, or a late-bound
* default.
*/
public Object getDefaultValueUnchecked() {
return defaultValue;
}
public LateBoundDefault getLateBoundDefault() {
Preconditions.checkState(isLateBound());
return (LateBoundDefault) defaultValue;
}
/**
* Returns true iff this attribute has a computed default.
*
* @see #getDefaultValue
*/
boolean hasComputedDefault() {
return defaultValue instanceof ComputedDefault
|| defaultValue instanceof StarlarkComputedDefaultTemplate;
}
/**
* Returns if this attribute is an implicit dependency according to the naming policy that
* designates implicit attributes.
*/
public boolean isImplicit() {
return isImplicit(name);
}
/**
* Returns if an attribute with the given name is an implicit dependency according to the naming
* policy that designates implicit attributes.
*/
public static boolean isImplicit(String name) {
return name.startsWith("$");
}
/**
* Returns if this attribute is late-bound according to the naming policy that designates
* late-bound attributes.
*/
public boolean isLateBound() {
return isLateBound(name);
}
/**
* Returns if an attribute with the given name is late-bound according to the naming policy that
* designates late-bound attributes.
*/
public static boolean isLateBound(String name) {
return name.startsWith(":");
}
/** Returns whether this attribute is considered private in Starlark. */
private static boolean isPrivateAttribute(String nativeAttrName) {
return isLateBound(nativeAttrName) || isImplicit(nativeAttrName);
}
/**
* Returns the Starlark-usable name of this attribute.
*
*
Implicit and late-bound attributes start with '_' (instead of '$' or ':').
*/
public static String getStarlarkName(String nativeAttrName) {
if (isPrivateAttribute(nativeAttrName)) {
return "_" + nativeAttrName.substring(1);
}
return nativeAttrName;
}
@Override
public String toString() {
return "Attribute(" + name + ", " + type + ")";
}
@Override
public int compareTo(Attribute other) {
return name.compareTo(other.name);
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
Attribute attribute = (Attribute) o;
return hashCode == attribute.hashCode
&& Objects.equals(name, attribute.name)
&& Objects.equals(doc, attribute.doc)
&& Objects.equals(type, attribute.type)
&& Objects.equals(propertyFlags, attribute.propertyFlags)
&& Objects.equals(defaultValue, attribute.defaultValue)
&& Objects.equals(transitionFactory, attribute.transitionFactory)
&& Objects.equals(allowedRuleClassesForLabels, attribute.allowedRuleClassesForLabels)
&& Objects.equals(
allowedRuleClassesForLabelsWarning, attribute.allowedRuleClassesForLabelsWarning)
&& Objects.equals(allowedFileTypesForLabels, attribute.allowedFileTypesForLabels)
&& Objects.equals(validityPredicate, attribute.validityPredicate)
&& Objects.equals(allowedValues, attribute.allowedValues)
&& Objects.equals(requiredProviders, attribute.requiredProviders)
&& Objects.equals(aspects, attribute.aspects);
}
@Override
public int hashCode() {
return hashCode;
}
/** Returns a replica builder of this Attribute. */
public Attribute.Builder cloneBuilder(Type tp) {
Preconditions.checkArgument(tp == this.type);
Builder builder = new Builder<>(name, tp);
builder.doc = doc;
builder.allowedFileTypesForLabels = allowedFileTypesForLabels;
builder.allowedRuleClassesForLabels = allowedRuleClassesForLabels;
builder.allowedRuleClassesForLabelsWarning = allowedRuleClassesForLabelsWarning;
builder.requiredProvidersBuilder = requiredProviders.copyAsBuilder();
builder.validityPredicate = validityPredicate;
builder.transitionFactory = transitionFactory;
builder.propertyFlags = newEnumSet(propertyFlags, PropertyFlag.class);
builder.value = defaultValue;
builder.valueSet = false;
builder.allowedValues = allowedValues;
builder.aspectsListBuilder = new AspectsListBuilder(aspects);
return builder;
}
public Attribute.Builder cloneBuilder() {
return cloneBuilder(this.type);
}
/**
* Converts a rule attribute value from internal form to Starlark form. Internal form may use any
* subtype of {@link List} or {@link Map} for {@code list} and {@code dict} attributes, whereas
* Starlark uses only immutable {@link net.starlark.java.eval.StarlarkList} and {@link Dict}.
*
* The conversion is similar to {@link Starlark#fromJava} for all types except {@code
* attr.string_list_dict} ({@code Map>}), for which fromJava does not
* recursively convert elements. (Doing so is expensive.)
*
* It is tempting to require that attributes are stored internally in Starlark form. However, a
* number of obstacles would need to be overcome:
*
*
* Some obscure attribute types such as TRISTATE and DISTRIBUTION are not currently legal
* Starlark values.
* ImmutableList is significantly more compact than StarlarkList for small lists (n < 2).
* StarlarkList would need multiple representations and a builder to achieve parity.
* The types used by the Type mechanism would need changing; this has extensive
* ramifications.
*
*/
public static Object valueToStarlark(Object x) {
// Is x a non-empty string_list_dict?
if (x instanceof Map) {
Map map = (Map) x;
if (!map.isEmpty() && map.values().iterator().next() instanceof List) {
// Recursively convert subelements.
Dict.Builder dict = Dict.builder();
for (Map.Entry e : map.entrySet()) {
dict.put(e.getKey(), Starlark.fromJava(e.getValue(), null));
}
return dict.buildImmutable();
}
}
// For all other attribute values, shallow conversion is safe.
return Starlark.fromJava(x, null);
}
}