Create new config module that is responsible for creating BuildSetting descriptor objects.

Build settings are units of configuration i.e. a key/value pair of a setting (e.g. cpu) and a value (e.g. ppc). A build setting descriptor is used to describe what kind of build setting a skylark rule is (if any at all). The BuildSettingDescriptor implementation of the API describes two facets of the build setting rule: the type of the value and whether or not the setting is settable on the command line.

The methods exposed here will eventually be hooked up to a new parameter in the <code> rule() </code> function. Validation for these restrictions will also happen in a later CL attached to the same bug.

PiperOrigin-RevId: 208669663

8 files changed, 333 insertions, 3 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkConfig.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkConfig.java
new file mode 100644
index 0000000000..a75cd5c829
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkConfig.java
@@ -0,0 +1,89 @@
+// 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.analysis.skylark;
+
+import static com.google.devtools.build.lib.packages.BuildType.LABEL;
+import static com.google.devtools.build.lib.packages.BuildType.LABEL_LIST;
+import static com.google.devtools.build.lib.syntax.Type.BOOLEAN;
+import static com.google.devtools.build.lib.syntax.Type.INTEGER;
+import static com.google.devtools.build.lib.syntax.Type.STRING;
+import static com.google.devtools.build.lib.syntax.Type.STRING_LIST;
+
+import com.google.devtools.build.lib.skylarkbuildapi.SkylarkConfigApi;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter;
+import com.google.devtools.build.lib.syntax.Type;
+
+/**
+ * Skylark namespace for creating build setting descriptors.
+ */
+public class SkylarkConfig implements SkylarkConfigApi {
+
+  @Override
+  public BuildSettingDescriptor intSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, INTEGER);
+  }
+
+  @Override
+  public BuildSettingDescriptor boolSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, BOOLEAN);
+  }
+
+  @Override
+  public BuildSettingDescriptor stringSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, STRING);
+  }
+
+  @Override
+  public BuildSettingDescriptor stringListSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, STRING_LIST);
+  }
+
+  @Override
+  public BuildSettingDescriptor labelSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, LABEL);
+  }
+
+  @Override
+  public BuildSettingDescriptor labelListSetting(Boolean flag) {
+    return new BuildSettingDescriptor(flag, LABEL_LIST);
+  }
+
+  @Override
+  public void repr(SkylarkPrinter printer) {
+    printer.append("<config>");
+  }
+
+  /**
+   * An object that describes what time of build setting a skylark rule is (if any type).
+   */
+  public static final class BuildSettingDescriptor implements SkylarkConfigApi.BuildSettingApi {
+    private boolean isFlag;
+    private Type<?> type;
+
+    BuildSettingDescriptor(boolean isFlag, Type<?> type) {
+      this.isFlag = isFlag;
+      this.type = type;
+    }
+
+    public Type<?> getType() {
+      return type;
+    }
+
+    @Override
+    public void repr(SkylarkPrinter printer) {
+      printer.append("<build_setting." + type.toString() + ">");
+    }
+  }
+}
diff --git a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRules.java b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRules.java
index 09622578e1..1281325a17 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRules.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRules.java
@@ -17,6 +17,7 @@ import com.google.common.collect.ImmutableList;
 import com.google.devtools.build.lib.analysis.BaseRuleClasses;
 import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider;
 import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider.RuleSet;
+import com.google.devtools.build.lib.analysis.skylark.SkylarkConfig;
 import com.google.devtools.build.lib.rules.core.CoreRules;
 import com.google.devtools.build.lib.rules.platform.PlatformRules;
 import com.google.devtools.build.lib.skylarkbuildapi.config.ConfigBootstrap;
@@ -41,7 +42,8 @@ public final class ConfigRules implements RuleSet {
         new ConfigFeatureFlagConfiguration.Loader());
 
     builder.addRuleDefinition(new ConfigRuleClasses.ConfigFeatureFlagRule());
