Enable Launching the Debugee in VSCode Terminal

[wallace]

Summary

A "Launch In Terminal" option is added to the debug settings in IDE. When turn this option on, the debugee will be launched inside the integrated terminal so that user can input values for debugging. This diff involves the runInTerminal request sent from lldb to IDE and lldb won't attach the program until the runInTerminal response is received. A response handler for the runInTerminal response from IDE to lldb is added to handle the reverse requests and corresponding responses.
The screenshot shows what it looks like when the debugee is launched in terminal.

[wallace]

This is very good for a first implementation. You need to write a test for this as well. Once this works, you have to work on the launcher helper Greg and I mentioned to you that will help you guarantee you can always attach to the target.

Regarding the test, you have to build the python code that will mimic the runInTerminal reverse request, along with its response, which will just launch the debuggee inside a terminal.

For launching a process inside a shell from python, you can use the subprocess.run function and pass the shell=True attribute.

For adding the runInTerminal reverse request in python, take a look at the file packages/Python/lldbsuite/test/tools/lldb-vscode/vscode.py. You can see examples like request_launch, where it sends data and waits for a response using the send_recv method. You should add support for reverse requests.

lldb/tools/lldb-vscode/lldb-vscode.cpp

1382

s/VScode/VSCode

1605

move the entire contents of this if to another function for readability

1609

does it work if you don't specify the "seq" number? If it works without it, I would leave it empty

1612

what if cwd is not specified in the arguments? I imagine this might break or at least the IDE wouldn't be able to launch the target properly.
If "cwd" is not defined, then use llvm::sys::fs::current_path() instead. Does this make sense @clayborg ?

1615

what happens if it fails to attach? Try running a program that dies right away and that lldb can't attach. Does the debug session terminate correctly?

1615

mention here that VSCode doesn't respond back the pid of the target, so we can only attach by process name, which is already set up in the request_launch method

1618–1621

run clang-format

1625

remove this comment

1625

shouldn't you return at this point and not execute anything that happens after this?
The lines

g_vsc.SendJSON(llvm::json::Value(std::move(response)));
SendProcessEvent(Launch); // Maybe change this for Attach as you'll end up actually doing an attach
g_vsc.SendJSON(llvm::json::Value(CreateEventObject("initialized")));

probably should only be sent after you were able to attach.

1625

remove this

3009

you should use the command here, instead of the hardcoded string "runInTerminal"

[clayborg]

So there is a fundamental change needed for this patch to work. I tried to fully detail this in the inline comments. Let me know if you have any questions.

lldb/tools/lldb-vscode/lldb-vscode.cpp

1609

Remove this line. I will explain more in next inline comment!

1612

yes, we need to set this correctly if it isn't set in the launch.json and your suggestion makes sense.

1624

So I am not sure we need to do all of the response handler stuff since we need to get the result of this before we can proceed. So we need to be able to send this request and receive the response right here. So we need to add that ability to VSCode (the type definition of g_vsc).

This code should be:

llvm::json::Object reverseResponse = g_vsc.SendReverseRequest(llvm::json::Value(std::move(reverseRequest)));

Then we need to extract the pid from the response right in this function. Right now we don't have a thread that is listening for more packets, we just have the main thread getting the current packet ("launch" in this case) and we are currently handling this function, so there is no way we will get a response in this function if we don't do this.

You will need to write the "SendReverseRequest()" function in VSCode and it will rely on refactoring that I mentioned below in the main() function where we make VSCode::GetObject() and VSCode::HandleObject() and uses the new "PacketStatus" enum. The SendReverseRequest function will do something like:

