Added separated suggestions for BUILD and BZL files.
E.g. "native" package contains rules and functions that are available at top level in BUILD files and as methods in BZL.
BZL: native.go_binary(..)
BUILD: go_binary(..)
RELNOTES: None
PiperOrigin-RevId: 211835409
diff --git a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
index aeed62b..46a4695 100644
--- a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
+++ b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.docgen;
import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.docgen.builtin.BuiltinProtos.ApiContext;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Builtins;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Callable;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Param;
@@ -47,48 +48,88 @@
throws BuildEncyclopediaDocException {
for (Entry<String, SkylarkModuleDoc> modEntry : types.entrySet()) {
- SkylarkModuleDoc mod = modEntry.getValue();
+ SkylarkModuleDoc mod = modEntry.getValue();
- Type.Builder type = Type.newBuilder();
- type.setName(mod.getName());
- type.setDoc(mod.getDocumentation());
- for (SkylarkMethodDoc meth : mod.getJavaMethods()) {
+ Type.Builder type = Type.newBuilder();
+ type.setName(mod.getName());
+ type.setDoc(mod.getDocumentation());
+ for (SkylarkMethodDoc meth : mod.getJavaMethods()) {
// Constructors are exported as global symbols.
if (!(meth instanceof SkylarkConstructorMethodDoc)) {
- type.addField(collectMethodInfo(meth));
+ Value.Builder value = collectMethodInfo(meth);
+ // Methods from the native package are available as top level functions in BUILD files.
+ if (mod.getName().equals("native")) {
+ value.setApiContext(ApiContext.BUILD);
+ builtins.addGlobal(value);
+
+ value.setApiContext(ApiContext.BZL);
+ type.addField(value);
+ } else {
+ value.setApiContext(ApiContext.ALL);
+ type.addField(value);
}
}
- // Add native rules to the native type.
- if (mod.getName().equals("native")) {
+ }
+ // Native rules are available in BZL file as methods of the native package.
+ if (mod.getName().equals("native")) {
for (RuleDocumentation rule : nativeRules) {
- type.addField(collectRuleInfo(rule));
- }
+ Value.Builder field = collectRuleInfo(rule);
+ field.setApiContext(ApiContext.BZL);
+ type.addField(field);
}
- builtins.addType(type);
+ }
+ builtins.addType(type);
}
}
- private static void appendGlobals(Builtins.Builder builtins, Map<String, Object> globals) {
- for (Entry<String, Object> entry : globals.entrySet()) {
+ // Globals are available for both BUILD and BZL files.
+ private static void appendGlobals(Builtins.Builder builtins, Map<String, Object> globalMethods) {
+ for (Entry<String, Object> entry : globalMethods.entrySet()) {
Object obj = entry.getValue();
+ Value.Builder value = Value.newBuilder();
+ if (obj instanceof BaseFunction) {
+ value = collectFunctionInfo((BaseFunction) obj);
+ } else {
+ value.setName(entry.getKey());
+ }
+ value.setApiContext(ApiContext.ALL);
+ builtins.addGlobal(value);
+ }
+ }
+
+ private static void appendBzlGlobals(
+ Builtins.Builder builtins, Map<String, Object> starlarkGlobals) {
+ for (Entry<String, Object> entry : starlarkGlobals.entrySet()) {
+ Object obj = entry.getValue();
+ Value.Builder value = Value.newBuilder();
if (obj instanceof BaseFunction) {
- builtins.addGlobal(collectFunctionInfo((BaseFunction) obj));
+ value = collectFunctionInfo((BaseFunction) obj);
} else {
- Value.Builder value = Value.newBuilder();
- value.setName(entry.getKey());
-
SkylarkModule typeModule = SkylarkInterfaceUtils.getSkylarkModule(obj.getClass());
if (typeModule != null) {
if (FuncallExpression.hasSelfCallMethod(obj.getClass())) {
- builtins.addGlobal(collectFunctionInfo(FuncallExpression.getSelfCallMethod(obj)));
- continue;
+ value = collectFunctionInfo(FuncallExpression.getSelfCallMethod(obj));
+ } else {
+ value.setName(entry.getKey());
+ value.setType(entry.getKey());
+ value.setDoc(typeModule.doc());
}
- value.setType(entry.getKey());
- value.setDoc(typeModule.doc());
}
- builtins.addGlobal(value);
}
+ value.setApiContext(ApiContext.BZL);
+ builtins.addGlobal(value);
+ }
+ }
+
+ // Native rules are available as top level functions in BUILD files.
+ private static void appendNativeRules(
+ Builtins.Builder builtins, List<RuleDocumentation> nativeRules)
+ throws BuildEncyclopediaDocException {
+ for (RuleDocumentation rule : nativeRules) {
+ Value.Builder global = collectRuleInfo(rule);
+ global.setApiContext(ApiContext.BUILD);
+ builtins.addGlobal(global);
}
}
@@ -191,7 +232,9 @@
Builtins.Builder builtins = Builtins.newBuilder();
appendTypes(builtins, symbols.getTypes(), symbols.getNativeRules());
- appendGlobals(builtins, symbols.getGlobalSymbols());
+ appendGlobals(builtins, symbols.getGlobals());
+ appendBzlGlobals(builtins, symbols.getBzlGlobals());
+ appendNativeRules(builtins, symbols.getNativeRules());
writeBuiltins(options.outputFile, builtins);
} catch (Throwable e) {
@@ -200,4 +243,3 @@
}
}
}
-
diff --git a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
index 3c08a42..d51e058 100644
--- a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
+++ b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
@@ -66,9 +66,12 @@
*/
public class SymbolFamilies {
private final ImmutableList<RuleDocumentation> nativeRules;
- private final ImmutableMap<String, Object> globalSymbols;
private final ImmutableMap<String, SkylarkModuleDoc> types;
+ // Mappings between Starlark names and Starlark entities generated from the fakebuildapi.
+ private final ImmutableMap<String, Object> globals;
+ private final ImmutableMap<String, Object> bzlGlobals;
+
public SymbolFamilies(
String productName, String provider, List<String> inputDirs, String blackList)
throws NoSuchMethodException, ClassPathException, InvocationTargetException,
@@ -76,7 +79,8 @@
IOException {
this.nativeRules =
ImmutableList.copyOf(collectNativeRules(productName, provider, inputDirs, blackList));
- this.globalSymbols = ImmutableMap.copyOf(collectGlobalSymbols());
+ this.globals = ImmutableMap.copyOf(collectGlobals());
+ this.bzlGlobals = ImmutableMap.copyOf(collectBzlGlobals());
this.types = ImmutableMap.copyOf(collectTypes());
}
@@ -88,11 +92,19 @@
}
/*
- * Returns a mapping between Starlark module names and Starkark entities generated from the
- * fakebuildapi.
+ * Returns a mapping between Starlark names and Starkark entities that are available both in BZL
+ * and BUILD files.
*/
- public Map<String, Object> getGlobalSymbols() {
- return globalSymbols;
+ public Map<String, Object> getGlobals() {
+ return globals;
+ }
+
+ /*
+ * Returns a mapping between Starlark names and Starkark entities that are available only in BZL
+ * files.
+ */
+ public Map<String, Object> getBzlGlobals() {
+ return bzlGlobals;
}
// Returns a mapping between type names and module/type documentation.
@@ -100,10 +112,18 @@
return types;
}
+ /*
+ * Collects a mapping between type names and module/type documentation that are available both
+ * in BZL and BUILD files.
+ */
private Map<String, SkylarkModuleDoc> collectTypes() throws ClassPathException {
return SkylarkDocumentationCollector.collectModules();
}
+ /*
+ * Collects a list of native rules that are available in BUILD files as top level functions
+ * and in BZL files as methods of the native package.
+ */
private List<RuleDocumentation> collectNativeRules(
String productName, String provider, List<String> inputDirs, String blackList)
throws NoSuchMethodException, InvocationTargetException, IllegalAccessException,
@@ -114,7 +134,21 @@
return processor.getNativeRules();
}
- private Map<String, Object> collectGlobalSymbols() {
+ /*
+ * Collects a mapping between names and Starlark entities that are available both in BZL and
+ * BUILD files.
+ */
+ private Map<String, Object> collectGlobals() {
+ ImmutableMap.Builder<String, Object> envBuilder = ImmutableMap.builder();
+ MethodLibrary.addBindingsToBuilder(envBuilder);
+ Runtime.addConstantsToBuilder(envBuilder);
+ return envBuilder.build();
+ }
+
+ /*
+ * Collects a mapping between names and Starlark entities that are available only in BZL files
+ */
+ private Map<String, Object> collectBzlGlobals() {
ImmutableMap.Builder<String, Object> envBuilder = ImmutableMap.builder();
TopLevelBootstrap topLevelBootstrap =
new TopLevelBootstrap(
@@ -145,8 +179,6 @@
RepositoryBootstrap repositoryBootstrap = new RepositoryBootstrap(new FakeRepositoryModule());
TestingBootstrap testingBootstrap = new TestingBootstrap(new FakeTestingModule());
- Runtime.addConstantsToBuilder(envBuilder);
- MethodLibrary.addBindingsToBuilder(envBuilder);
topLevelBootstrap.addBindingsToBuilder(envBuilder);
androidBootstrap.addBindingsToBuilder(envBuilder);
appleBootstrap.addBindingsToBuilder(envBuilder);
diff --git a/src/main/protobuf/builtin.proto b/src/main/protobuf/builtin.proto
index 72df5a1..9ca7f54 100644
--- a/src/main/protobuf/builtin.proto
+++ b/src/main/protobuf/builtin.proto
@@ -50,6 +50,15 @@
string doc = 3;
}
+// ApiContext specifies the context(s) in which a symbol is available. For
+// example, a symbol may be available as a builtin only in .bzl files, but
+// not in BUILD files.
+enum ApiContext {
+ ALL = 0;
+ BZL = 1;
+ BUILD = 2;
+}
+
// Generic representation for a Skylark object. If the object is callable
// (can act as a function), then callable will be set.
message Value {
@@ -63,6 +72,9 @@
// Value documentation.
string doc = 4;
+
+ // The context(s) in which the symbol is recognized.
+ ApiContext api_context = 5;
}
message Callable {
