Proposal: Add Native Debug Adapter Protocol (DAP) Support to Harbour Debugger

[naldodj]

Proposal: Add Native Debug Adapter Protocol (DAP) Support to Harbour Debugger

Summary

This Issue proposes adding a transport-agnostic interface to the Harbour debugger to enable native Debug Adapter Protocol (DAP) support.
With this enhancement, Harbour applications could be debugged directly from modern editors such as VSCode, JetBrains IDEs, Eclipse, or any other DAP-compatible tool — without replacing the existing terminal debugger.

The approach is backwards-compatible, opt-in, and requires only minimal extensions to the current debugger architecture.

---

Problem

Harbour includes a mature and powerful debugger (debugger.prg), but today it is only accessible through terminal interfaces. As a result:

• There is no native way to debug Harbour code from modern IDEs.
• Developers cannot attach to remote processes running on servers, containers, or embedded devices.
• New developers often perceive Harbour as lacking modern tooling support.

Implementing DAP enables Harbour to integrate with any standard debugging client while preserving and reusing the existing debugger engine.

---

Motivation

Adding DAP support would bring several benefits:

1. Modern Development Workflow
   Debugging directly inside VSCode or JetBrains lowers the entry barrier for new developers.

2. Remote Debugging
   Enables attaching to Harbour applications over TCP/WebSocket.

3. Reuse of Existing Debugger Engine
   No need to create a new debugger — only to expose existing capabilities through transports.

4. Cross-Platform
   Works on Windows, Linux and macOS.

5. Ecosystem Compatibility
   Any DAP-compliant editor becomes a Harbour-capable debugger.

---

Proposed Architectural Approach (High-Level)

This proposal follows a minimal and additive strategy:

1. Add New Debugger Activation Modes

Example:

• HB_DBG_ACTIVATE_STDIO
• HB_DBG_ACTIVATE_DAP

These modes would activate the debugger in “remote/transported” mode rather than terminal mode.

2. Create Transport-Agnostic Hooks

Introduce small send/receive abstractions inside the debugger so communication can be routed through:

• STDIO
• TCP sockets
• WebSockets
• Any custom transport

This requires only lightweight additions (e.g., setting function pointers or callbacks).

3. Add a Basic DAP Command Handler

At this stage, only essential commands are required:

• initialize
• launch / attach
• setBreakpoints
• continue / next / stepIn
• stackTrace
• scopes / variables
• evaluate

This can be expanded incrementally.

4. Keep Terminal Debugger Fully Intact

Existing behaviour remains unchanged unless a DAP/STDIO mode is explicitly activated.

---

Implementation Plan (Phased)

Phase 1 — STDIO Transport

• JSON-over-stdio communication
• Minimal command set
• Allows local debugging from any DAP client

Phase 2 — Full DAP Support

• Complete DAP request/response/event coverage
• Editor extension for VSCode (optional)

Phase 3 — Remote Transports

• TCP server for remote debugging
• WebSocket transport for browser-based tools
• Attach support

---

Backward Compatibility

This proposal is 100% additive:

• The default debugger continues operating exactly as it does today.
• No behavioural changes occur unless the new modes are explicitly requested.
• The terminal UI remains untouched.

---

Example of Expected Usage (Conceptual)

Local (STDIO) Debugging

harbour app.prg -debug=stdio

DAP Server

harbour app.prg -debug=dap:port=4712

VSCode Launch Configuration

{
  "type": "harbour",
  "request": "launch",
  "name": "Debug Harbour",
  "program": "${workspaceFolder}/app.prg",
  "transport": "stdio"
}

---

Prototype Availability

A working prototype demonstrating the feasibility of this architecture exists.
I am willing to contribute a full implementation and help maintain the feature if this proposal is accepted.

---

Request for Feedback

I would appreciate input from the maintainers and community on:

1. Whether this direction aligns with Harbour’s architecture
2. Any concerns regarding integration into debugger.prg
3. Suggestions for transport API design
4. Interest in accepting a PR for this feature

---

[FiveTechSoft]

Dear Naldo,

This proposal is excellent and strategically vital for Harbour's future. It effectively bridges the gap between a classic language and modern tooling.

Here is the summary of my technical opinion:

• Perfect Architecture: The "transport-agnostic" and "opt-in" approach is the correct strategy. It decouples the debugging logic from the UI, allowing the legacy terminal debugger to coexist seamlessly with modern interfaces.
• Ecosystem Integration: By adopting the standard DAP (Debug Adapter Protocol), Harbour instantly gains support for VSCode, JetBrains, and other modern editors without needing to build custom plugins for each.
• Game-Changer for Web/Cloud: The ability to attach via TCP/Sockets enables remote debugging. This is critical for mod_harbour and Linux backend development, allowing developers to debug server-side code from their local machines.
• Technical Feasibility: The implementation is highly viable using Harbour's native JSON and Socket support. The main challenges will be optimizing object serialization (to avoid performance hits) and managing the non-blocking event loop.

In short: This transforms Harbour from a "legacy" tool into a modern development platform. If you have a prototype, it represents a massive leap forward in Developer Experience (DX).

[naldodj]

