gidebug

package
v1.0.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 2, 2022 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	NotStartedErr = errors.New("debugger not started")

	IsRunningErr = errors.New("debugger is currently running and cannot return info")
)
View Source 
var DefaultParams = Params{
	VarList: VarParams{
		FollowPointers:  false,
		MaxRecurse:      4,
		MaxStringLen:    100,
		MaxArrayValues:  10,
		MaxStructFields: -1,
	},
	GetVar: VarParams{
		FollowPointers:  false,
		MaxRecurse:      10,
		MaxStringLen:    1024,
		MaxArrayValues:  1024,
		MaxStructFields: -1,
	},
}

DefaultParams are default parameter values

View Source 
var KiT_Status = kit.Enums.AddEnum(StatusN, kit.NotBitFlag, nil)
View Source 
var KiT_Variable = kit.Types.AddType(&Variable{}, nil)
View Source 
var VariableProps = ki.Props{
	"EnumType:Flag": gi.KiT_NodeFlags,
	"StructViewFields": ki.Props{
		"UniqueNm": `view:"-"`,
		"Flag":     `view:"-"`,
		"Kids":     `view:"-"`,
		"Props":    `view:"-"`,
	},
	"ToolBar": ki.PropSlice{
		{"FollowPtr", ki.Props{
			"desc": "retrieve the contents of this pointer -- child nodes will contain further data",
			"icon": "update",
			"updtfunc": func(vri interface{}, act *gi.Action) {
				vr := vri.(ki.Ki).Embed(KiT_Variable).(*Variable)
				act.SetActiveState(!vr.HasChildren())
			},
		}},
	},
}

Functions

func SortBreaks 

func SortBreaks(brk []*Break)

SortBreaks sorts breaks by id

func SortVars 

func SortVars(vrs []*Variable)

SortVars sorts vars by name

Types

type AllState 

type AllState struct {
	Mode       Modes       `desc:"mode we're running in"`
	Status     Status      `desc:"overall debugger status"`
	State      State       `desc:"current run state"`
	CurThread  int         `desc:"id of the current system thread to examine"`
	CurTask    int         `desc:"id of the current task to examine"`
	CurFrame   int         `desc:"frame number within current thread"`
	CurBreak   int         `desc:"current breakpoint that we stopped at -- will be 0 if none, after UpdateState"`
	Breaks     []*Break    `desc:"all breakpoints that have been set -- some may not be On"`
	CurBreaks  []*Break    `desc:"current, active breakpoints as retrieved from debugger"`
	Threads    []*Thread   `desc:"all system threads"`
	Tasks      []*Task     `desc:"all tasks"`
	Stack      []*Frame    `desc:"current stack frame for current thread / task"`
	Vars       []*Variable `desc:"current local variables and args for current frame"`
	GlobalVars []*Variable `desc:"global variables for current thread / task"`
	FindFrames []*Frame    `desc:"current find-frames result"`
}

AllState holds all relevant state information. This can be maintained and updated in the debug view.

func (*AllState) AddBreak 

func (as *AllState) AddBreak(fpath string, line int) *Break

AddBreak adds file path and line to full list of breaks. checks for an existing and turns it on if so.

func (*AllState) BlankState 

func (as *AllState) BlankState()

BlankState initializes state with a blank initial state with the various slices having a single entry -- for GUI initialization.

func (*AllState) BreakByFile 

func (as *AllState) BreakByFile(fpath string, line int) (*Break, int)

BreakByFile returns the given breakpoint by file path and line from list. returns nil, -1 if not found.

func (*AllState) BreakByID 

func (as *AllState) BreakByID(id int) (*Break, int)

BreakByID returns the given breakpoint by ID from full list, and index. returns nil, -1 if not found.

func (*AllState) DeleteBreakByFile 

func (as *AllState) DeleteBreakByFile(fpath string, line int) bool

DeleteBreakByFile deletes given break by File and Line from full list. Returns true if deleted.

func (*AllState) DeleteBreakByID 

func (as *AllState) DeleteBreakByID(id int) bool

