From 51215bd922d57f2ddd03deac6295f3e9267c7c3c Mon Sep 17 00:00:00 2001 From: juliexxia Date: Tue, 14 Aug 2018 10:28:35 -0700 Subject: 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 rule() function. Validation for these restrictions will also happen in a later CL attached to the same bug. PiperOrigin-RevId: 208669663 --- .../build/lib/analysis/skylark/SkylarkConfig.java | 89 +++++++++++++ .../build/lib/rules/config/ConfigRules.java | 4 +- .../lib/skylarkbuildapi/SkylarkConfigApi.java | 146 +++++++++++++++++++++ .../skylarkbuildapi/config/ConfigBootstrap.java | 7 +- .../google/devtools/build/skydoc/SkydocMain.java | 4 +- .../fakebuildapi/FakeBuildSettingDescriptor.java | 26 ++++ .../build/skydoc/fakebuildapi/FakeConfigApi.java | 57 ++++++++ .../build/skydoc/testdata/misc_apis_test/input.bzl | 3 + 8 files changed, 333 insertions(+), 3 deletions(-) create mode 100644 src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkConfig.java create mode 100644 src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkConfigApi.java create mode 100644 src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeBuildSettingDescriptor.java create mode 100644 src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeConfigApi.java 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(""); + } + + /** + * 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(""); + } + } +} 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. " + + "" + + "

ex: the following rule is marked as a build setting by setting the " + + "build_setting parameter of the rule() function. Specifically " + + "it is a build setting of type int and is a flag which means " + + "this build setting is callable on the command line.

"
+        + "  my_rule = rule(\n"
+        + "    implementation = _impl,\n"
+        + "    build_setting = config.int(flag = True),\n"
+        + "    ...\n"
+        + "  )
") +//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 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() -- cgit v1.2.3