// Copyright 2018 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.skylarkbuildapi;
import com.google.common.collect.ImmutableList;
import com.google.devtools.build.lib.cmdline.Label;
import com.google.devtools.build.lib.events.Location;
import com.google.devtools.build.lib.skylarkinterface.Param;
import com.google.devtools.build.lib.skylarkinterface.ParamType;
import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
import com.google.devtools.build.lib.skylarkinterface.SkylarkValue;
import com.google.devtools.build.lib.syntax.ClassObject;
import com.google.devtools.build.lib.syntax.Environment;
import com.google.devtools.build.lib.syntax.EvalException;
import com.google.devtools.build.lib.syntax.FuncallExpression.FuncallException;
import com.google.devtools.build.lib.syntax.Runtime;
import com.google.devtools.build.lib.syntax.SkylarkDict;
import com.google.devtools.build.lib.syntax.SkylarkIndexable;
import com.google.devtools.build.lib.syntax.SkylarkList;
import com.google.devtools.build.lib.syntax.SkylarkList.Tuple;
import com.google.devtools.build.lib.syntax.SkylarkNestedSet;
import java.util.Map;
import javax.annotation.Nullable;
/** Interface for a context object given to rule implementation functions. */
@SkylarkModule(
name = "ctx",
category = SkylarkModuleCategory.BUILTIN,
doc = "The context of the rule containing helper functions and "
+ "information about attributes, depending targets and outputs. "
+ "You get a ctx object as an argument to the implementation function when "
+ "you create a rule.")
public interface SkylarkRuleContextApi extends SkylarkValue {
public static final String DOC_NEW_FILE_TAIL = "Does not actually create a file on the file "
+ "system, just declares that some action will do so. You must create an action that "
+ "generates the file. If the file should be visible to other rules, declare a rule output "
+ "instead when possible. Doing so enables Blaze to associate a label with the file that "
+ "rules can refer to (allowing finer dependency control) instead of referencing the whole "
+ "rule.";
public static final String EXECUTABLE_DOC =
"A struct containing executable files defined in label type "
+ "attributes marked as executable=True. The struct fields correspond "
+ "to the attribute names. Each value in the struct is either a file or "
+ "None. If an optional attribute is not specified in the rule "
+ "then the corresponding struct value is None. If a label type is not "
+ "marked as executable=True, no corresponding struct field is generated. "
+ "See example of use.";
public static final String FILES_DOC =
"A struct containing files defined in label or label list "
+ "type attributes. The struct fields correspond to the attribute names. The struct "
+ "values are list of files. "
+ "It is a shortcut for:"
+ "
[f for t in ctx.attr.<ATTR> for f in t.files]
"
+ "In other words, use files to access the "
+ "default outputs of a "
+ "dependency. "
+ ""
+ "See example of use.";
public static final String FILE_DOC =
"A struct containing files defined in label type "
+ "attributes marked as allow_single_file. The struct fields correspond "
+ "to the attribute names. The struct value is always a file or "
+ "None. If an optional attribute is not specified in the rule "
+ "then the corresponding struct value is None. If a label type is not "
+ "marked as allow_single_file, no corresponding struct field is generated. "
+ "It is a shortcut for:"
+ "
list(ctx.attr.<ATTR>.files)[0]
"
+ "In other words, use file to access the (singular) "
+ "default output of a "
+ "dependency. "
+ "See example of use.";
public static final String ATTR_DOC =
"A struct to access the values of the attributes. The values are provided by "
+ "the user (if not, a default value is used). The attributes of the struct and the "
+ "types of their values correspond to the keys and values of the attrs "
+ "dict provided to the rule function. "
+ "See example of use.";
public static final String SPLIT_ATTR_DOC =
"A struct to access the values of attributes with split configurations. If the attribute is "
+ "a label list, the value of split_attr is a dict of the keys of the split (as strings) "
+ "to lists of the ConfiguredTargets in that branch of the split. If the attribute is a "
+ "label, then the value of split_attr is a dict of the keys of the split (as strings) "
+ "to single ConfiguredTargets. Attributes with split configurations still appear in the "
+ "attr struct, but their values will be single lists with all the branches of the split "
+ "merged together.";
public static final String OUTPUTS_DOC =
"A pseudo-struct containing all the predeclared output files, represented by "
+ "File objects. See the "
+ "Rules page for more information and examples."
+ "
This field does not exist on aspect contexts, since aspects do not have "
+ "predeclared outputs."
+ "
The fields of this object are defined as follows. It is an error if two outputs "
+ "produce the same field name or have the same label."
+ "
"
+ "
If the rule declares an outputs"
+ " dict, then for every entry in the dict, there is a field whose name is the key "
+ "and whose value is the corresponding File."
+ "
For every attribute of type attr.output"
+ " that the rule declares, there is a field whose name is the attribute's name. "
+ "If the target specified a label for that attribute, then the field value is the "
+ "corresponding File; otherwise the field value is None."
+ "
For every attribute of type attr.output_list"
+ " that the rule declares, there is a field whose name is the attribute's "
+ "name. The field value is a list of File objects corresponding to the "
+ "labels given for that attribute in the target, or an empty list if the attribute was "
+ "not specified in the target."
+ "
(Deprecated) If the rule is marked "
+ "executable or test,"
+ "there is a field named \"executable\", which is the default executable. "
+ "It is recommended that instead of using this, you pass another file (either "
+ "predeclared or not) to the executable arg of "
+ "DefaultInfo."
+ "
";
@SkylarkCallable(
name = "default_provider",
structField = true,
doc = "Deprecated. Use DefaultInfo instead."
)
public ProviderApi getDefaultProvider();
@SkylarkCallable(
name = "actions",
structField = true,
doc = "Functions to declare files and create actions."
)
public SkylarkActionFactoryApi actions();
@SkylarkCallable(
name = "created_actions",
doc = "For rules with _skylark_testable"
+ " set to True, this returns an "
+ "Actions provider representing all actions "
+ "created so far for the current rule. For all other rules, returns None. "
+ "Note that the provider is not updated when subsequent actions are created, so you "
+ "will have to call this function again if you wish to inspect them. "
+ "
"
+ "This is intended to help write tests for rule-implementation helper functions, which "
+ "may take in a ctx object and create actions on it.")
public SkylarkValue createdActions() throws EvalException;
@SkylarkCallable(name = "attr", structField = true, doc = ATTR_DOC)
public StructApi getAttr() throws EvalException;
@SkylarkCallable(name = "split_attr", structField = true, doc = SPLIT_ATTR_DOC)
public StructApi getSplitAttr() throws EvalException;
@SkylarkCallable(name = "executable", structField = true, doc = EXECUTABLE_DOC)
public StructApi getExecutable() throws EvalException;
@SkylarkCallable(name = "file", structField = true, doc = FILE_DOC)
public StructApi getFile() throws EvalException;
@SkylarkCallable(name = "files", structField = true, doc = FILES_DOC)
public StructApi getFiles() throws EvalException;
@SkylarkCallable(
name = "workspace_name",
structField = true,
doc = "Returns the workspace name as defined in the WORKSPACE file."
)
public String getWorkspaceName() throws EvalException;
@SkylarkCallable(name = "label", structField = true, doc = "The label of this rule.")
public Label getLabel() throws EvalException;
@SkylarkCallable(
name = "fragments",
structField = true,
doc = "Allows access to configuration fragments in target configuration."
)
public FragmentCollectionApi getFragments() throws EvalException;
@SkylarkCallable(
name = "host_fragments",
structField = true,
doc = "Allows access to configuration fragments in host configuration."
)
public FragmentCollectionApi getHostFragments() throws EvalException;
@SkylarkCallable(
name = "configuration",
structField = true,
doc =
"Returns the default configuration. See the "
+ "configuration type for more details."
)
public BuildConfigurationApi getConfiguration() throws EvalException;
@SkylarkCallable(
name = "host_configuration",
structField = true,
doc =
"Returns the host configuration. See the "
+ "configuration type for more details."
)
public BuildConfigurationApi getHostConfiguration() throws EvalException;
@SkylarkCallable(
name = "coverage_instrumented",
doc = "Returns whether code coverage instrumentation should be generated when performing "
+ "compilation actions for this rule or, if target is provided, the rule "
+ "specified by that Target. (If a non-rule or a Skylark rule Target is provided, this "
+ "returns False.) Checks if the sources of the current rule (if no Target is provided) or"
+ "the sources of Target should be instrumented based on the --instrumentation_filter and"
+ "--instrument_test_targets config settings. "
+ "This differs from coverage_enabled in the "
+ "configuration, which notes whether coverage data collection is enabled for the "
+ "entire run, but not whether a specific target should be instrumented.",
parameters = {
@Param(
name = "target",
type = TransitiveInfoCollectionApi.class,
defaultValue = "None",
noneable = true,
named = true,
doc = "A Target specifying a rule. If not provided, defaults to the current rule.")
}
)
public boolean instrumentCoverage(Object targetUnchecked) throws EvalException;
@SkylarkCallable(
name = "features",
structField = true,
doc = "Returns the set of features that are enabled for this rule."
)
public ImmutableList getFeatures() throws EvalException;
@SkylarkCallable(
name = "bin_dir",
structField = true,
doc = "The root corresponding to bin directory."
)
public FileRootApi getBinDirectory() throws EvalException;
@SkylarkCallable(
name = "genfiles_dir",
structField = true,
doc = "The root corresponding to genfiles directory."
)
public FileRootApi getGenfilesDirectory() throws EvalException;
@SkylarkCallable(structField = true, doc = OUTPUTS_DOC)
public ClassObject outputs() throws EvalException;
@SkylarkCallable(
structField = true,
doc =
"Returns rule attributes descriptor for the rule that aspect is applied to."
+ " Only available in aspect implementation functions."
)
public SkylarkAttributesCollectionApi rule() throws EvalException;
@SkylarkCallable(
structField = true,
name = "aspect_ids",
doc =
"Returns a list ids for all aspects applied to the target."
+ " Only available in aspect implementation functions."
)
public ImmutableList aspectIds() throws EvalException;
@SkylarkCallable(
structField = true,
doc = "Dictionary (String to String) of configuration variables."
)
public SkylarkDict var() throws EvalException;
@SkylarkCallable(structField = true, doc = "Toolchains required for this rule.")
public SkylarkIndexable toolchains() throws EvalException;
@SkylarkCallable(doc = "Splits a shell command to a list of tokens.", documented = false)
public SkylarkList tokenize(String optionString) throws FuncallException, EvalException;
@SkylarkCallable(
doc =
"Expands all references to labels embedded within a string for all files using a mapping "
+ "from definition labels (i.e. the label in the output type attribute) to files. "
+ "Deprecated.",
documented = false
)
public String expand(
@Nullable String expression, SkylarkList