DeleteBreakByID deletes given break by ID from full list. Returns true if deleted.

func (*AllState) MergeBreaks 

func (as *AllState) MergeBreaks()

MergeBreaks merges the current breaks with AllBreaks -- any not in Cur are indicated as !On

func (*AllState) StackFrame 

func (as *AllState) StackFrame(idx int) *Frame

StackFrame safely returns the given stack frame -- nil if out of range

func (*AllState) VarByName added in v0.9.14 

func (as *AllState) VarByName(varNm string) *Variable

VarByName returns variable with the given name, or nil if not found

type Break 

type Break struct {
	ID    int    `inactive:"+" desc:"unique numerical ID of the breakpoint"`
	On    bool   `width:"4" desc:"whether the breakpoint is currently enabled"`
	PC    uint64 `inactive:"+" format:"%#X" desc:"program counter (address) -- may be subset of multiple"`
	File  string `inactive:"+" desc:"file name (trimmed up to point of project base path)"`
	Line  int    `inactive:"+" desc:"line within file"`
	FPath string `inactive:"+" view:"-" tableview:"-" desc:"full path to file"`
	Func  string `inactive:"+" desc:"the name of the function"`
	Cond  string `desc:"condition for conditional breakbpoint"`
	Trace bool   `width:"7" desc:"if true, execution does not stop -- just a message is reported when this point is hit"`
}

Break describes one breakpoint

func BreakByFile 

func BreakByFile(bks []*Break, fpath string, line int) (*Break, int)

BreakByFile returns the given breakpoint by file path and line from list. returns nil, -1 if not found.

func BreakByID 

func BreakByID(bks []*Break, id int) (*Break, int)

BreakByID returns the given breakpoint by ID from full list, and index. returns nil, -1 if not found.

type Frame 

type Frame struct {
	Depth    int         `desc:"depth in overall stack -- 0 is the bottom (currently executing) frame, and it counts up from there"`
	ThreadID int         `desc:"the Task or Thread id that this frame belongs to"`
	PC       uint64      `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`
	File     string      `desc:"file name (trimmed up to point of project base path)"`
	Line     int         `desc:"line within file"`
	FPath    string      `tableview:"-" tableview:"-" desc:"full path to file"`
	Func     string      `desc:"the name of the function"`
	Vars     []*Variable `tableview:"-" desc:"values of the local variables at this frame"`
	Args     []*Variable `tableview:"-" desc:"values of the local function args at this frame"`
}

Frame describes one frame in a stack trace.

type GiDebug 

