[lldb-dap] Implement command directives (llvm#74808)

This adds support for optionally prefixing any command with `?` and/or
`!`.
- `?` prevents the output of a commands to be printed to the console
unless it fails.
- `!` aborts the dap if the command fails.

They come in handy when programmatically running commands on behalf of
the user without wanting them to know unless they fail, or when a
critical setup is required as part of launchCommands and it's better to
abort on failures than to silently skip.

Author: walter-erquinigo

lldb/packages/Python/lldbsuite/test/tools/lldb-dap/lldbdap_testcase.py

@@ -291,6 +291,7 @@ def attach(
         postRunCommands=None,
         sourceMap=None,
         sourceInitFile=False,
+        expectFailure=False,
     ):
         """Build the default Makefile target, create the DAP debug adaptor,
         and attach to the process.
@@ -322,6 +323,8 @@ def cleanup():
             postRunCommands=postRunCommands,
             sourceMap=sourceMap,
         )
+        if expectFailure:
+            return response
         if not (response and response["success"]):
             self.assertTrue(
                 response["success"], "attach failed (%s)" % (response["message"])
@@ -437,6 +440,8 @@ def build_and_launch(
         commandEscapePrefix=None,
         customFrameFormat=None,
         customThreadFormat=None,
+        launchCommands=None,
+        expectFailure=False,
     ):
         """Build the default Makefile target, create the DAP debug adaptor,
         and launch the process.
@@ -470,4 +475,6 @@ def build_and_launch(
             commandEscapePrefix=commandEscapePrefix,
             customFrameFormat=customFrameFormat,
             customThreadFormat=customThreadFormat,
+            launchCommands=launchCommands,
+            expectFailure=expectFailure,
         )

lldb/test/API/tools/lldb-dap/commands/Makefile

@@ -0,0 +1,3 @@
+CXX_SOURCES := main.cpp
+
+include Makefile.rules

lldb/test/API/tools/lldb-dap/commands/TestDAP_commands.py

@@ -0,0 +1,80 @@
+import os
+
+import dap_server
+import lldbdap_testcase
+from lldbsuite.test import lldbtest, lldbutil
+from lldbsuite.test.decorators import *
+
+
+class TestDAP_commands(lldbdap_testcase.DAPTestCaseBase):
+    def test_command_directive_quiet_on_success(self):
+        program = self.getBuildArtifact("a.out")
+        command_quiet = (
+            "settings set target.show-hex-variable-values-with-leading-zeroes false"
+        )
+        command_not_quiet = (
+            "settings set target.show-hex-variable-values-with-leading-zeroes true"
+        )
+        self.build_and_launch(
+            program,
+            initCommands=["?" + command_quiet, command_not_quiet],
+            terminateCommands=["?" + command_quiet, command_not_quiet],
+            stopCommands=["?" + command_quiet, command_not_quiet],
+            exitCommands=["?" + command_quiet, command_not_quiet],
+        )
+        full_output = self.collect_console(duration=1.0)
+        self.assertNotIn(command_quiet, full_output)
+        self.assertIn(command_not_quiet, full_output)
+
+    def do_test_abort_on_error(
+        self,
+        use_init_commands=False,
+        use_launch_commands=False,
+        use_pre_run_commands=False,
+        use_post_run_commands=False,
+    ):
+        program = self.getBuildArtifact("a.out")
+        command_quiet = (
+            "settings set target.show-hex-variable-values-with-leading-zeroes false"
+        )
+        command_abort_on_error = "settings set foo bar"
+        commands = ["?!" + command_quiet, "!" + command_abort_on_error]
+        self.build_and_launch(
+            program,
+            initCommands=commands if use_init_commands else None,
+            launchCommands=commands if use_launch_commands else None,
+            preRunCommands=commands if use_pre_run_commands else None,
+            postRunCommands=commands if use_post_run_commands else None,
+            expectFailure=True,
+        )
+        full_output = self.collect_console(duration=1.0)
+        self.assertNotIn(command_quiet, full_output)
+        self.assertIn(command_abort_on_error, full_output)
+
+    def test_command_directive_abort_on_error_init_commands(self):
+        self.do_test_abort_on_error(use_init_commands=True)
+
+    def test_command_directive_abort_on_error_launch_commands(self):
+        self.do_test_abort_on_error(use_launch_commands=True)
+
+    def test_command_directive_abort_on_error_pre_run_commands(self):
+        self.do_test_abort_on_error(use_pre_run_commands=True)
+
+    def test_command_directive_abort_on_error_post_run_commands(self):
+        self.do_test_abort_on_error(use_post_run_commands=True)
+
+    def test_command_directive_abort_on_error_attach_commands(self):
+        program = self.getBuildArtifact("a.out")
+        command_quiet = (
+            "settings set target.show-hex-variable-values-with-leading-zeroes false"
+        )
+        command_abort_on_error = "settings set foo bar"
+        self.build_and_create_debug_adaptor()
+        self.attach(
+            program,
+            attachCommands=["?!" + command_quiet, "!" + command_abort_on_error],
+            expectFailure=True,
+        )
+        full_output = self.collect_console(duration=1.0)
+        self.assertNotIn(command_quiet, full_output)
+        self.assertIn(command_abort_on_error, full_output)

lldb/test/API/tools/lldb-dap/commands/main.cpp

@@ -0,0 +1 @@
+int main() { return 0; }

lldb/tools/lldb-dap/DAP.cpp

@@ -434,20 +434,54 @@ ExpressionContext DAP::DetectExpressionContext(lldb::SBFrame &frame,
   return ExpressionContext::Variable;
 }
 
-void DAP::RunLLDBCommands(llvm::StringRef prefix,
-                          const std::vector<std::string> &commands) {
-  SendOutput(OutputType::Console,
-             llvm::StringRef(::RunLLDBCommands(prefix, commands)));
+bool DAP::RunLLDBCommands(llvm::StringRef prefix,
+                          llvm::ArrayRef<std::string> commands) {
+  bool required_command_failed = false;
+  std::string output =
+      ::RunLLDBCommands(prefix, commands, required_command_failed);
+  SendOutput(OutputType::Console, output);
+  return !required_command_failed;
+}
+
+static llvm::Error createRunLLDBCommandsErrorMessage(llvm::StringRef category) {
+  return llvm::createStringError(
+      llvm::inconvertibleErrorCode(),
+      llvm::formatv(
+          "Failed to run {0} commands. See the Debug Console for more details.",
+          category)
+          .str()
+          .c_str());
+}
+
+llvm::Error
+DAP::RunAttachCommands(llvm::ArrayRef<std::string> attach_commands) {
+  if (!RunLLDBCommands("Running attachCommands:", attach_commands))
+    return createRunLLDBCommandsErrorMessage("attach");
+  return llvm::Error::success();
 }
 
-void DAP::RunInitCommands() {
-  RunLLDBCommands("Running initCommands:", init_commands);
+llvm::Error
+DAP::RunLaunchCommands(llvm::ArrayRef<std::string> launch_commands) {
+  if (!RunLLDBCommands("Running launchCommands:", launch_commands))
+    return createRunLLDBCommandsErrorMessage("launch");
+  return llvm::Error::success();
 }
 
-void DAP::RunPreRunCommands() {
-  RunLLDBCommands("Running preRunCommands:", pre_run_commands);
+llvm::Error DAP::RunInitCommands() {
+  if (!RunLLDBCommands("Running initCommands:", init_commands))
+    return createRunLLDBCommandsErrorMessage("initCommands");
+  return llvm::Error::success();
 }
 
+llvm::Error DAP::RunPreRunCommands() {
+  if (!RunLLDBCommands("Running preRunCommands:", pre_run_commands))
+    return createRunLLDBCommandsErrorMessage("preRunCommands");
+  return llvm::Error::success();
+}
+
+void DAP::RunPostRunCommands() {
+  RunLLDBCommands("Running postRunCommands:", post_run_commands);
+}
 void DAP::RunStopCommands() {
   RunLLDBCommands("Running stopCommands:", stop_commands);
 }

lldb/tools/lldb-dap/DAP.h

@@ -158,6 +158,7 @@ struct DAP {
   std::vector<ExceptionBreakpoint> exception_breakpoints;
   std::vector<std::string> init_commands;
   std::vector<std::string> pre_run_commands;
+  std::vector<std::string> post_run_commands;
   std::vector<std::string> exit_commands;
   std::vector<std::string> stop_commands;
   std::vector<std::string> terminate_commands;
@@ -227,11 +228,17 @@ struct DAP {
   ExpressionContext DetectExpressionContext(lldb::SBFrame &frame,
                                             std::string &text);
 
-  void RunLLDBCommands(llvm::StringRef prefix,
-                       const std::vector<std::string> &commands);
-
-  void RunInitCommands();
-  void RunPreRunCommands();
+  /// \return
+  ///   \b false if a fatal error was found while executing these commands,
+  ///   according to the rules of \a LLDBUtils::RunLLDBCommands.
+  bool RunLLDBCommands(llvm::StringRef prefix,
+                       llvm::ArrayRef<std::string> commands);
+
+  llvm::Error RunAttachCommands(llvm::ArrayRef<std::string> attach_commands);
+  llvm::Error RunLaunchCommands(llvm::ArrayRef<std::string> launch_commands);
+  llvm::Error RunInitCommands();
+  llvm::Error RunPreRunCommands();
+  void RunPostRunCommands();
   void RunStopCommands();
   void RunExitCommands();
   void RunTerminateCommands();

lldb/tools/lldb-dap/LLDBUtils.cpp

@@ -11,40 +11,81 @@
 
 namespace lldb_dap {
 
-void RunLLDBCommands(llvm::StringRef prefix,
+bool RunLLDBCommands(llvm::StringRef prefix,
                      const llvm::ArrayRef<std::string> &commands,
-                     llvm::raw_ostream &strm) {
+                     llvm::raw_ostream &strm, bool parse_command_directives) {
   if (commands.empty())
-    return;
+    return true;
+
+  bool did_print_prefix = false;
+
   lldb::SBCommandInterpreter interp = g_dap.debugger.GetCommandInterpreter();
-  if (!prefix.empty())
-    strm << prefix << "\n";
-  for (const auto &command : commands) {
+  for (llvm::StringRef command : commands) {
     lldb::SBCommandReturnObject result;
-    strm << "(lldb) " << command << "\n";
-    interp.HandleCommand(command.c_str(), result);
-    auto output_len = result.GetOutputSize();
-    if (output_len) {
-      const char *output = result.GetOutput();
-      strm << output;
+    bool quiet_on_success = false;
+    bool check_error = false;
+
+    while (parse_command_directives) {
+      if (command.starts_with("?")) {
+        command = command.drop_front();
+        quiet_on_success = true;
+      } else if (command.starts_with("!")) {
+        command = command.drop_front();
+        check_error = true;
+      } else {
+        break;
+      }
     }
-    auto error_len = result.GetErrorSize();
-    if (error_len) {
-      const char *error = result.GetError();
-      strm << error;
+
+    interp.HandleCommand(command.str().c_str(), result);
+    const bool got_error = !result.Succeeded();
+    // The if statement below is assuming we always print out `!` prefixed
+    // lines. The only time we don't print is when we have `quiet_on_success ==
+    // true` and we don't have an error.
+    if (quiet_on_success ? got_error : true) {
+      if (!did_print_prefix && !prefix.empty()) {
+        strm << prefix << "\n";
+        did_print_prefix = true;
+      }
+      strm << "(lldb) " << command << "\n";
+      auto output_len = result.GetOutputSize();
+      if (output_len) {
+        const char *output = result.GetOutput();
+        strm << output;
+      }
+      auto error_len = result.GetErrorSize();
+      if (error_len) {
+        const char *error = result.GetError();
+        strm << error;
+      }
     }
+    if (check_error && got_error)
+      return false; // Stop running commands.
   }
+  return true;
 }
 
 std::string RunLLDBCommands(llvm::StringRef prefix,
-                            const llvm::ArrayRef<std::string> &commands) {
+                            const llvm::ArrayRef<std::string> &commands,
+                            bool &required_command_failed,
+                            bool parse_command_directives) {
+  required_command_failed = false;
   std::string s;
   llvm::raw_string_ostream strm(s);
-  RunLLDBCommands(prefix, commands, strm);
+  required_command_failed =
+      !RunLLDBCommands(prefix, commands, strm, parse_command_directives);
   strm.flush();
   return s;
 }
 
+std::string
+RunLLDBCommandsVerbatim(llvm::StringRef prefix,
+                        const llvm::ArrayRef<std::string> &commands) {
+  bool required_command_failed = false;
+  return RunLLDBCommands(prefix, commands, required_command_failed,
+                         /*parse_command_directives=*/false);
+}
+
 bool ThreadHasStopReason(lldb::SBThread &thread) {
   switch (thread.GetStopReason()) {
   case lldb::eStopReasonTrace:

lldb/tools/lldb-dap/LLDBUtils.h

@@ -23,6 +23,12 @@ namespace lldb_dap {
 /// All output from every command, including the prompt + the command
 /// is placed into the "strm" argument.
 ///
+/// Each individual command can be prefixed with \b ! and/or \b ? in no
+/// particular order. If \b ? is provided, then the output of that command is
+/// only emitted if it fails, and if \b ! is provided, then the output is
+/// emitted regardless, and \b false is returned without executing the
+/// remaining commands.
+///
 /// \param[in] prefix
 ///     A string that will be printed into \a strm prior to emitting
 ///     the prompt + command and command output. Can be NULL.
@@ -33,9 +39,17 @@ namespace lldb_dap {
 /// \param[in] strm
 ///     The stream that will receive the prefix, prompt + command and
 ///     all command output.
-void RunLLDBCommands(llvm::StringRef prefix,
+///
+/// \param[in] parse_command_directives
+///     If \b false, then command prefixes like \b ! or \b ? are not parsed and
+///     each command is executed verbatim.
+///
+/// \return
+///     \b true, unless a command prefixed with \b ! fails and parsing of
+///     command directives is enabled.
+bool RunLLDBCommands(llvm::StringRef prefix,
                      const llvm::ArrayRef<std::string> &commands,
-                     llvm::raw_ostream &strm);
+                     llvm::raw_ostream &strm, bool parse_command_directives);
 
 /// Run a list of LLDB commands in the LLDB command interpreter.
 ///
@@ -49,11 +63,26 @@ void RunLLDBCommands(llvm::StringRef prefix,
 /// \param[in] commands
 ///     An array of LLDB commands to execute.
 ///
+/// \param[out] required_command_failed
+///     If parsing of command directives is enabled, this variable is set to
+///     \b true if one of the commands prefixed with \b ! fails.
+///
+/// \param[in] parse_command_directives
+///     If \b false, then command prefixes like \b ! or \b ? are not parsed and
+///     each command is executed verbatim.
+///
 /// \return
 ///     A std::string that contains the prefix and all commands and
-///     command output
+///     command output.
 std::string RunLLDBCommands(llvm::StringRef prefix,
-                            const llvm::ArrayRef<std::string> &commands);
+                            const llvm::ArrayRef<std::string> &commands,
+                            bool &required_command_failed,
+                            bool parse_command_directives = true);
+
+/// Similar to the method above, but without parsing command directives.
+std::string
+RunLLDBCommandsVerbatim(llvm::StringRef prefix,
+                        const llvm::ArrayRef<std::string> &commands);
 
 /// Check if a thread has a stop reason.
 ///