struct VSCode {
...
  uint32_t reverse_request_seq = 0;  
  PacketStatus SendReverseRequest(const llvm::json::Value &request, llvm::json::Object &response) {
    // Put the right "seq" into the packet here, so we don't have to do it from
    // where we send the reverse request.
    request.try_emplace("seq", ++reverse_request_seq);
    SendJSON(request);
    bool got_response = false;
    while (!got_response) {
      llvm::json::Object response;
      Status status = GetObject(response);
      if (status == PacketStatus::Success) {
        const auto packet_type = GetString(response, "type");
        if (packet_type == "response")
          return status;
        // Not our response, we got another packet
       HandleObject(response)
      } else {
        return status;
      }
    }
  }

The "VSCode::GetResponse" is a new function as well that we will make from

2996–3006

We need to move these lines into VSCode.h and VSCode.cpp into a function called GetObject():

enum class PacketStatus {
  Success = 0
  EndOfFile,
  JSONMalformed,
  JSONNotObject
};

PacketStatus VSCode::GetObject(llvm::json::Object &object) {
  std::string json =ReadJSON();
  if (json.empty())
      return PacketStatus::EndOfFile;

  llvm::StringRef json_sref(json);
  llvm::Expected<llvm::json::Value> json_value = llvm::json::parse(json_sref);
  if (!json_value) {
    auto error = json_value.takeError();
    if (log) {
      std::string error_str;
      llvm::raw_string_ostream strm(error_str);
      strm << error;
      strm.flush();
      *log << "error: failed to parse JSON: " << error_str << std::endl
                 << json << std::endl;
    }
    return PacketStatus::JSONMalformed;
  }
  object = std::move(json_value->getAsObject());
  if (!object) {
    if (log)
      *log << "error: json packet isn't a object" << std::endl;
    return PacketStatus::JSONNotObject;
  }
  return PacketStatus::Success;
}

This will allow us to use this function in the VSCode::SendReverseRequest(). Then this code becomes:

llvm::json::Object object;
PacketStatus status = g_vsc.GetObject(object);
if (status == PacketStatus::EndOfFile)
  break;
if (status != PacketStatus::Success)
  return 1; // Fatal error

We need to do this so we can re-use the VSCode::GetObject in VSCode::SendReverseRequest().

3005–3006

This should also be moved into VSCode.h/VSCode.cpp:

bool VSCode::HandleObject(const llvm::json::Object& object) {

const auto packet_type = GetString(object, "type");
if (packet_type == "request") {
  const auto command = GetString(object, "command");
  auto handler_pos = request_handlers.find(std::string(command));
  if (handler_pos != request_handlers.end()) {
    handler_pos->second(*object);
    return true; // Success
} else {
    if (log)
      *log << "error: unhandled command \"" << command.data() << std::endl;
    return false; // Fail
}

}

Then this code becomes:

if (!g_vsc.HandleObject(object))

return 1;

[clayborg]

lldb/tools/lldb-vscode/lldb-vscode.cpp

1615

The response has the process ID of what we need to attach to right? Why do we need to do this by name?

[• aelitashen]

Add a attacher thread to avoid race condition

[• aelitashen]

Remove uncomplete tests

[clayborg]

So there is a lot of noise in this patch that is just reformatting on code that hasn't changed. It would be nice to get rid of any changes that are whitespace/indentation/formatting only. Also see inlined comments for needed changes.

lldb/tools/lldb-vscode/VSCode.cpp

390

add "const" to before "llvm::json::Object &request"

lldb/tools/lldb-vscode/VSCode.h

170–177

Revert all changes to this function. Seems like there are some forward declarations to functions in here for some reason that aren't needed.

lldb/tools/lldb-vscode/lldb-vscode.cpp

1446

Add more comment here to explain how we are attaching. Maybe something like:

// We have already created a target that has a valid "program" path to the executable.
// We will attach to the next process whose basename matches that of the target's 
// executable by waiting for the next process to launch that matches. This help LLDB
// ignore any existing processes that are already running that match this executable
// name and wait for the next one to launch.

1453–1454

Inline the lambda, add a comment, and enable async mode to ensure we don't have a race condition:

// Here we launch a thread to do the attach. We disable async events so
// that when we call g_vsc.target.Attach(...) it will not return unless the attach
// succeeds. In the event the attach never happens, the user will be able to hit
// the square stop button in the debug session and it will kill lldb-vscode. If
// this ever changes in the IDE we will need to do more work to ensure we can
// nicely timeout from the attach after a set period of time.
std::thread attacher([&]() { 
   g_vsc.debugger.SetAsync(false);
   g_vsc.target.Attach(attach_info, error); 
   g_vsc.debugger.SetAsync(true);
});

1491–1511

Need to clean up this logic a bit. We have two "if (error.Success())" statements and the flow of the code is hard to follow.

if (error.Success()) {
  // IDE doesn't respond back the pid of the target from the runInTerminal 
  // response, so we have lldb attach by name and wait, so grab the process
  // ID from the target.
  auto attached_pid = g_vsc.target.GetProcess().GetProcessID();
  if (attached_pid == LLDB_INVALID_PROCESS_ID)
    error.SetErrorString("Failed to attach to a process");
  else
    SendProcessEvent(Attach);
}

// Check error again as it might have been modified with a new error above.
if (error.Fail()) {
  launch_response["success"] = llvm::json::Value(false);
  EmplaceSafeString(launch_response, "message", std::string(error.GetCString()));
} else {
  launch_response["success"] = llvm::json::Value(true);
}

1605–1610

Remove all new indentation that was added for the else scope and use early return:

if (GetBoolean(arguments, "launchInTerminal", false)) {
  request_runInTerminal(request, response);
  g_vsc.SendJSON(llvm::json::Value(std::move(response)));
  return;
}

[clayborg]

lldb/tools/lldb-vscode/VSCode.h

177

I thought this was the contents of a "lldb::SBTarget CreateTargetFromArguments(const llvm::json::Object &arguments, lldb::SBError &error);" function!

Ignore this bad comment!

[clayborg]

lldb/tools/lldb-vscode/VSCode.cpp

390

I see we are modifying "request" below, so we can't make it "const". There are two ways to fix this:
1 - change it to be "llvm::json::Object request" and then use std::move() when calling SendReverseRequest.
2 - just leave as a reference and modify the original object.

I think I prefer option #1.

[clayborg]

lldb/tools/lldb-vscode/VSCode.cpp

390

Or we can leave this as "const" as originally suggested and add a function to VSCode:

llvm::json::Object VSCode::CreateReverseRequest(std::string command) {
  llvm::json::Object request;
  request.try_emplace("type", "request");
  request.try_emplace("command", command);
  request.try_emplace("seq", ++reverse_request_seq);
  return request;
}

And call that in request_runInTerminal when creating the reverse request packet. See other inline comment for details.

lldb/tools/lldb-vscode/lldb-vscode.cpp

1458–1460

This could become:

llvm::json::Object reverseRequest = g_vsc.CreateReverseRequest("runInTerminal");

And then we wouldn't need to add the "seq" key/value pair in SendReverseRequest

[• aelitashen]

Refactor code and optimize logic

[• aelitashen]

I tried rebase onto the commit that Walter created just for formatting but I am not sure why it didn't remove those formatting noise..

lldb/tools/lldb-vscode/VSCode.cpp

390

I eventually choose #1 cuz const keeps raising problem when calling function like try_emplace() and move() :(

[clayborg]

All of the code looks good now and we need to add a test. This means we will need to modify vscode.py in the test suite to be able to received the reverse request and just launch the process. We don't need to launch the program in a terminal, just spawn the process using subprocess.

[• aelitashen]

@Walter Please help me fix the tests. Looks like in the new added runInTerminal tests, it cannot hit the breakpoint and capture the local variable.

[wallace]

We found a very strange issue with lldb not stopping at any breakpoint after attaching. I'll figure that out

[wallace]

Now this feature is fully functional. Besiding adding a test, I was able to debug LLDB from an integrated terminal in VSCode. Stdin and stdout work correctly.

This is LLDB being debugger

Regarding the implementation, I'm attaching asynchronously to the inferior using the wait-for logic. As soon as the first stop event happens, the response from the launch request is sent to the IDE to finish the configuration.

As a last detail, when the debug session ends, VSCode closes the terminal.

[aeubanks]

the added test TestVSCode_runInTerminal consistently fails for me locally with

Failed to attach to the target process. Timed out trying to get messages from the runInTerminal launcher

I've asked other people and they've also reported consistent (or flaky) failures of this test. Any idea of what could be going wrong?

[labath]

I'm pretty sure that's because YAMA prevents the attach operation. The test probably needs to launch the binary through something like this.

lldb/packages/Python/lldbsuite/test/tools/lldb-vscode/lldbvscode_testcase.py

def attach(self, program=None, pid=None, waitFor=None, trace=None,
                             'attach failed (%s)' % (response['message']))
 
     def launch(self, program=None, args=None, cwd=None, env=None,
                stopOnEntry=False, disableASLR=True,
                disableSTDIO=False, shellExpandArguments=False,
                trace=False, initCommands=None, preRunCommands=None,
                stopCommands=None, exitCommands=None, terminateCommands=None,
                sourcePath=None, debuggerRoot=None, launchCommands=None,
-               sourceMap=None, disconnectAutomatically=True):
+               sourceMap=None, disconnectAutomatically=True, runInTerminal=False):
         '''Sending launch request to vscode
         '''
 
