// Copyright 2014 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.rules;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.Iterables;
import com.google.devtools.build.lib.cmdline.Label;
import com.google.devtools.build.lib.events.Location;
import com.google.devtools.build.lib.packages.Attribute;
import com.google.devtools.build.lib.packages.Attribute.AllowedValueSet;
import com.google.devtools.build.lib.packages.Attribute.ConfigurationTransition;
import com.google.devtools.build.lib.packages.Attribute.SkylarkComputedDefaultTemplate;
import com.google.devtools.build.lib.packages.Attribute.SplitTransition;
import com.google.devtools.build.lib.packages.AttributeValueSource;
import com.google.devtools.build.lib.packages.BuildType;
import com.google.devtools.build.lib.packages.ClassObjectConstructor;
import com.google.devtools.build.lib.packages.SkylarkAspect;
import com.google.devtools.build.lib.packages.SkylarkProviderIdentifier;
import com.google.devtools.build.lib.skylarkinterface.Param;
import com.google.devtools.build.lib.skylarkinterface.ParamType;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter;
import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
import com.google.devtools.build.lib.skylarkinterface.SkylarkValue;
import com.google.devtools.build.lib.syntax.BuiltinFunction;
import com.google.devtools.build.lib.syntax.Environment;
import com.google.devtools.build.lib.syntax.EvalException;
import com.google.devtools.build.lib.syntax.EvalUtils;
import com.google.devtools.build.lib.syntax.FuncallExpression;
import com.google.devtools.build.lib.syntax.Runtime;
import com.google.devtools.build.lib.syntax.SkylarkCallbackFunction;
import com.google.devtools.build.lib.syntax.SkylarkDict;
import com.google.devtools.build.lib.syntax.SkylarkList;
import com.google.devtools.build.lib.syntax.SkylarkSignatureProcessor;
import com.google.devtools.build.lib.syntax.SkylarkType;
import com.google.devtools.build.lib.syntax.Type;
import com.google.devtools.build.lib.syntax.Type.ConversionException;
import com.google.devtools.build.lib.syntax.Type.LabelClass;
import com.google.devtools.build.lib.syntax.UserDefinedFunction;
import com.google.devtools.build.lib.util.FileType;
import com.google.devtools.build.lib.util.FileTypeSet;
import com.google.devtools.build.lib.util.Preconditions;
import java.util.List;
import java.util.Map;
import javax.annotation.Nullable;
/**
* A helper class to provide Attr module in Skylark.
*
*
It exposes functions (e.g. 'attr.string', 'attr.label_list', etc.) to Skylark users. The
* functions are executed through reflection. As everywhere in Skylark, arguments are type-checked
* with the signature and cannot be null.
*/
@SkylarkModule(
name = "attr",
namespace = true,
category = SkylarkModuleCategory.BUILTIN,
doc =
"Module for creating new attributes. "
+ "They are only for use with rule or "
+ "aspect."
)
public final class SkylarkAttr implements SkylarkValue {
// Arguments
private static final String ALLOW_FILES_ARG = "allow_files";
private static final String ALLOW_FILES_DOC =
"whether File targets are allowed. Can be True, False (default), or a list of file "
+ "extensions that are allowed (e.g. [\".cc\", \".cpp\"]).";
private static final String ALLOW_RULES_ARG = "allow_rules";
private static final String ALLOW_RULES_DOC =
"which rule targets (name of the classes) are allowed. This is deprecated (kept only for "
+ "compatibility), use providers instead.";
private static final String ASPECTS_ARG = "aspects";
private static final String ASPECTS_ARG_DOC =
"aspects that should be applied to the dependency or dependencies specified by this "
+ "attribute";
private static final String CONFIGURATION_ARG = "cfg";
private static final String CONFIGURATION_DOC =
"configuration of the attribute. It can be either \"data\", \"host\", or \"target\". "
+ "This parameter is required if executable is True.";
private static final String DEFAULT_ARG = "default";
private static final String DEFAULT_DOC = "the default value of the attribute.";
private static final String DOC_ARG = "doc";
private static final String DOC_DOC =
"a description of the attribute that can be extracted by documentation generating tools.";
private static final String EXECUTABLE_ARG = "executable";
private static final String EXECUTABLE_DOC =
"True if the labels have to be executable. This means the label must refer to an "
+ "executable file, or to a rule that outputs an executable file. Access the labels "
+ "with ctx.executable.<attribute_name>.";
private static final String FLAGS_ARG = "flags";
private static final String FLAGS_DOC = "deprecated, will be removed";
private static final String MANDATORY_ARG = "mandatory";
private static final String MANDATORY_DOC = "True if the value must be explicitly specified";
private static final String NON_EMPTY_ARG = "non_empty";
private static final String NON_EMPTY_DOC =
"True if the attribute must not be empty. Deprecated: Use allow_empty instead.";
private static final String ALLOW_EMPTY_ARG = "allow_empty";
private static final String ALLOW_EMPTY_DOC = "True if the attribute can be empty";
private static final String PROVIDERS_ARG = "providers";
private static final String PROVIDERS_DOC =
"mandatory providers list. It should be either a list of providers, or a "
+ "list of lists of providers. Every dependency should provide ALL providers "
+ "from at least ONE of these lists. A single list of providers will be "
+ "automatically converted to a list containing one list of providers.";
private static final String SINGLE_FILE_ARG = "single_file";
private static final String ALLOW_SINGLE_FILE_ARG = "allow_single_file";
private static final String VALUES_ARG = "values";
private static final String VALUES_DOC =
"the list of allowed values for the attribute. An error is raised if any other "
+ "value is given.";
private static boolean containsNonNoneKey(SkylarkDict arguments, String key) {
return arguments.containsKey(key) && arguments.get(key) != Runtime.NONE;
}
private static void setAllowedFileTypes(
String attr, Object fileTypesObj, FuncallExpression ast, Attribute.Builder> builder)
throws EvalException {
if (fileTypesObj == Boolean.TRUE) {
builder.allowedFileTypes(FileTypeSet.ANY_FILE);
} else if (fileTypesObj == Boolean.FALSE) {
builder.allowedFileTypes(FileTypeSet.NO_FILE);
} else if (fileTypesObj instanceof SkylarkFileType) {
// TODO(laurentlb): deprecated, to be removed
builder.allowedFileTypes(((SkylarkFileType) fileTypesObj).getFileTypeSet());
} else if (fileTypesObj instanceof SkylarkList) {
List arg =
SkylarkList.castSkylarkListOrNoneToList(
fileTypesObj, String.class, "allow_files argument");
builder.allowedFileTypes(FileType.of(arg));
} else {
throw new EvalException(
ast.getLocation(), attr + " should be a boolean or a string list");
}
}
private static Attribute.Builder> createAttribute(
Type> type, SkylarkDict arguments, FuncallExpression ast, Environment env)
throws EvalException {
// We use an empty name now so that we can set it later.
// This trick makes sense only in the context of Skylark (builtin rules should not use it).
return createAttribute(type, arguments, ast, env, "");
}
private static Attribute.Builder> createAttribute(
Type> type,
SkylarkDict arguments,
FuncallExpression ast,
Environment env,
String name)
throws EvalException {
Attribute.Builder> builder = Attribute.attr(name, type);
Object defaultValue = arguments.get(DEFAULT_ARG);
if (!EvalUtils.isNullOrNone(defaultValue)) {
if (defaultValue instanceof UserDefinedFunction) {
// Computed attribute. Non label type attributes already caused a type check error.
SkylarkCallbackFunction callback =
new SkylarkCallbackFunction((UserDefinedFunction) defaultValue, ast, env);
// SkylarkComputedDefaultTemplate needs to know the names of all attributes that it depends
// on. However, this method does not know anything about other attributes.
// We solve this problem by asking the SkylarkCallbackFunction for the parameter names used
// in the function definition, which must be the names of attributes used by the callback.
builder.value(
new SkylarkComputedDefaultTemplate(
type, callback.getParameterNames(), callback, ast.getLocation()));
} else {
builder.defaultValue(defaultValue, env.getGlobals().getTransitiveLabel(), DEFAULT_ARG);
}
}
for (String flag : SkylarkList.castSkylarkListOrNoneToList(
arguments.get(FLAGS_ARG), String.class, FLAGS_ARG)) {
builder.setPropertyFlag(flag);
}
if (containsNonNoneKey(arguments, MANDATORY_ARG) && (Boolean) arguments.get(MANDATORY_ARG)) {
builder.setPropertyFlag("MANDATORY");
}
// TODO(laurentlb): Deprecated, remove in August 2016 (use allow_empty instead).
if (containsNonNoneKey(arguments, NON_EMPTY_ARG) && (Boolean) arguments.get(NON_EMPTY_ARG)) {
builder.setPropertyFlag("NON_EMPTY");
}
if (containsNonNoneKey(arguments, ALLOW_EMPTY_ARG)
&& !(Boolean) arguments.get(ALLOW_EMPTY_ARG)) {
builder.setPropertyFlag("NON_EMPTY");
}
if (containsNonNoneKey(arguments, EXECUTABLE_ARG) && (Boolean) arguments.get(EXECUTABLE_ARG)) {
builder.setPropertyFlag("EXECUTABLE");
if (!containsNonNoneKey(arguments, CONFIGURATION_ARG)) {
throw new EvalException(
ast.getLocation(),
"cfg parameter is mandatory when executable=True is provided. Please see "
+ "https://www.bazel.build/versions/master/docs/skylark/rules.html#configurations "
+ "for more details.");
}
}
// TODO(laurentlb): Deprecated, remove in August 2016 (use allow_single_file).
if (containsNonNoneKey(arguments, SINGLE_FILE_ARG)
&& (Boolean) arguments.get(SINGLE_FILE_ARG)) {
if (containsNonNoneKey(arguments, ALLOW_SINGLE_FILE_ARG)) {
throw new EvalException(
ast.getLocation(),
"Cannot specify both single_file (deprecated) and allow_single_file");
}
builder.setPropertyFlag("SINGLE_ARTIFACT");
}
if (containsNonNoneKey(arguments, ALLOW_FILES_ARG)
&& containsNonNoneKey(arguments, ALLOW_SINGLE_FILE_ARG)) {
throw new EvalException(
ast.getLocation(), "Cannot specify both allow_files and allow_single_file");
}
if (containsNonNoneKey(arguments, ALLOW_FILES_ARG)) {
Object fileTypesObj = arguments.get(ALLOW_FILES_ARG);
setAllowedFileTypes(ALLOW_FILES_ARG, fileTypesObj, ast, builder);
} else if (containsNonNoneKey(arguments, ALLOW_SINGLE_FILE_ARG)) {
Object fileTypesObj = arguments.get(ALLOW_SINGLE_FILE_ARG);
setAllowedFileTypes(ALLOW_SINGLE_FILE_ARG, fileTypesObj, ast, builder);
builder.setPropertyFlag("SINGLE_ARTIFACT");
} else if (type.getLabelClass() == LabelClass.DEPENDENCY) {
builder.allowedFileTypes(FileTypeSet.NO_FILE);
}
Object ruleClassesObj = arguments.get(ALLOW_RULES_ARG);
if (ruleClassesObj != null && ruleClassesObj != Runtime.NONE) {
builder.allowedRuleClasses(
SkylarkList.castSkylarkListOrNoneToList(
ruleClassesObj, String.class, "allowed rule classes for attribute definition"));
}
List