-    builder.addSkylarkBootstrap(new ConfigBootstrap(new ConfigSkylarkCommon()));
+    builder.addSkylarkBootstrap(
+        new ConfigBootstrap(new ConfigSkylarkCommon(), new SkylarkConfig()));
   }
 
   @Override
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkConfigApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkConfigApi.java
new file mode 100644
index 0000000000..e6cf44b3ad
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkConfigApi.java
@@ -0,0 +1,146 @@
+// 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.devtools.build.lib.skylarkinterface.Param;
+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;
+
+
+/**
+ *  The "config" module of the Build API.
+ *
+ *  This exposes methods to describe what kind of build setting (if any) a skylark rule is using
+ *  the {@code build_setting} attr of the {@code rule(...)} function.
+ */
+@SkylarkModule(
+    name = "config",
+    namespace = true,
+    category = SkylarkModuleCategory.BUILTIN,
+    doc = "This is a top-level module for creating build setting descriptors which describe what "
+        + "kind of build setting (if any) a skylark rule is. "
+        + ""
+        + "<p>ex: the following rule is marked as a build setting by setting the "
+        + "<code>build_setting</code> parameter of the <code>rule()</code> function. Specifically "
+        + "it is a build setting of type <code>int</code> and is a <code>flag</code> which means "
+        + "this build setting is callable on the command line.<br><pre class=language-python>"
+        + "  my_rule = rule(\n"
+        + "    implementation = _impl,\n"
+        + "    build_setting = config.int(flag = True),\n"
+        + "    ...\n"
+        + "  )</pre>")
+//TODO(juliexxia): Create formal documentation for skylark build configuration efforts (b/112545834)
+public interface SkylarkConfigApi extends SkylarkValue {
+
+  static final String FLAG_ARG = "flag";
+  static final String FLAG_ARG_DOC =
+      "Whether or not this build setting is callable on the command line.";
+
+  @SkylarkCallable(
+      name = "int",
+      doc = "An integer-typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi intSetting(Boolean flag);
+
+  @SkylarkCallable(
+      name = "bool",
+      doc = "A bool-typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi boolSetting(Boolean flag);
+
+  @SkylarkCallable(
+      name = "string",
+      doc = "A string-typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi stringSetting(Boolean flag);
+
+  @SkylarkCallable(
+      name = "string_list",
+      doc = "A string list-typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi stringListSetting(Boolean flag);
+
+  @SkylarkCallable(
+      name = "label",
+      doc = "A label typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi labelSetting(Boolean flag);
+
+  @SkylarkCallable(
+      name = "label_list",
+      doc = "A label list-typed build setting",
+      parameters = {
+        @Param(
+            name = FLAG_ARG,
+            type = Boolean.class,
+            defaultValue = "False",
+            doc = FLAG_ARG_DOC,
+            named = true,
+            positional = false)
+      })
+  BuildSettingApi labelListSetting(Boolean flag);
+
+  /** The API for build setting descriptors. */
+  @SkylarkModule(
+      name = "BuildSetting",
+      category = SkylarkModuleCategory.NONE,
+      doc =
+          "The descriptor for a single piece of configuration information. If configuration is a "
+              + "key-value map of settings like {'cpu': 'ppc', 'copt': '-DFoo'}, this describes a "
+              + "single entry in that map.")
+  interface BuildSettingApi extends SkylarkValue {}
+}
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigBootstrap.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigBootstrap.java
index 0624ebf0a9..80379a31d3 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigBootstrap.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigBootstrap.java
@@ -16,6 +16,7 @@ package com.google.devtools.build.lib.skylarkbuildapi.config;
 
 import com.google.common.collect.ImmutableMap.Builder;
 import com.google.devtools.build.lib.skylarkbuildapi.Bootstrap;
+import com.google.devtools.build.lib.skylarkbuildapi.SkylarkConfigApi;
 
 /**
  * A {@link Bootstrap} for config-related libraries of the build API.
@@ -23,13 +24,17 @@ import com.google.devtools.build.lib.skylarkbuildapi.Bootstrap;
 public class ConfigBootstrap implements Bootstrap {
 
   private final ConfigSkylarkCommonApi configSkylarkCommonApi;
+  private final SkylarkConfigApi skylarkConfigApi;
 
-  public ConfigBootstrap(ConfigSkylarkCommonApi configSkylarkCommonApi) {
+  public ConfigBootstrap(
+      ConfigSkylarkCommonApi configSkylarkCommonApi, SkylarkConfigApi skylarkConfigApi) {
     this.configSkylarkCommonApi = configSkylarkCommonApi;
+    this.skylarkConfigApi = skylarkConfigApi;
   }
 
   @Override
   public void addBindingsToBuilder(Builder<String, Object> builder) {
     builder.put("config_common", configSkylarkCommonApi);
+    builder.put("config", skylarkConfigApi);
   }
 }
diff --git a/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java b/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
index 2a0bf3d475..8e43d1074c 100644
--- a/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
+++ b/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
@@ -42,6 +42,7 @@ import com.google.devtools.build.lib.syntax.Runtime;
 import com.google.devtools.build.lib.syntax.SkylarkImport;
 import com.google.devtools.build.skydoc.fakebuildapi.FakeActionsInfoProvider;
 import com.google.devtools.build.skydoc.fakebuildapi.FakeBuildApiGlobals;
+import com.google.devtools.build.skydoc.fakebuildapi.FakeConfigApi;
 import com.google.devtools.build.skydoc.fakebuildapi.FakeDefaultInfoProvider;
 import com.google.devtools.build.skydoc.fakebuildapi.FakeOutputGroupInfo.FakeOutputGroupInfoProvider;
 import com.google.devtools.build.skydoc.fakebuildapi.FakeSkylarkAttrApi;
@@ -310,7 +311,8 @@ public class SkydocMain {
         new FakeAndroidResourcesInfoProvider(),
         new FakeAndroidNativeLibsInfoProvider());
     AppleBootstrap appleBootstrap = new AppleBootstrap(new FakeAppleCommon());
-    ConfigBootstrap configBootstrap = new ConfigBootstrap(new FakeConfigSkylarkCommon());
+    ConfigBootstrap configBootstrap =
+        new ConfigBootstrap(new FakeConfigSkylarkCommon(), new FakeConfigApi());
     CcBootstrap ccBootstrap = new CcBootstrap(new FakeCcModule());
     JavaBootstrap javaBootstrap = new JavaBootstrap(new FakeJavaCommon(),
         new FakeJavaInfoProvider(),
diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeBuildSettingDescriptor.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeBuildSettingDescriptor.java
new file mode 100644
index 0000000000..facde6c9be
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeBuildSettingDescriptor.java
@@ -0,0 +1,26 @@
+// 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.skydoc.fakebuildapi;
+
+import com.google.devtools.build.lib.skylarkbuildapi.SkylarkConfigApi.BuildSettingApi;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter;
+
+/**
+ * Fake implementation of {@link BuildSettingApi};
+ */
+public class FakeBuildSettingDescriptor implements BuildSettingApi {
+  @Override
+  public void repr(SkylarkPrinter printer) {}
+}
diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeConfigApi.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeConfigApi.java
new file mode 100644
index 0000000000..2bd322b9f7
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeConfigApi.java
@@ -0,0 +1,57 @@
+// 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.skydoc.fakebuildapi;
+
+import com.google.devtools.build.lib.skylarkbuildapi.SkylarkConfigApi;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter;
+
+/**
+ * Fake implementation of {@link SkylarkConfigApi}.
+ */
+public class FakeConfigApi implements SkylarkConfigApi {
+
+  @Override
+  public BuildSettingApi intSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public BuildSettingApi boolSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public BuildSettingApi stringSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public BuildSettingApi stringListSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public BuildSettingApi labelSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public BuildSettingApi labelListSetting(Boolean flag) {
+    return new FakeBuildSettingDescriptor();
+  }
+
+  @Override
+  public void repr(SkylarkPrinter printer) {}
+}
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
index 10ef29d783..b2be410f3f 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
@@ -6,6 +6,9 @@ def exercise_the_api():
     var2 = platform_common.TemplateVariableInfo
     var3 = repository_rule(implementation = my_rule_impl)
     var4 = testing.ExecutionInfo({})
+    # TODO(juliexxia): This isn't actually where this module would be used.
+    # Move this to the rule definition when the relevant parameter is set up.
+    var5 = config.int(flag = True)
 
 exercise_the_api()