type GiDebug interface {

	// HasTasks returns true if the debugger supports a level of threading
	// below the system thread level.  If true, then use Task data
	// otherwise, use Threads
	HasTasks() bool

	// Start starts the debugger for a given exe path, and overall project
	// root path (for trimming file names), and sets output of debugger
	// session to given textbuf which is used to monitor output.
	// params must have relevant settings in place (StatFunc, Mode, etc).
	Start(path, rootPath string, outbuf *giv.TextBuf, pars *Params) error

	// SetParams sets the current parameters to control how info is returned
	SetParams(params *Params)

	// IsActive returns true if the debugger is active and ready for commands
	IsActive() bool

	// Returns the pid of the process we are debugging.
	ProcessPid() int

	// LastModified returns the time that the process' executable was modified.
	LastModified() time.Time

	// Detach detaches the debugger, optionally killing the process.
	Detach(killProcess bool) error

	// Disconnect closes the connection to the server without
	// sending a Detach request first.  If cont is true a continue
	// command will be sent instead.
	Disconnect(cont bool) error

	// Restarts program.
	Restart() error

	// GetState returns the current debugger state.
	// This will return immediately -- if the target is running then
	// the Running flag will be set and a Stop bus be called to
	// get any further information about the target.
	GetState() (*State, error)

	// Continue resumes process execution.  The channel will block until the
	// process stops by any means.  Tracepoints are automatically handled by
	// the debugger, and do not appear.  Typically there is just one State
	// in the channel, but perhaps there could be more -- use a range to iterate
	// over all items in the channel -- it will close after data is sent.
	// The last state can be used for further updating.
	Continue(all *AllState) <-chan *State

	// StepOver continues to the next source line, not entering function calls.
	StepOver() (*State, error)

	// StepInto continues to the next source line, entering function calls.
	StepInto() (*State, error)

	// StepOut continues to the return point of the current function
	StepOut() (*State, error)

	// StepSingle step a single cpu instruction.
	StepSingle() (*State, error)

	// SwitchThread switches the current system thread context to given one
	SwitchThread(threadID int) (*State, error)

	// SwitchTask switches the current thread to given one
	SwitchTask(threadID int) (*State, error)

	// Stop suspends the process.
	Stop() (*State, error)

	// GetBreak gets info about a breakpoint by ID.
	GetBreak(id int) (*Break, error)

	// SetBreak sets a new breakpoint at given file (must be enough to be unique)
	// and line number
	SetBreak(fname string, line int) (*Break, error)

	// ListBreaks gets all breakpoints.
	ListBreaks() ([]*Break, error)

	// ClearBreak deletes a breakpoint by ID.
	ClearBreak(id int) error

	// AmmendBreak updates the Condition and Trace information
	// for the given breakpoint
	AmendBreak(id int, fname string, line int, cond string, trace bool) error

	// UpdateBreaks updates current breakpoints based on given list of breakpoints.
	// first gets the current list, and does actions to ensure that the list is set.
	UpdateBreaks(brk *[]*Break) error

	// Cancels a Next or Step call that was interrupted by a
	// manual stop or by another breakpoint
	CancelNext() error

	// InitAllState initializes the given AllState with relevant info
	// for current debugger state.  Does NOT get AllVars.
	InitAllState(all *AllState) error

	// UpdateAllState updates the state for given threadId and
	// frame number (only info different from current results is updated).
	// For given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	UpdateAllState(all *AllState, threadID int, frame int) error

	// FindFrames looks through the Stacks of all Tasks / Threads
	// for the closest Stack Frame to given file and line number.
	// Results are sorted by line number proximity to given line.
	FindFrames(all *AllState, fname string, line int) ([]*Frame, error)

	// CurThreadID returns the proper current threadID (task or thread)
	// based on debugger, from given state.
	CurThreadID(all *AllState) int

	// ListThreads lists all system threads.
	ListThreads() ([]*Thread, error)

	// GetThread gets a thread by its ID.
	GetThread(id int) (*Thread, error)

	// ListTasks lists all the currently active threads (if supported)
	ListTasks() ([]*Task, error)

	// Stack returns the current stack, up to given depth,
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	Stack(threadID int, depth int) ([]*Frame, error)

	// ListGlobalVars lists global variables (subject to filter) in the context
	// of the current thread.
	ListGlobalVars(filter string) ([]*Variable, error)

	// ListVars lists all stack-frame local variables (including args)
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	ListVars(threadID int, frame int) ([]*Variable, error)

	// GetVar returns a variable for given thread (lowest-level supported by
	// language -- e.g., Task if supported, else Thread), and frame number,
	// from given expression, which depending on debugger can be a full
	// expression (e.g., path, address with cast, etc)
	GetVar(expr string, threadID int, frame int) (*Variable, error)

	// FollowPtr fills in the Child of given Variable
	// with retrieved value.  Uses last eval scope.
	FollowPtr(vr *Variable) error

	// SetVar sets the value of a variable.
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	SetVar(name, value string, threadID int, frame int) error

	// ListSources lists all source files in the process matching filter.
	ListSources(filter string) ([]string, error)

	// ListFuncs lists all functions in the process matching filter.
	ListFuncs(filter string) ([]string, error)

	// ListTypes lists all types in the process matching filter.
	ListTypes(filter string) ([]string, error)

	// WriteToConsole writes given message string to the debugger's output console.
	// message should end in newline
	WriteToConsole(msg string)
}

GiDebug is the interface for all supported debuggers. It is based directly on the Delve Client interface.

