dbgp

README

dbgp protocol for go (debugger engine side)


status: alpha/beta/patches-please
license: isc


interesting sub-project: gdb->dbgp proxy

quick-start:
$ go get github.com/tmc/dbgp/gdbproxy/cmd/gdb2dbgp # (I know)
$ gdb2dbgp ./binary-debuggable-with-gdb # this will attempt to connect to your IDE on port 9000 (see -h for options)

hacking:

invoke with logging:
$ gdb2dbgp -v=2 -logtostderr

Documentation

Overview

Package dbgp implements the dbgp client protocol

see https://github.com/derickr/dbgp/blob/master/debugger_protocol.rst

status: pre-alpha

Index

• Variables
• type Breakpoint
• type Conn
  • func NewConn(conn io.ReadWriter, client DBGPClient) *Conn
  • func (c *Conn) Run() error
• type Context
• type DBGPClient
• type Features
• type InitResponse
• type Property
• type Stack

Variables

var (
	// ErrParseError means an error occurred while parsing
	ErrParseError = dbgpError{1, "Parse Error"}
	// ErrInvalidOpts means invalid options were supplied
	ErrInvalidOpts = dbgpError{3, "Invaild Options"}
	// ErrUnimplemented means the attempted action is not implemented
	ErrUnimplemented = dbgpError{4, "Unimplemented"}
)

Types

type Breakpoint

type Breakpoint struct {
	ID int `xml:"breakpoint_id,attr"`
	// Either "enabled" or "disabled"
	State string `xml:"state,attr"`
}

Breakpoint is a breakpoint in code

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a upstream connection to a DBGP-capable IDE or proxy

func NewConn

func NewConn(conn io.ReadWriter, client DBGPClient) *Conn

NewConn creates a new DBGP client connection with an rw for the communication and a DBGPClient

func (*Conn) Run

func (c *Conn) Run() error

Run start the upstream communication and invokes teh client

type Context

type Context struct {
	Name string `xml:"name,attr"`
	ID   int    `xml:"id,attr"`
}

type DBGPClient

type DBGPClient interface {
	// Init is called when starting communication with upstream
	Init() InitResponse
	// Return status, one of ("starting", "stopping", "running", "break")
	Status() string
	// Return supported features (called after Init())
	Features() Features
	// Step the debugger into the program. State being one of ("starting", "stopping", "running", "break"), and reason one of ("ok, "error", "aborted", "exception")
	StepInto() (status string, reason string)
	// Step over the program. State being one of ("starting", "stopping", "running", "break"), and reason one of ("ok, "error", "aborted", "exception")
	StepOver() (status string, reason string)
	// Return the maximum stack depth
	StackDepth() int
	// Return one or more Stack elements based on the requested depth
	StackGet(depth int) ([]Stack, error)
	// Return the relevant Contexts
	ContextNames(depth int) ([]Context, error)
	// Return the properties associated with the specified stack depth and context
	ContextGet(depth, context int) ([]Property, error)
	// Return the value for a property
	PropertyGet(depth, context int, name string) (string, error)
	// Set a breakpoint
	BreakpointSet(bpType, fileName string, line int) (Breakpoint, error)
}

The DBGPClient interface captures what a client implementation must provide

type Features

type Features struct {
	Supports_async bool
	Language_name  string
}

Features describes the supported features of the debugger enging

type InitResponse

type InitResponse struct {
	AppID    string `xml:"appid,attr"`
	IDeKey   string `xml:"idekey,attr"`
	Session  string `xml:"session,attr"`
	Thread   string `xml:"thread,attr"`
	Parent   string `xml:"parent,attr"`
	Language string `xml:"language,attr"`
	FileURI  string `xml:"fileuri,attr"`
}

type Property

type Property struct {
	Name      string `xml:"name,attr"`      // Short variable name.
	Fullname  string `xml:"fullname,attr"`  // Long variable name. This is the long form of the name which can be eval'd by the language to retrieve the value of the variable.
	Classname string `xml:"classname,attr"` // If the type is an object or resource, then the debugger engine MAY specify the class name This is an optional attribute.
	Type      string `xml:"type,attr"`      // language specific data type name

	Address string `xml:"address,attr"` // containing physical memory address, optional
	// contains filtered or unexported fields
}

type Stack

type Stack struct {
	Level    int    `xml:"level,attr"`    // the stack depth of this stack element
	Type     string `xml:"type,attr"`     // the type of stack frame. Valid values are "file" or "eval"
	Filename string `xml:"filename,attr"` // absolute file URI in the local filesystem
	Lineno   int    `xml:"lineno,attr"`   // 1-based line offset into the buffer
	Where    string `xml:"where,attr"`    // current command name (optional)
	// contains filtered or unexported fields
}