Initial implementation of a Skylark debug server API.

I've pulled out the API for separate review. It includes all
hooks from blaze/skylark used by the debugger.

Debuggable thread contexts are currently declared in 3 places:
- BuildFileAST (top-level evaluation of BUILD files)
- SkylarkRuleConfiguredTargetUtil (rules)
- SkylarkAspectFactory (aspects)

The purpose of declaring these contexts is so that the debugger
can track currently-active threads (and stop tracking them when
the task is completed).

Details of the actual debugging server are in unknown commit.

PiperOrigin-RevId: 197770547

3 files changed, 117 insertions, 0 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/BUILD b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/BUILD
new file mode 100644
index 0000000000..00fae167a0
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/BUILD
@@ -0,0 +1,25 @@
+package(default_visibility = ["//src:__subpackages__"])
+
+filegroup(
+    name = "srcs",
+    srcs = glob(["**"]),
+    visibility = ["//src/main/java/com/google/devtools/build/lib:__pkg__"],
+)
+
+java_library(
+    name = "module",
+    srcs = ["SkylarkDebuggerModule.java"],
+    deps = [
+        ":options",
+        "//src/main/java/com/google/devtools/build/lib:events",
+        "//src/main/java/com/google/devtools/build/lib:runtime",
+    ],
+)
+
+java_library(
+    name = "options",
+    srcs = ["SkylarkDebuggerOptions.java"],
+    deps = [
+        "//src/main/java/com/google/devtools/common/options",
+    ],
+)
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerModule.java b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerModule.java
new file mode 100644
index 0000000000..167d3c853b
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerModule.java
@@ -0,0 +1,47 @@
+// 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.skylarkdebug.module;
+
+import com.google.devtools.build.lib.events.Reporter;
+import com.google.devtools.build.lib.runtime.BlazeModule;
+import com.google.devtools.build.lib.runtime.CommandEnvironment;
+
+/** Blaze module for setting up Skylark debugging. */
+public final class SkylarkDebuggerModule extends BlazeModule {
+  @Override
+  public void beforeCommand(CommandEnvironment env) {
+    // Conditionally enable debugging
+    SkylarkDebuggerOptions buildOptions = env.getOptions().getOptions(SkylarkDebuggerOptions.class);
+    boolean enabled = buildOptions != null && buildOptions.debugSkylark;
+    if (enabled) {
+      initializeDebugging(env.getReporter(), buildOptions.debugServerPort);
+    } else {
+      disableDebugging();
+    }
+  }
+
+  @Override
+  public void afterCommand() {
+    disableDebugging();
+  }
+
+  private static void initializeDebugging(Reporter reporter, int debugPort) {
+    // TODO(brendandouglas): implement a debug server
+  }
+
+  private static void disableDebugging() {
+    // TODO(brendandouglas): implement a debug server
+  }
+}
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerOptions.java b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerOptions.java
new file mode 100644
index 0000000000..831a7770c6
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkdebug/module/SkylarkDebuggerOptions.java
@@ -0,0 +1,45 @@
+// 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.skylarkdebug.module;
+
+import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
+import com.google.devtools.common.options.OptionEffectTag;
+import com.google.devtools.common.options.OptionMetadataTag;
+import com.google.devtools.common.options.OptionsBase;
+
+/** Configuration options for Skylark debugging. */
+public final class SkylarkDebuggerOptions extends OptionsBase {
+  @Option(
+      name = "experimental_skylark_debug",
+      defaultValue = "false",
+      documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
+      effectTags = {OptionEffectTag.EXECUTION},
+      metadataTags = {OptionMetadataTag.EXPERIMENTAL},
+      help =
+          "If true, Blaze will open the Skylark debug server at the start of the build "
+              + "invocation, and wait for a debugger to attach before running the build.")
+  public boolean debugSkylark;
+
+  @Option(
+      name = "experimental_debug_server_port",
+      defaultValue = "7300",
+      category = "server startup",
+      documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
+      effectTags = {OptionEffectTag.EXECUTION},
+      metadataTags = {OptionMetadataTag.EXPERIMENTAL},
+      help = "The port on which the Skylark debug server will listen for connections.")
+  public int debugServerPort;
+}