Rename native.rule and native.rules to {existing_rule,existing_rules}
This is to avoid confusion between rule(), which declares a new build
rules, and native.rule(), which can only be used in macros to inspect
the BUILD file processed so far.
native.{rule,rules} is maintained and marked deprecated to smooth the
transition for early adopters.
--
MOS_MIGRATED_REVID=113250194
diff --git a/site/docs/skylark/cookbook.md b/site/docs/skylark/cookbook.md
index 60f441f..bf96adc 100644
--- a/site/docs/skylark/cookbook.md
+++ b/site/docs/skylark/cookbook.md
@@ -66,11 +66,11 @@
## <a name="conditional-instantiation"></a>Conditional instantiation.
Macros can look at previously instantiated rules. This is done with
-`native.rule`, which returns information on a single rule defined in the same
+`native.existing_rule`, which returns information on a single rule defined in the same
`BUILD` file, eg.,
```python
-native.rule("descriptor_proto")
+native.existing_rule("descriptor_proto")
```
This is useful to avoid instantiating the same rule twice, which is an
@@ -82,7 +82,7 @@
```python
def system_test(test_file, flavor):
n = "system_test_%s_%s_test" % (test_file, flavor)
- if native.rule(n) == None:
+ if native.existing_rule(n) == None:
native.py_test(
name = n,
srcs = [ "test_driver.py", test_file ],
@@ -115,22 +115,22 @@
Macros can collect information from the BUILD file as processed so far. We call
this aggregation. The typical example is collecting data from all rules of a
-certain kind. This is done by calling `native.rules`, which returns a
+certain kind. This is done by calling `native.existing_rules`, which returns a
dictionary representing all rules defined so far in the current BUILD file. The
dictionary has entries of the form `name` => `rule`, with the values using the
-same format as `native.rule`.
+same format as `native.existing_rule`.
```python
def archive_cc_src_files(tag):
"""Create an archive of all C++ sources that have the given tag."""
all_src = []
- for r in native.rules().values():
+ for r in native.existing_rules().values():
if tag in r["tags"] and r["kind"] == "cc_library":
all_src.append(r["srcs"])
native.genrule(cmd = "zip $@ $^", srcs = all_src, outs = ["out.zip"])
```
-Since `native.rules` constructs a potentially large dictionary, you should avoid
+Since `native.existing_rules` constructs a potentially large dictionary, you should avoid
calling it repeatedly within BUILD file.
## <a name="empty"></a>Empty rule
diff --git a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
index ad73b16..dd80289 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
@@ -95,13 +95,12 @@
}
};
+ @Deprecated
@SkylarkSignature(
name = "rule",
objectType = SkylarkNativeModule.class,
returnType = Object.class,
- doc =
- "Returns a dictionary representing the attributes of a previously defined rule, "
- + "or None if the rule does not exist.",
+ doc = "Deprecated. Use existing_rule instead.",
mandatoryPositionals = {
@Param(name = "name", type = String.class, doc = "The name of the rule.")
},
@@ -122,12 +121,58 @@
}
};
+ @SkylarkSignature(
+ name = "existing_rule",
+ objectType = SkylarkNativeModule.class,
+ returnType = Object.class,
+ doc =
+ "Returns a dictionary representing the attributes of a previously defined rule, "
+ + "or None if the rule does not exist.",
+ mandatoryPositionals = {
+ @Param(name = "name", type = String.class, doc = "The name of the rule.")
+ },
+ useAst = true,
+ useEnvironment = true
+ )
+ private static final BuiltinFunction existingRule =
+ new BuiltinFunction("existing_rule") {
+ public Object invoke(String name, FuncallExpression ast, Environment env)
+ throws EvalException, InterruptedException {
+ env.checkLoadingPhase("native.existing_rule", ast.getLocation());
+ Map<String, Object> rule = PackageFactory.callGetRuleFunction(name, ast, env);
+ if (rule != null) {
+ return rule;
+ }
+
+ return Runtime.NONE;
+ }
+ };
+
+ @Deprecated
+ @SkylarkSignature(
+ name = "rules",
+ objectType = SkylarkNativeModule.class,
+ returnType = Map.class,
+ doc = "Deprecated. Use existing_rules instead.",
+ mandatoryPositionals = {},
+ useAst = true,
+ useEnvironment = true
+ )
+ private static final BuiltinFunction getRules =
+ new BuiltinFunction("rules") {
+ public Map<?, ?> invoke(FuncallExpression ast, Environment env)
+ throws EvalException, InterruptedException {
+ env.checkLoadingPhase("native.rules", ast.getLocation());
+ return PackageFactory.callGetRulesFunction(ast, env);
+ }
+ };
+
/*
If necessary, we could allow filtering by tag (anytag, alltags), name (regexp?), kind ?
For now, we ignore this, since users can implement it in Skylark.
*/
@SkylarkSignature(
- name = "rules",
+ name = "existing_rules",
objectType = SkylarkNativeModule.class,
returnType = Map.class,
doc =
@@ -138,11 +183,11 @@
useAst = true,
useEnvironment = true
)
- private static final BuiltinFunction getRules =
- new BuiltinFunction("rules") {
- public Map invoke(FuncallExpression ast, Environment env)
+ private static final BuiltinFunction existingRules =
+ new BuiltinFunction("existing_rules") {
+ public Map<?, ?> invoke(FuncallExpression ast, Environment env)
throws EvalException, InterruptedException {
- env.checkLoadingPhase("native.rules", ast.getLocation());
+ env.checkLoadingPhase("native.existing_rules", ast.getLocation());
return PackageFactory.callGetRulesFunction(ast, env);
}
};
diff --git a/src/test/java/com/google/devtools/build/lib/skylark/SkylarkRuleContextTest.java b/src/test/java/com/google/devtools/build/lib/skylark/SkylarkRuleContextTest.java
index 240b587..2fb7db0 100644
--- a/src/test/java/com/google/devtools/build/lib/skylark/SkylarkRuleContextTest.java
+++ b/src/test/java/com/google/devtools/build/lib/skylark/SkylarkRuleContextTest.java
@@ -356,7 +356,8 @@
@Test
public void testGetRuleSelect() throws Exception {
scratch.file("test/skylark/BUILD");
- scratch.file("test/skylark/rulestr.bzl", "def rule_dict(name):", " return native.rule(name)");
+ scratch.file(
+ "test/skylark/rulestr.bzl", "def rule_dict(name):", " return native.existing_rule(name)");
scratch.file(
"test/getrule/BUILD",
@@ -376,9 +377,9 @@
scratch.file(
"test/skylark/rulestr.bzl",
"def rule_dict(name):",
- " return native.rule(name)",
+ " return native.existing_rule(name)",
"def rules_dict():",
- " return native.rules()",
+ " return native.existing_rules()",
"def nop(ctx):",
" pass",
"nop_rule = rule(attrs = {'x': attr.label()}, implementation = nop)",
