cppdap: C++ Implementation of the Debug Adapter Protocol

To build cppdap on Linux or macOS, use CMake to generate build files and then use make.

1. Create a build directory and run CMake:

   mkdir build
   cd build
   cmake .. [FLAGS]

2. Build the project:

   make

Available CMake flags:

• -DCPPDAP_BUILD_TESTS=1: Builds the cppdap unit tests.
• -DCPPDAP_BUILD_EXAMPLES=1: Builds the cppdap examples.
• -DCPPDAP_INSTALL_VSCODE_EXAMPLES=1: Installs examples as Visual Studio Code extensions.
• -DCPPDAP_WARNINGS_AS_ERRORS=1: Treats all compiler warnings as errors.

cd <path-to-cppdap>
mkdir build
cd build
cmake .. -DCPPDAP_BUILD_TESTS=1
make

cppdap uses git submodules for its primary dependencies: nlohmann/json and googletest. You must initialize these submodules before building.

To fetch the dependencies, run:

cd <path-to-cppdap>
git submodule update --init

While cppdap defaults to nlohmann/json, you can use alternative JSON serialization libraries by setting the following CMake cache variables:

• CPPDAP_USE_EXTERNAL_NLOHMANN_JSON_PACKAGE
• CPPDAP_USE_EXTERNAL_RAPIDJSON_PACKAGE (for RapidJSON)
• CPPDAP_USE_EXTERNAL_JSONCPP_PACKAGE (for JsonCpp)

After creating a session, you must bind it to communication channels using connect(). This method requires a std::shared_ptr<dap::Reader> and a std::shared_ptr<dap::Writer>. Once connected, the session can begin receiving and sending DAP messages.

session->connect(reader, writer);

To send a command to the debug adapter, use the send overload that accepts TypeInfo for both the request and the expected response. This method automatically manages sequence numbers and registers a GenericResponseHandler to catch the eventual response.

Arguments:

• requestTypeInfo: The dap::TypeInfo describing the request structure.
• responseTypeInfo: The dap::TypeInfo describing the expected response structure.
• request: A pointer to the data object to be serialized.
• responseHandler: A callback invoked when the response arrives.

session->send(requestTypeInfo, responseTypeInfo, requestData, [](const void* data, const dap::Error* error) {
    if (error) {
        // Handle error
    } else {
        // Handle successful response data
    }
});

The ContentWriter class provides an interface for writing data to a dap::Writer. It is initialized with a std::shared_ptr<Writer>.

Key methods:

• isOpen(): Returns true if the writer is currently open.
• close(): Closes the writer.
• write(const std::string&): Writes the provided string to the underlying writer. Returns true if successful.

#include "dap/content_stream.h"
#include "dap/session.h"

// Assuming writer_ptr is a valid std::shared_ptr<dap::Writer>
dap::ContentWriter content_writer(writer_ptr);

if (content_writer.isOpen()) {
    bool success = content_writer.write("your content here");
    content_writer.close();
}

To broadcast an event, use the send overload that accepts TypeInfo and an event object. This method automatically assigns a sequence number and serializes the event body.

Arguments:

• typeinfo: The dap::TypeInfo describing the event.
• event: A pointer to the data object to be serialized as the event body.

session->send(eventTypeInfo, eventData);

To begin the asynchronous processing of incoming messages, call startProcessingMessages(). This method spawns internal threads to:

1. Read messages from the connected reader.
2. Dispatch payloads (requests, events, or responses) to their registered handlers.

You can optionally provide a ClosedHandler callback that will be executed when the reader is closed and the processing loop terminates.

session->startProcessingMessages([]() {
  // Handle session closure
});