         # Make sure we disconnect and terminate the VSCode debug adapter,
         # if we throw an exception during the test case
         def cleanup():
             if disconnectAutomatically:
                 self.vscode.request_disconnect(terminateDebuggee=True)
def launch(self, program=None, args=None, cwd=None, env=None,
             initCommands=initCommands,
             preRunCommands=preRunCommands,
             stopCommands=stopCommands,
             exitCommands=exitCommands,
             terminateCommands=terminateCommands,
             sourcePath=sourcePath,
             debuggerRoot=debuggerRoot,
             launchCommands=launchCommands,
-            sourceMap=sourceMap)
+            sourceMap=sourceMap,
+            runInTerminal=runInTerminal)
         if not (response and response['success']):
             self.assertTrue(response['success'],
                             'launch failed (%s)' % (response['message']))
+        # We need to trigger a request_configurationDone after we've successfully
+        # attached a runInTerminal process to finish initialization.
+        if runInTerminal:
+            self.vscode.request_configurationDone()
+
 
     def build_and_launch(self, program, args=None, cwd=None, env=None,
                          stopOnEntry=False, disableASLR=True,
                          disableSTDIO=False, shellExpandArguments=False,
                          trace=False, initCommands=None, preRunCommands=None,
                          stopCommands=None, exitCommands=None,
                          terminateCommands=None, sourcePath=None,
-                         debuggerRoot=None):
+                         debuggerRoot=None, runInTerminal=False):
         '''Build the default Makefile target, create the VSCode debug adaptor,
            and launch the process.
         '''
         self.build_and_create_debug_adaptor()
         self.assertTrue(os.path.exists(program), 'executable must exist')
 
         self.launch(program, args, cwd, env, stopOnEntry, disableASLR,
                     disableSTDIO, shellExpandArguments, trace,
                     initCommands, preRunCommands, stopCommands, exitCommands,
-                    terminateCommands, sourcePath, debuggerRoot)
+                    terminateCommands, sourcePath, debuggerRoot, runInTerminal=runInTerminal)

lldb/packages/Python/lldbsuite/test/tools/lldb-vscode/vscode.py

class DebugCommunication(object):
     def send_recv(self, command):
         '''Send a command python dictionary as JSON and receive the JSON
            response. Validates that the response is the correct sequence and
            command in the reply. Any events that are received are added to the
            events list in this object'''
         self.send_packet(command)
         done = False
         while not done:
-            response = self.recv_packet(filter_type='response')
-            if response is None:
+            response_or_request = self.recv_packet(filter_type=['response', 'request'])
+            if response_or_request is None:
                 desc = 'no response for "%s"' % (command['command'])
                 raise ValueError(desc)
-            self.validate_response(command, response)
-            return response
+            if response_or_request['type'] == 'response':
+                self.validate_response(command, response_or_request)
+                return response_or_request
+            else:
+                if response_or_request['command'] == 'runInTerminal':
+                    subprocess.Popen(response_or_request['arguments']['args'], 
+                        env=response_or_request['arguments']['env'])
+                    self.send_packet({
+                        "type": "response",
+                        "seq": -1,
+                        "request_seq": response_or_request['seq'],
+                        "success": True,
+                        "command": "runInTerminal",
+                        "body": {}
+                    }, set_sequence=False)
+                else:
+                    desc = 'unkonwn reverse request "%s"' % (response_or_request['command'])
+                    raise ValueError(desc)
+            
         return None
 
     def wait_for_event(self, filter=None, timeout=None):
         while True:
             return self.recv_packet(filter_type='event', filter_event=filter,
                                     timeout=timeout)
         return None
 
def request_initialize(self):
         return response
 
     def request_launch(self, program, args=None, cwd=None, env=None,
                        stopOnEntry=False, disableASLR=True,
                        disableSTDIO=False, shellExpandArguments=False,
                        trace=False, initCommands=None, preRunCommands=None,
                        stopCommands=None, exitCommands=None,
                        terminateCommands=None ,sourcePath=None,
-                       debuggerRoot=None, launchCommands=None, sourceMap=None):
+                       debuggerRoot=None, launchCommands=None, sourceMap=None,
+                       runInTerminal=False):
         args_dict = {
             'program': program
         }
         if args:
             args_dict['args'] = args
         if cwd:
             args_dict['cwd'] = cwd
         if env:
