xdebug is a lightweight TCP text-command debug service for native C++ programs.

It is designed for embedded and media-service debugging: link libxdebug.so, register module commands in the module owner's constructor, start one process-wide debug server, and inspect or change runtime state with tools such as nc or telnet.

• Process-wide singleton server: xdebug::DebugServer::instance()
• Module lifecycle owned by module owners, not by the server
• RAII-friendly module registration and unregistration
• Plain line-based TCP command protocol
• Default listener: xdebug::kDefaultHost:xdebug::kDefaultPort (0.0.0.0:59695)
• Multi-interface support: loopback, Ethernet, Wi-Fi, and other reachable IPv4 interfaces
• CMake builds:
  • libxdebug.so
  • xdebug_demo

cmake -S . -B build
cmake --build build

Outputs:

build/xdebug/libxdebug.so
build/demo/xdebug_demo

./build/demo/xdebug_demo

The demo binds <xdebug::kDefaultHost>:<xdebug::kDefaultPort> by default (0.0.0.0:59695), so it accepts connections through any local IPv4 interface.

Local loopback:

nc 127.0.0.1 59695

Ethernet or Wi-Fi:

nc 10.48.11.15 59695
nc 192.168.1.104 59695

nc is the preferred client because it sends raw TCP bytes. It is predictable for line-based debug protocols:

nc 127.0.0.1 59695

telnet can also be useful when nc is not available:

telnet 127.0.0.1 59695

However, telnet is not just a raw TCP client. Some implementations send telnet option negotiation bytes. xdebug uses a simple text protocol, so nc is cleaner for automated tests and scripts. Use telnet mainly for manual checks on constrained systems where telnet is already installed.

help
modules
ping
server status
player show
player play
player stop
player set-volume 80
encoder show
encoder set-fps 30
encoder request-idr
quit

class EncoderModule final : public xdebug::DebugModule {
public:
    EncoderModule() {
        xdebug::DebugServer::instance().registerModule(this);
    }

    ~EncoderModule() override {
        xdebug::DebugServer::instance().unregisterModule(this);
    }

    std::string name() const override { return "encoder"; }
    std::string help() const override { return "encoder show"; }

    xdebug::CommandResult handle(const xdebug::CommandRequest& request) override {
        return xdebug::CommandResult::ok("encoder state");
    }
};

The server stores non-owning module pointers. The module owner must ensure the module outlives its registration.

• Technical design
• Usage
• Architecture PlantUML
• Class PlantUML
• Command sequence PlantUML

GNU Lesser General Public License v2.1 or later. See LICENSE.