Added more details about the use of configuration fragments in Skylark to the documentation.

--
MOS_MIGRATED_REVID=101357875

4 files changed, 32 insertions, 18 deletions

diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index d21ddb1742..f450fd0ab9 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -219,6 +219,27 @@ in the attribute.
 `DATA_CFG` is present for legacy reasons and should be used for the `data`
 attributes.
 
+<a name="fragments"></a>
+Configuration Fragments
+--------------
+
+Rules may access configuration fragments such as `cpp`, `java` and `jvm`.
+However, all required fragments have to be declared in order to avoid access
+errors:
+
+```python
+def impl(ctx):
+    # Using ctx.fragments.cpp would lead to an error since it was not declared.
+    x = ctx.fragments.java
+    ...
+
+my_rule = rule(
+    implementation=impl,
+    fragments = ["java"],
+    ...
+)
+```
+
 Providers
 ---------
 
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java b/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java
index 655aff90fa..d649f47b51 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java
@@ -25,8 +25,9 @@ import javax.annotation.Nullable;
 /**
  * Represents a collection of configuration fragments in Skylark.
  */
+// Documentation can be found at ctx.fragments
 @Immutable
-@SkylarkModule(name = "fragments", doc = "Allows access to configuration fragments.")
+@SkylarkModule(name = "fragments", documented = false, doc = "")
 public class FragmentCollection implements ClassObject {
   private final RuleContext ruleContext;
 
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
index b0e94d918a..52e85086cd 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
@@ -17,7 +17,6 @@ package com.google.devtools.build.lib.bazel.rules;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Functions;
 import com.google.common.collect.ImmutableList;
-import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.lib.analysis.BaseRuleClasses;
 import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider;
 import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider.PrerequisiteValidator;
@@ -82,19 +81,16 @@ import com.google.devtools.build.lib.rules.android.AndroidRuleClasses;
 import com.google.devtools.build.lib.rules.cpp.CcToolchainRule;
 import com.google.devtools.build.lib.rules.cpp.CcToolchainSuiteRule;
 import com.google.devtools.build.lib.rules.cpp.CppBuildInfo;
-import com.google.devtools.build.lib.rules.cpp.CppConfiguration;
 import com.google.devtools.build.lib.rules.cpp.CppConfigurationLoader;
 import com.google.devtools.build.lib.rules.cpp.CppOptions;
 import com.google.devtools.build.lib.rules.genquery.GenQueryRule;
 import com.google.devtools.build.lib.rules.java.J2ObjcCommandLineOptions;
 import com.google.devtools.build.lib.rules.java.J2ObjcConfiguration;
-import com.google.devtools.build.lib.rules.java.JavaConfiguration;
 import com.google.devtools.build.lib.rules.java.JavaConfigurationLoader;
 import com.google.devtools.build.lib.rules.java.JavaCpuSupplier;
 import com.google.devtools.build.lib.rules.java.JavaImportBaseRule;
 import com.google.devtools.build.lib.rules.java.JavaOptions;
 import com.google.devtools.build.lib.rules.java.JavaToolchainRule;
-import com.google.devtools.build.lib.rules.java.Jvm;
 import com.google.devtools.build.lib.rules.java.JvmConfigurationLoader;
 import com.google.devtools.build.lib.rules.objc.ExperimentalIosTestRule;
 import com.google.devtools.build.lib.rules.objc.IosApplicationRule;
@@ -121,7 +117,6 @@ import com.google.devtools.build.lib.rules.python.PythonConfigurationLoader;
 import com.google.devtools.build.lib.rules.python.PythonOptions;
 import com.google.devtools.build.lib.rules.workspace.BindRule;
 import com.google.devtools.build.lib.syntax.Label;
-import com.google.devtools.build.lib.syntax.SkylarkType;
 import com.google.devtools.build.lib.util.ResourceFileLoader;
 
 import java.io.IOException;
@@ -211,23 +206,13 @@ public class BazelRuleClassProvider {
           AndroidConfiguration.Options.class
       );
 
-  /**
-   * Java objects accessible from Skylark rule implementations using this module.
-   */
-  private static final ImmutableMap<String, SkylarkType> skylarkBuiltinJavaObects =
-      ImmutableMap.of(
-          "jvm", SkylarkType.of(Jvm.class),
-          "java_configuration", SkylarkType.of(JavaConfiguration.class),
-          "cpp", SkylarkType.of(CppConfiguration.class));
-
   public static void setup(ConfiguredRuleClassProvider.Builder builder) {
     builder
         .addBuildInfoFactory(new BazelJavaBuildInfoFactory())
         .addBuildInfoFactory(new CppBuildInfo())
         .addBuildInfoFactory(new ObjcBuildInfoFactory())
         .setConfigurationCollectionFactory(new BazelConfigurationCollection())
-        .setPrerequisiteValidator(new BazelPrerequisiteValidator())
-        .setSkylarkAccessibleJavaClasses(skylarkBuiltinJavaObects);
+        .setPrerequisiteValidator(new BazelPrerequisiteValidator());
 
     for (Class<? extends FragmentOptions> fragmentOptions : BUILD_OPTIONS) {
       builder.addConfigurationOptions(fragmentOptions);
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
index 93ff5aa416..dbaf2c8f64 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
@@ -312,7 +312,14 @@ public final class SkylarkRuleContext {
   }
 
   @SkylarkCallable(
-      name = "fragments", structField = true, doc = "Allows access to configuration fragments.")
+    name = "fragments",
+    structField = true,
+    doc =
+        "Allows access to configuration fragments. Possible fields are <code>cpp</code>, "
+            + "<code>java</code> and <code>jvm</code>. "
+            + "However, rules have to declare their required fragments in order to access them "
+            + "(see <a href=\"../rules.html#fragments\">here</a>)."
+  )
   public FragmentCollection getFragments() {
     return fragments;
   }