def request_launch(self, program, args=None, cwd=None, env=None,
         if sourcePath:
             args_dict['sourcePath'] = sourcePath
         if debuggerRoot:
             args_dict['debuggerRoot'] = debuggerRoot
         if launchCommands:
             args_dict['launchCommands'] = launchCommands
         if sourceMap:
             args_dict['sourceMap'] = sourceMap
+        if runInTerminal:
+            args_dict['runInTerminal'] = runInTerminal
         command_dict = {
             'command': 'launch',
             'type': 'request',
             'arguments': args_dict
         }
         response = self.send_recv(command_dict)
 
         # Wait for a 'process' and 'initialized' event in any order

lldb/test/API/tools/lldb-vscode/runInTerminal/Makefile

+C_SOURCES := main.c
+
+include Makefile.rules

lldb/test/API/tools/lldb-vscode/runInTerminal/TestVSCode_runInTerminal.py

+"""
+Test lldb-vscode runInTerminal reverse request
+"""
+
+
+import unittest2
+import vscode
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+import lldbvscode_testcase
+import time
+import os
+
+
+class TestVSCode_runInTerminal(lldbvscode_testcase.VSCodeTestCaseBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    @skipIfWindows
+    @skipIfRemote
+    def test_runInTerminal(self):
+        '''
+            Tests the "runInTerminal" reverse request. It makes sure that the IDE can
+            launch the inferior with the correct environment variables and arguments.
+        '''
+        program = self.getBuildArtifact("a.out")
+        source = 'main.c'
+        self.build_and_launch(program, stopOnEntry=True, runInTerminal=True, args=["foobar"], env=["FOO=bar"])
+        breakpoint_line = line_number(source, '// breakpoint')
+        
+        self.set_source_breakpoints(source, [breakpoint_line])
+        self.continue_to_next_stop()
+        
+        # We verify we actually stopped inside the loop
+        counter = int(self.vscode.get_local_variable_value('counter'))
+        self.assertTrue(counter > 0)
+
+        # We verify we were able to set the launch arguments
+        argc = int(self.vscode.get_local_variable_value('argc'))
+        self.assertEqual(argc, 2)
+        
+        argv1 = self.vscode.request_evaluate('argv[1]')['body']['result']
+        self.assertIn('foobar', argv1)
+        
+        # We verify we were able to set the environment
+        env = self.vscode.request_evaluate('foo')['body']['result']
+        self.assertIn('bar', env)

lldb/test/API/tools/lldb-vscode/runInTerminal/main.c

+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int main(int argc, char *argv[]) {
+  const char *foo = getenv("FOO");
+  for (int counter = 1;; counter++) {
+    sleep(1); // breakpoint
+  }
+  return 0;
+}

lldb/tools/lldb-vscode/JSONUtils.h

 //===-- JSONUtils.h ---------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_TOOLS_LLDB_VSCODE_JSONUTILS_H
 #define LLDB_TOOLS_LLDB_VSCODE_JSONUTILS_H
 
 #include "VSCodeForward.h"
 #include "lldb/API/SBModule.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/JSON.h"
 #include <stdint.h>
 
 namespace lldb_vscode {
 
 /// Emplace a StringRef in a json::Object after enusring that the
 /// string is valid UTF8. If not, first call llvm::json::fixUTF8

 /// \return
 ///     A "Variable" JSON object with that follows the formal JSON
 ///     definition outlined by Microsoft.
 llvm::json::Value CreateVariable(lldb::SBValue v, int64_t variablesReference,
                                  int64_t varID, bool format_hex);
 
 llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit);
 
+/// Create a runInTerminal reverse request object
+///
+/// \param[in] launch_request
+///     The original launch_request object whose fields are used to construct
+///     the reverse request object.
+///
+/// \return
+///     A "runInTerminal" JSON object that follows the specification outlined by
+///     Microsoft.
+llvm::json::Object
+CreateRunInTerminalReverseRequest(const llvm::json::Object &launch_request);
+
 } // namespace lldb_vscode
 
 #endif

lldb/tools/lldb-vscode/JSONUtils.cpp

 #include <iomanip>
 #include <sstream>
 
 #include "llvm/ADT/Optional.h"
 #include "llvm/Support/FormatAdapters.h"
 #include "llvm/Support/Path.h"
 #include "llvm/Support/ScopedPrinter.h"
 
 #include "lldb/API/SBBreakpoint.h"
 #include "lldb/API/SBBreakpointLocation.h"
 #include "lldb/API/SBValue.h"
 #include "lldb/Host/PosixApi.h"
 
 #include "ExceptionBreakpoint.h"
 #include "JSONUtils.h"
 #include "LLDBUtils.h"
 #include "VSCode.h"
llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit) {
   llvm::json::Object object;
   char unit_path_arr[PATH_MAX];
   unit.GetFileSpec().GetPath(unit_path_arr, sizeof(unit_path_arr));
   std::string unit_path(unit_path_arr);
   object.try_emplace("compileUnitPath", unit_path);
   return llvm::json::Value(std::move(object));
 }
 
+/// See
+/// https://microsoft.github.io/debug-adapter-protocol/specification#Reverse_Requests_RunInTerminal
+llvm::json::Object
+CreateRunInTerminalReverseRequest(const llvm::json::Object &launch_request) {
+  llvm::json::Object reverse_request;
+  reverse_request.try_emplace("type", "request");
+  reverse_request.try_emplace("command", "runInTerminal");
+
+  llvm::json::Object run_in_terminal_args;
+  // This indicates the IDE to open an embedded terminal, instead of opening the
+  // terminal in a new window.
+  run_in_terminal_args.try_emplace("kind", "integrated");
+
+  auto launch_request_arguments = launch_request.getObject("arguments");
+  std::vector<std::string> args = GetStrings(launch_request_arguments, "args");
+  // The program path must be the first entry in the "args" field
+  args.insert(args.begin(),
+              GetString(launch_request_arguments, "program").str());
+  run_in_terminal_args.try_emplace("args", args);
+
+  const auto cwd = GetString(launch_request_arguments, "cwd");
+  if (!cwd.empty())
+    run_in_terminal_args.try_emplace("cwd", cwd);
+
+  // We need to convert the input list of environments variables into a
+  // dictionary
+  std::vector<std::string> envs = GetStrings(launch_request_arguments, "env");
+  llvm::json::Object environment;
+  for (const std::string &env : envs) {
+    size_t index = env.find("=");
+    environment.try_emplace(env.substr(0, index), env.substr(index + 1));
+  }
+  run_in_terminal_args.try_emplace("env",
+                                   llvm::json::Value(std::move(environment)));
+
+  reverse_request.try_emplace(
+      "arguments", llvm::json::Value(std::move(run_in_terminal_args)));
+  return reverse_request;
+}
+
 } // namespace lldb_vscode