type Location 

type Location struct {
	PC    uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`
	File  string `desc:"file name (trimmed up to point of project base path)"`
	Line  int    `desc:"line within file"`
	FPath string `view:"-" tableview:"-" desc:"full path to file"`
	Func  string `desc:"the name of the function"`
}

Location holds program location information.

type Modes 

type Modes int32

Modes are different modes of running the debugger 

const (
	// Exec means debug a standard executable program
	Exec Modes = iota

	// Test means debug a testing program
	Test

	// Attach means attach to an already-running process
	Attach
)

type Params 

type Params struct {
	Mode     Modes             `xml:"-" json:"-" view:"-" desc:"mode for running the debugger"`
	PID      uint64            `xml:"-" json:"-" view:"-" desc:"process id number to attach to, for Attach mode"`
	Args     []string          `` /* 171-byte string literal not displayed */
	StatFunc func(stat Status) `xml:"-" json:"-" view:"-" desc:"status function for debugger updating status"`
	VarList  VarParams         `desc:"parameters for level of detail on overall list of variables"`
	GetVar   VarParams         `desc:"parameters for level of detail retrieving a specific variable"`
}

Params are overall debugger parameters

type State 

type State struct {
	Thread     Thread `desc:"currently executing system thread"`
	Task       Task   `desc:"currently executing task"`
	Running    bool   `desc:"true if the process is running and no other information can be collected."`
	NextUp     bool   `desc:"if true, a Next or Step is already in progress and another should not be attempted until after a Continue"`
	Exited     bool   `desc:"if true, the program has exited"`
	ExitStatus int    `desc:"indicates the exit status if Exited"`
	Err        error  `desc:"error communicated to client -- if non-empty, something bad happened"`
	CurTrace   int    `desc:"if this is > 0, then we just hit that tracepoint -- the Continue process will continue execution"`
}

State represents the current immediate execution state of the debugger.

func (*State) String added in v1.0.27 

func (st *State) String() string

type Status 

type Status int32

Status of the debugger 

const (
	// NotInit is not initialized
	NotInit Status = iota

	// Error means the debugger has an error -- usually from building
	Error

	// Building is building the exe for debugging
	Building

	// Ready means executable is built and ready to start (or restarted)
	Ready

	// Running means the process is running
	Running

	// Stopped means the process has stopped
	// (at a breakpoint, crash, or from single stepping)
	Stopped

	// Breakpoint means the process has stopped at a breakpoint
	Breakpoint

	// Finished means the process has finished running.
	// See console for output and return value etc
	Finished

	// StatusN is the number of find locations (scopes)
	StatusN
)

func (*Status) FromString 

func (i *Status) FromString(s string) error

func (Status) MarshalJSON 

func (ev Status) MarshalJSON() ([]byte, error)

func (Status) String 

func (i Status) String() string

func (*Status) UnmarshalJSON 

func (ev *Status) UnmarshalJSON(b []byte) error

type Task 

type Task struct {
	ID        int      `desc:"task identifier"`
	PC        uint64   `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`
	File      string   `desc:"file name (trimmed up to point of project base path)"`
	Line      int      `desc:"line within file"`
	FPath     string   `tableview:"-" tableview:"-" desc:"full path to file"`
	Func      string   `desc:"the name of the function"`
	Thread    int      `format:"%#X" desc:"id of the current Thread this task is running on"`
	StartLoc  Location `tableview:"-" desc:"where did this task first start running?"`
	LaunchLoc Location `tableview:"-" desc:"at what point was this task launched from another task?"`
}

Task is an optional finer-grained, lighter-weight thread, e.g., a goroutine in the Go language. if GiDebug HasTasks() == false then it is not used.

func TaskByID 

func TaskByID(thrs []*Task, id int) (*Task, int)

TaskByID returns the given thread by ID from full list, and index. returns nil, -1 if not found.

func (*Task) String added in v1.0.27 

func (th *Task) String() string

type Thread 

type Thread struct {
	ID    int    `format:"%#X" desc:"thread identifier"`
	PC    uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`
	File  string `desc:"file name (trimmed up to point of project base path)"`
	Line  int    `desc:"line within file"`
	FPath string `tableview:"-" tableview:"-" desc:"full path to file"`
	Func  string `desc:"the name of the function"`
	Task  int    `desc:"id of the current Task within this system thread (if relevant)"`
}