TL;DR: Proposal for transport-agnostic debugger enabling VSCode/DAP support via minimal, additive changes that preserve existing terminal debugger. Seeking architectural feedback before any implementation.

Thank you very much for the detailed feedback — I’m really glad to hear that the proposal aligns with Harbour’s long-term direction. Below I’ll clarify some points and add a few conceptual examples showing why the architecture can fit naturally into the existing debugger.

Transport Abstraction (Conceptual Proposal)

The main idea is to keep the debugger transport-agnostic, allowing different communication layers (STDIO, TCP, WebSockets, etc.) without altering the debugger’s internal logic.

Conceptually, this could be achieved with lightweight callbacks such as:

hDebugger:bSend    := {|c| /* send through selected transport */ }
hDebugger:bReceive := {||   /* receive from selected transport */ }

This preserves the terminal debugger exactly as it works today — nothing changes unless a transport-based mode is explicitly activated.

---

New Activation Modes (Conceptual Example)

As an illustration, two new activation constants could be introduced:

#define HB_DBG_ACTIVATE_DAP      10
#define HB_DBG_ACTIVATE_STDIO    11

Their purpose would be simply to enable a “transported/remote” mode without interfering with the traditional UI.

Example of how it could conceptually look:

CASE HB_DBG_ACTIVATE_DAP
CASE HB_DBG_ACTIVATE_STDIO
   t_oDebugger := HBDebugger():New( .T. ) // remote mode enabled
   t_oDebugger:cTransportType := "dap"
   t_oDebugger:Activate()
   RETURN

These samples are illustrative only, to show how small and additive the change could be.

---

Minimal DAP Handler (Conceptual Skeleton)

To validate feasibility, I drafted a very small conceptual skeleton illustrating how DAP requests could be handled:

METHOD ProcessDAPCommand( hCmd ) CLASS HBDebugger
   LOCAL cCommand := hb_HGetDef( hCmd, "command", "" )

   DO CASE
   CASE cCommand == "initialize"
      ::SendDAPResponse( hCmd["seq"], { "supportsStepBack" => .F. } )

   CASE cCommand == "setBreakpoints"
      ::HandleSetBreakpoints( hCmd )

   CASE cCommand == "stackTrace"
      ::SendDAPResponse( hCmd["seq"], { ;
         "stackFrames" => ::BuildStackFrames( 1 ) ;
      } )

   CASE cCommand == "evaluate"
      ::SendDAPResponse( hCmd["seq"], ::EvaluateExpression( hCmd["expression"], 0 ) )
   ENDCASE
RETURN

Again — not functional code, just a demonstration that the structure maps well to DAP semantics.

---

Possible Phased Implementation (Suggestion Only)

To keep the feature incremental and review-friendly, the idea could evolve in phases:

Phase 1 — STDIO Transport

• Basic JSON-over-STDIO
• Minimal DAP subset

Phase 2 — Full DAP

• Support for all DAP requests/responses
• Capability reporting
• Editor integrations as optional add-ons

Phase 3 — Remote Debugging

• TCP transport
• WebSocket support
• Attach semantics

These are suggested pathways, nothing enforced.

---

Next Steps

At this point, everything I have is conceptual and experimental, intended only to demonstrate feasibility.
I am not preparing a PR; the goal is to provide architectural insight and start a discussion.

I would appreciate feedback from the maintainers about:

• whether this direction fits Harbour’s long-term goals
• whether transport abstraction is something the project is open to
• preferred patterns for extending the debugger’s architecture
• any potential conflicts in debugger.prg

With that guidance, the community (including myself if needed) could later explore ways to contribute, test, or refine the design — but the core implementation would naturally stay in the hands of the Harbour team.

Thanks again for the encouraging response — I’m happy to help refine the proposal however needed.

[lailton]

This is an interesting approach.

A good reference to study and implement it is the excellent debugger created by
Antonino Perricone ( @APerricone )
https://github.com/APerricone/harbourCodeExtension

It is very useful and a good example of how to implement what is being proposed.

[alcz]

Hard to be against this one, Harbour should have GUI debugger too. Considering there is hardly a GUI in the core, a common protocol is an option.

• it should be replacable and extensible, Antonio Perricone debugger, Alexander Kresin's debuggers proof it is already replaceable?
• it's not HBDebugger class that should be extended - subclass, comparible class? otherwise hb_gtCreate() style API for compiling-in, REQUEST DBGDAP, hDbg := hb_dbgCreate("DAP"), hb_dbgSelect() for multiple backends?
• (transport) as it is in Alexander Kresin HwGUI debugger should be considered too as a alternative to sockets
• bring the code in, the more .prg based it is, the more gives it a chance for inclusion, less C cleanups needed

Must insert a rant here too, because there are many proposals now being formatted by AI agents apparently. It creates sort of imbalance in time spent, creating them vs accomodating them (me or others devs interested). While they look as extensive specifications, many times they are not precise. It's not five-second read to keep up if the details are realistic. If they would be, why not make your agent do the actual implementation?

[FiveTechSoft]

Dear naldodj,

Will it support MT ? Thank you

[APerricone]

Dear naldodj,

Will it support MT ? Thank you

Please don't rub on it 🙂never had time for multi htread support, now I am out from harbour