lldb/tools/lldb-vscode/VSCode.h

 #include <set>
 #include <stdio.h>
 #include <thread>
 
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/DenseSet.h"
 #include "llvm/ADT/StringMap.h"
 #include "llvm/ADT/StringRef.h"
+#include "llvm/Support/JSON.h"
 #include "llvm/Support/raw_ostream.h"
 
 #include "lldb/API/SBAttachInfo.h"
 #include "lldb/API/SBBreakpoint.h"
 #include "lldb/API/SBBreakpointLocation.h"
 #include "lldb/API/SBCommandInterpreter.h"
 #include "lldb/API/SBCommandReturnObject.h"
 #include "lldb/API/SBCommunication.h"
 #include "lldb/API/SBDebugger.h"
 #include "lldb/API/SBEvent.h"
 #include "lldb/API/SBHostOS.h"

 namespace lldb_vscode {
 
 typedef llvm::DenseMap<uint32_t, SourceBreakpoint> SourceBreakpointMap;
 typedef llvm::StringMap<FunctionBreakpoint> FunctionBreakpointMap;
 enum class OutputType { Console, Stdout, Stderr, Telemetry };
 
 enum VSCodeBroadcasterBits { eBroadcastBitStopEventThread = 1u << 0 };
 
+typedef void (*RequestCallback)(const llvm::json::Object &command);
+
+enum class PacketStatus {
+  Success = 0,
+  EndOfFile,
+  JSONMalformed,
+  JSONNotObject
+};
+
 struct VSCode {
   InputStream input;
   OutputStream output;
   lldb::SBDebugger debugger;
   lldb::SBTarget target;
   lldb::SBValueList variables;
   lldb::SBBroadcaster broadcaster;
   int64_t num_regs;
struct VSCode {
   std::vector<std::string> pre_run_commands;
   std::vector<std::string> exit_commands;
   std::vector<std::string> stop_commands;
   std::vector<std::string> terminate_commands;
   lldb::tid_t focus_tid;
   bool sent_terminated_event;
   bool stop_at_entry;
   bool is_attach;
+  uint32_t reverse_request_seq;
+  std::map<std::string, RequestCallback> request_handlers;
+  std::condition_variable request_in_terminal_cv;
+  bool waiting_for_run_in_terminal;
   // Keep track of the last stop thread index IDs as threads won't go away
   // unless we send a "thread" event to indicate the thread exited.
   llvm::DenseSet<lldb::tid_t> thread_ids;
   VSCode();
   ~VSCode();
   VSCode(const VSCode &rhs) = delete;
   void operator=(const VSCode &rhs) = delete;
   int64_t GetLineForPC(int64_t sourceReference, lldb::addr_t pc) const;
struct VSCode {
   /// \return
   ///     An SBTarget object.
   lldb::SBTarget CreateTargetFromArguments(const llvm::json::Object &arguments,
                                            lldb::SBError &error);
 
   /// Set given target object as a current target for lldb-vscode and start
   /// listeing for its breakpoint events.
   void SetTarget(const lldb::SBTarget target);
+
+  const std::map<std::string, RequestCallback> &GetRequestHandlers();
+
+  PacketStatus GetObject(llvm::json::Object &object);
+  bool HandleObject(const llvm::json::Object &object);
+
+  /// Send a Debug Adapter Protocol reverse request to the IDE
+  ///
+  /// \param[in] request
+  ///   The payload of the request to send.
+  ///
+  /// \param[out] response
+  ///   The response of the IDE. It might be undefined if there was an error.
+  ///
+  /// \return
+  ///   A \a PacketStatus object indicating the sucess or failure of the
+  ///   request.
+  PacketStatus SendReverseRequest(llvm::json::Object request,
+                                  llvm::json::Object &response);
+
+  /// Registers a callback handler for a Debug Adapter Protocol request
+  ///
+  /// \param[in] request
+  ///     The name of the request following the Debug Adapter Protocol
+  ///     specification.
+  ///
+  /// \param[in] callback
+  ///     The callback to execute when the given request is triggered by the
+  ///     IDE.
+  void RegisterRequestCallback(std::string request, RequestCallback callback);
 };
 
 extern VSCode g_vsc;
 
 } // namespace lldb_vscode
 
 #endif

lldb/tools/lldb-vscode/VSCode.cpp

: variables(), broadcaster("lldb-vscode"), num_regs(0), num_locals(0),
       exception_breakpoints(
           {{"cpp_catch", "C++ Catch", lldb::eLanguageTypeC_plus_plus},
            {"cpp_throw", "C++ Throw", lldb::eLanguageTypeC_plus_plus},
            {"objc_catch", "Objective C Catch", lldb::eLanguageTypeObjC},
            {"objc_throw", "Objective C Throw", lldb::eLanguageTypeObjC},
            {"swift_catch", "Swift Catch", lldb::eLanguageTypeSwift},
            {"swift_throw", "Swift Throw", lldb::eLanguageTypeSwift}}),
       focus_tid(LLDB_INVALID_THREAD_ID), sent_terminated_event(false),
-      stop_at_entry(false), is_attach(false) {
+      stop_at_entry(false), is_attach(false),
+      waiting_for_run_in_terminal(false), reverse_request_seq(0) {
   const char *log_file_path = getenv("LLDBVSCODE_LOG");
 #if defined(_WIN32)
   // Windows opens stdout and stdin in text mode which converts \n to 13,10
   // while the value is just 10 on Darwin/Linux. Setting the file mode to binary
   // fixes this.
   int result = _setmode(fileno(stdout), _O_BINARY);
   assert(result);
   result = _setmode(fileno(stdin), _O_BINARY);
if (target.IsValid()) {
     listener.StartListeningForEvents(
         this->target.GetBroadcaster(),
         lldb::SBTarget::eBroadcastBitModulesLoaded |
             lldb::SBTarget::eBroadcastBitModulesUnloaded |
             lldb::SBTarget::eBroadcastBitSymbolsLoaded);
   }
 }
 
+PacketStatus VSCode::GetObject(llvm::json::Object &object) {
+  std::string json = ReadJSON();
+  if (json.empty())
+    return PacketStatus::EndOfFile;
+
+  llvm::StringRef json_sref(json);
+  llvm::Expected<llvm::json::Value> json_value = llvm::json::parse(json_sref);
+  if (!json_value) {
+    auto error = json_value.takeError();
+    if (log) {
+      std::string error_str;
+      llvm::raw_string_ostream strm(error_str);
+      strm << error;
+      strm.flush();
+      *log << "error: failed to parse JSON: " << error_str << std::endl
+           << json << std::endl;
+    }
+    return PacketStatus::JSONMalformed;
+  }
+  object = *json_value->getAsObject();
+  if (!json_value->getAsObject()) {
+    if (log)
+      *log << "error: json packet isn't a object" << std::endl;
+    return PacketStatus::JSONNotObject;
+  }
+  return PacketStatus::Success;
+}
+
+bool VSCode::HandleObject(const llvm::json::Object &object) {
+  const auto packet_type = GetString(object, "type");
+  if (packet_type == "request") {
+    const auto command = GetString(object, "command");
+    auto handler_pos = request_handlers.find(std::string(command));
+    if (handler_pos != request_handlers.end()) {
+      handler_pos->second(object);
+      return true; // Success
+    } else {
+      if (log)
+        *log << "error: unhandled command \"" << command.data() << std::endl;
+      return false; // Fail
+    }
+  }
+  return false;
+}
+
+PacketStatus VSCode::SendReverseRequest(llvm::json::Object request,
+                                        llvm::json::Object &response) {
+  request.try_emplace("seq", ++reverse_request_seq);
+  SendJSON(llvm::json::Value(std::move(request)));
+  bool got_response = false;
+  while (!got_response) {
+    PacketStatus status = GetObject(response);
+    const auto packet_type = GetString(response, "type");
+    if (packet_type == "response") {
+      if (status == PacketStatus::Success) {
+        return status;
+        // Not our response, we got another packet
+        HandleObject(response);
+      } else {
+        return status;
+      }
+    }
+  }
+}
+
+void VSCode::RegisterRequestCallback(std::string request,
+                                     RequestCallback callback) {
+  request_handlers[request] = callback;
+}
+
 } // namespace lldb_vscode

lldb/tools/lldb-vscode/lldb-vscode.cpp

if (listener.WaitForEvent(1, event)) {
           case lldb::eStateStepping:
             break;
           case lldb::eStateCrashed:
             break;
           case lldb::eStateDetached:
             break;
           case lldb::eStateSuspended:
             break;
-          case lldb::eStateStopped:
+          case lldb::eStateStopped: {
+            if (g_vsc.waiting_for_run_in_terminal) {
+              g_vsc.waiting_for_run_in_terminal = false;
+              g_vsc.request_in_terminal_cv.notify_one();
+            }
+          }
             // Only report a stopped event if the process was not restarted.
             if (!lldb::SBProcess::GetRestartedFromEvent(event)) {
               SendStdOutStdErr(process);
               SendThreadStoppedEvent();
             }
             break;
           case lldb::eStateRunning:
             break;
void request_initialize(const llvm::json::Object &request) {
   // data hovers.
   body.try_emplace("supportsEvaluateForHovers", true);
   // Available filters or options for the setExceptionBreakpoints request.
   llvm::json::Array filters;
   for (const auto &exc_bp : g_vsc.exception_breakpoints) {
     filters.emplace_back(CreateExceptionBreakpointFilter(exc_bp));
   }
   body.try_emplace("exceptionBreakpointFilters", std::move(filters));
+  // The debug adapter supports launching a debugee in intergrated VSCode
+  // terminal.
+  body.try_emplace("supportsRunInTerminalRequest", true);
   // The debug adapter supports stepping back via the stepBack and
   // reverseContinue requests.
   body.try_emplace("supportsStepBack", false);
   // The debug adapter supports setting a variable to a value.
   body.try_emplace("supportsSetVariable", true);
   // The debug adapter supports restarting a frame.
   body.try_emplace("supportsRestartFrame", false);
   // The debug adapter supports the gotoTargetsRequest.
void request_initialize(const llvm::json::Object &request) {
   body.try_emplace("supportsDelayedStackTraceLoading", true);
   // The debug adapter supports the 'loadedSources' request.
   body.try_emplace("supportsLoadedSourcesRequest", false);
 
   response.try_emplace("body", std::move(body));
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));
 }
 
+void request_runInTerminal(const llvm::json::Object &launch_request,
+                           llvm::json::Object &launch_response) {
+  // We have already created a target that has a valid "program" path to the
+  // executable. We will attach to the next process whose name matches that
+  // of the target's.
+  g_vsc.is_attach = true;
+  lldb::SBAttachInfo attach_info;
+  lldb::SBError error;
+  attach_info.SetWaitForLaunch(true, /*async*/ true);
+  g_vsc.target.Attach(attach_info, error);
+
+  llvm::json::Object reverse_request =
+      CreateRunInTerminalReverseRequest(launch_request);
+  llvm::json::Object reverse_response;
+  lldb_vscode::PacketStatus status =
+      g_vsc.SendReverseRequest(reverse_request, reverse_response);
+  if (status != lldb_vscode::PacketStatus::Success)
+    error.SetErrorString("Process cannot be launched by IDE.");
+
+  if (error.Success()) {
+    // Wait for the attach stop event to happen or for a timeout.
+    g_vsc.waiting_for_run_in_terminal = true;
+    static std::mutex mutex;
+    std::unique_lock<std::mutex> locker(mutex);
+    g_vsc.request_in_terminal_cv.wait_for(locker, std::chrono::seconds(10));
+
+    auto attached_pid = g_vsc.target.GetProcess().GetProcessID();
+    if (attached_pid == LLDB_INVALID_PROCESS_ID)
+      error.SetErrorString("Failed to attach to a process");
+    else
+      SendProcessEvent(Attach);
+  }
+
+  if (error.Fail()) {
+    launch_response["success"] = llvm::json::Value(false);
+    EmplaceSafeString(launch_response, "message",
+                      std::string(error.GetCString()));
+  } else {
+    launch_response["success"] = llvm::json::Value(true);
+    g_vsc.SendJSON(CreateEventObject("initialized"));
+  }
+}
+
 // "LaunchRequest": {
 //   "allOf": [ { "$ref": "#/definitions/Request" }, {
 //     "type": "object",
 //     "description": "Launch request; value of command field is 'launch'.",
 //     "properties": {
 //       "command": {
 //         "type": "string",
 //         "enum": [ "launch" ]
 //       },
 //       "arguments": {
 //         "$ref": "#/definitions/LaunchRequestArguments"
 //       }
 //     },
 //     "required": [ "command", "arguments"  ]
 //   }]
 // },
 // "LaunchRequestArguments": {
 //   "type": "object",
 //   "description": "Arguments for 'launch' request.",
 //   "properties": {
 //     "noDebug": {
 //       "type": "boolean",
 //       "description": "If noDebug is true the launch request should launch
 //                       the program without enabling debugging."
 //     }
 //   }
 // },
 // "LaunchResponse": {
 //   "allOf": [ { "$ref": "#/definitions/Response" }, {
 //     "type": "object",
 //     "description": "Response to 'launch' request. This is just an
 //                     acknowledgement, so no body field is required."
 //   }]
void request_launch(const llvm::json::Object &request) {
   g_vsc.SetTarget(g_vsc.CreateTargetFromArguments(*arguments, status));
   if (status.Fail()) {
     response["success"] = llvm::json::Value(false);
     EmplaceSafeString(response, "message", status.GetCString());
     g_vsc.SendJSON(llvm::json::Value(std::move(response)));
     return;
   }
 
+  if (GetBoolean(arguments, "runInTerminal", false)) {
+    request_runInTerminal(request, response);
+    g_vsc.SendJSON(llvm::json::Value(std::move(response)));
+    return;
+  }
+
   // Instantiate a launch info instance for the target.
   auto launch_info = g_vsc.target.GetLaunchInfo();
 
   // Grab the current working directory if there is one and set it in the
   // launch info.
   const auto cwd = GetString(arguments, "cwd");
   if (!cwd.empty())
     launch_info.SetWorkingDirectory(cwd.data());
void request_launch(const llvm::json::Object &request) {
 
   // Run any pre run LLDB commands the user specified in the launch.json
   g_vsc.RunPreRunCommands();
   if (launchCommands.empty()) {
     // Disable async events so the launch will be successful when we return from
     // the launch call and the launch will happen synchronously
     g_vsc.debugger.SetAsync(false);
     g_vsc.target.Launch(launch_info, error);
     g_vsc.debugger.SetAsync(true);
   } else {
     g_vsc.RunLLDBCommands("Running launchCommands:", launchCommands);
     // The custom commands might have created a new target so we should use the
     // selected target after these commands are run.
     g_vsc.target = g_vsc.debugger.GetSelectedTarget();
   }
 
   if (error.Fail()) {
     response["success"] = llvm::json::Value(false);
     EmplaceSafeString(response, "message", std::string(error.GetCString()));
   }
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));
 
   SendProcessEvent(Launch);
   g_vsc.SendJSON(llvm::json::Value(CreateEventObject("initialized")));
   // Reenable async events and start the event thread to catch async events.
   // g_vsc.debugger.SetAsync(true);
 }
 
 // "NextRequest": {
 //   "allOf": [ { "$ref": "#/definitions/Request" }, {
 //     "type": "object",
 //     "description": "Next request; value of command field is 'next'. The
 //                     request starts the debuggee to run again for one step.
 //                     The debug adapter first sends the NextResponse and then
 //                     a StoppedEvent (event type 'step') after the step has
 //                     completed.",
 //     "properties": {
for (uint32_t i = 0; g_vsc.target.GetBreakpointAtIndex(i).IsValid(); ++i) {
     AppendBreakpoint(bp, response_breakpoints);
   }
   llvm::json::Object body;
   body.try_emplace("breakpoints", std::move(response_breakpoints));
   response.try_emplace("body", std::move(body));
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));
 }
 