Thread is a system-level thread within the debugged process. For many languages, this is synonymous with functional threads, but if HasTasks() is true from GiDebug, then there are separate Task constructs as well, which provide a finer-grained processing within the Thread. For example, go routines in Go are represented by Tasks in the GiDebug framework.

func ThreadByID 

func ThreadByID(thrs []*Thread, id int) (*Thread, int)

ThreadByID returns the given thread by ID from full list, and index. returns nil, -1 if not found.

func (*Thread) String added in v1.0.27 

func (th *Thread) String() string

type VarParams 

type VarParams struct {
	FollowPointers  bool `` /* 166-byte string literal not displayed */
	MaxRecurse      int  `desc:"how far to recurse when evaluating nested types."`
	MaxStringLen    int  `desc:"the maximum number of bytes read from a string"`
	MaxArrayValues  int  `desc:"the maximum number of elements read from an array, a slice or a map."`
	MaxStructFields int  `desc:"the maximum number of fields read from a struct, -1 will read all fields."`
}

VarParams are parameters controlling how much detail the debugger reports about variables.

type Variable 

type Variable struct {
	ki.Node
	Value       string               `inactive:"-" width:"60" desc:"value of variable -- may be truncated if long"`
	TypeStr     string               `inactive:"-" desc:"type of variable as a string expression (shortened for display)"`
	FullTypeStr string               `view:"-" inactive:"-" desc:"type of variable as a string expression (full length)"`
	Kind        syms.Kinds           `inactive:"-" desc:"kind of element"`
	ElValue     string               `inactive:"-" view:"-" desc:"own elemental value of variable (blank for composite types)"`
	Len         int64                `inactive:"-" desc:"length of variable (slices, maps, strings etc)"`
	Cap         int64                `inactive:"-" tableview:"-" desc:"capacity of vaiable"`
	Addr        uintptr              `inactive:"-" desc:"address where variable is located in memory"`
	Heap        bool                 `inactive:"-" desc:"if true, the variable is stored in the main memory heap, not the stack"`
	Loc         Location             `inactive:"-" tableview:"-" desc:"location where the variable was defined in source"`
	List        []string             `tableview:"-" desc:"if kind is a list type (array, slice), and elements are primitive types, this is the contents"`
	Map         map[string]string    `tableview:"-" desc:"if kind is a map, and elements are primitive types, this is the contents"`
	MapVar      map[string]*Variable `tableview:"-" desc:"if kind is a map, and elements are not primitive types, this is the contents"`
	Dbg         GiDebug              `view:"-" desc:"our debugger -- for getting further variable data"`
}

Variable describes a variable. It is a Ki tree type so that full tree can be visualized.

func (*Variable) CopyFieldsFrom 

func (vr *Variable) CopyFieldsFrom(frm interface{})

func (*Variable) FollowPtr 

func (vr *Variable) FollowPtr()

FollowPtr retrieves the contents of this pointer and adds it as a child.

func (*Variable) Label added in v0.9.15 

func (vr *Variable) Label() string

Label satisfies the gi.Labeler interface for showing name = value

func (*Variable) TypeInfo 

func (vr *Variable) TypeInfo(newlines bool) string

TypeInfo returns a string of type information -- if newlines, then include newlines between each item (else tabs)

func (*Variable) ValueString 

func (vr *Variable) ValueString(newlines bool, ident int, maxdepth, maxlen int, outType bool) string

ValueString returns the value of the variable, integrating over sub-elements if newlines, each element is separated by a new line, and indented. Generally this should be used to set the Value field after getting new data. The maxdepth and maxlen parameters provide constraints on the detail provided by this string. outType indicates whether to output type name

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.