-const std::map<std::string, RequestCallback> &GetRequestHandlers() {
-#define REQUEST_CALLBACK(name)                                                 \
-  { #name, request_##name }
-  static std::map<std::string, RequestCallback> g_request_handlers = {
-      // VSCode Debug Adaptor requests
-      REQUEST_CALLBACK(attach),
-      REQUEST_CALLBACK(completions),
-      REQUEST_CALLBACK(continue),
-      REQUEST_CALLBACK(configurationDone),
-      REQUEST_CALLBACK(disconnect),
-      REQUEST_CALLBACK(evaluate),
-      REQUEST_CALLBACK(exceptionInfo),
-      REQUEST_CALLBACK(getCompileUnits),
-      REQUEST_CALLBACK(initialize),
-      REQUEST_CALLBACK(launch),
-      REQUEST_CALLBACK(next),
-      REQUEST_CALLBACK(pause),
-      REQUEST_CALLBACK(scopes),
-      REQUEST_CALLBACK(setBreakpoints),
-      REQUEST_CALLBACK(setExceptionBreakpoints),
-      REQUEST_CALLBACK(setFunctionBreakpoints),
-      REQUEST_CALLBACK(setVariable),
-      REQUEST_CALLBACK(source),
-      REQUEST_CALLBACK(stackTrace),
-      REQUEST_CALLBACK(stepIn),
-      REQUEST_CALLBACK(stepOut),
-      REQUEST_CALLBACK(threads),
-      REQUEST_CALLBACK(variables),
-      // Testing requests
-      REQUEST_CALLBACK(_testGetTargetBreakpoints),
-  };
-#undef REQUEST_CALLBACK
-  return g_request_handlers;
+void RegisterRequestCallbacks() {
+  g_vsc.RegisterRequestCallback("attach", request_attach);
+  g_vsc.RegisterRequestCallback("completions", request_completions);
+  g_vsc.RegisterRequestCallback("continue", request_continue);
+  g_vsc.RegisterRequestCallback("configurationDone", request_configurationDone);
+  g_vsc.RegisterRequestCallback("disconnect", request_disconnect);
+  g_vsc.RegisterRequestCallback("evaluate", request_evaluate);
+  g_vsc.RegisterRequestCallback("exceptionInfo", request_exceptionInfo);
+  g_vsc.RegisterRequestCallback("getCompileUnits", request_getCompileUnits);
+  g_vsc.RegisterRequestCallback("initialize", request_initialize);
+  g_vsc.RegisterRequestCallback("launch", request_launch);
+  g_vsc.RegisterRequestCallback("next", request_next);
+  g_vsc.RegisterRequestCallback("pause", request_pause);
+  g_vsc.RegisterRequestCallback("scopes", request_scopes);
+  g_vsc.RegisterRequestCallback("setBreakpoints", request_setBreakpoints);
+  g_vsc.RegisterRequestCallback("setExceptionBreakpoints",
+                                request_setExceptionBreakpoints);
+  g_vsc.RegisterRequestCallback("setFunctionBreakpoints",
+                                request_setFunctionBreakpoints);
+  g_vsc.RegisterRequestCallback("setVariable", request_setVariable);
+  g_vsc.RegisterRequestCallback("source", request_source);
+  g_vsc.RegisterRequestCallback("stackTrace", request_stackTrace);
+  g_vsc.RegisterRequestCallback("stepIn", request_stepIn);
+  g_vsc.RegisterRequestCallback("stepOut", request_stepOut);
+  g_vsc.RegisterRequestCallback("threads", request_threads);
+  g_vsc.RegisterRequestCallback("variables", request_variables);
+  g_vsc.RegisterRequestCallback("_testGetTargetBreakpoints",
+                                request__testGetTargetBreakpoints);
 }
 
 } // anonymous namespace
 
 static void printHelp(LLDBVSCodeOptTable &table, llvm::StringRef tool_name) {
   std::string usage_str = tool_name.str() + "options";
   table.PrintHelp(llvm::outs(), usage_str.c_str(), "LLDB VSCode", false);
 
EXAMPLES:
   llvm::outs() << examples;
 }
 
 int main(int argc, char *argv[]) {
 
   // Initialize LLDB first before we do anything.
   lldb::SBDebugger::Initialize();
 
+  RegisterRequestCallbacks();
+
   int portno = -1;
 
   LLDBVSCodeOptTable T;
   unsigned MAI, MAC;
   llvm::ArrayRef<const char *> ArgsArr = llvm::makeArrayRef(argv + 1, argc);
   llvm::opt::InputArgList input_args = T.ParseArgs(ArgsArr, MAI, MAC);
 
   if (input_args.hasArg(OPT_help)) {
if (portno != -1) {
     } else {
       exit(1);
     }
   } else {
     g_vsc.input.descriptor = StreamDescriptor::from_file(fileno(stdin), false);
     g_vsc.output.descriptor =
         StreamDescriptor::from_file(fileno(stdout), false);
   }
-  auto request_handlers = GetRequestHandlers();
   uint32_t packet_idx = 0;
   while (!g_vsc.sent_terminated_event) {
-    std::string json = g_vsc.ReadJSON();
-    if (json.empty())
+    llvm::json::Object object;
+    lldb_vscode::PacketStatus status = g_vsc.GetObject(object);
+    if (status == lldb_vscode::PacketStatus::EndOfFile)
       break;
+    if (status != lldb_vscode::PacketStatus::Success)
+      return 1; // Fatal error
 
-    llvm::StringRef json_sref(json);
-    llvm::Expected<llvm::json::Value> json_value = llvm::json::parse(json_sref);
-    if (!json_value) {
-      auto error = json_value.takeError();
-      if (g_vsc.log) {
-        std::string error_str;
-        llvm::raw_string_ostream strm(error_str);
-        strm << error;
-        strm.flush();
-
-        *g_vsc.log << "error: failed to parse JSON: " << error_str << std::endl
-                   << json << std::endl;
-      }
+    if (!g_vsc.HandleObject(object))
       return 1;
-    }
-
-    auto object = json_value->getAsObject();
-    if (!object) {
-      if (g_vsc.log)
-        *g_vsc.log << "error: json packet isn't a object" << std::endl;
-      return 1;
-    }
-
-    const auto packet_type = GetString(object, "type");
-    if (packet_type == "request") {
-      const auto command = GetString(object, "command");
-      auto handler_pos = request_handlers.find(std::string(command));
-      if (handler_pos != request_handlers.end()) {
-        handler_pos->second(*object);
-      } else {
-        if (g_vsc.log)
-          *g_vsc.log << "error: unhandled command \"" << command.data()
-                     << std::endl;
-        return 1;
-      }
-    }
     ++packet_idx;
   }
 
   // We must terminate the debugger in a thread before the C++ destructor
   // chain messes everything up.
   lldb::SBDebugger::Terminate();
   return 0;
 }

lldb/tools/lldb-vscode/package.json

"debuggers": [
                 "type": "array",
                 "description": "Commands executed each time the program stops.",
                 "default": []
               },
               "exitCommands": {
                 "type": "array",
                 "description": "Commands executed at the end of debugging session.",
                 "default": []
+              },
+              "runInTerminal": {
+                "type": "boolean",
+                "description": "Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs",
+                "default": false
               }
             }
           },
           "attach": {
             "properties": {
               "program": {
                 "type": "string",
                 "description": "Path to the program to attach to."