gidebug

package
v1.1.11 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2023 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 any, 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 we're running in
	Mode Modes `desc:"mode we're running in"`

	// overall debugger status
	Status Status `desc:"overall debugger status"`

	// current run state
	State State `desc:"current run state"`

	// id of the current system thread to examine
	CurThread int `desc:"id of the current system thread to examine"`

	// id of the current task to examine
	CurTask int `desc:"id of the current task to examine"`

	// frame number within current thread
	CurFrame int `desc:"frame number within current thread"`

	// current breakpoint that we stopped at -- will be 0 if none, after UpdateState
	CurBreak int `desc:"current breakpoint that we stopped at -- will be 0 if none, after UpdateState"`

	// all breakpoints that have been set -- some may not be On
	Breaks []*Break `desc:"all breakpoints that have been set -- some may not be On"`

	// current, active breakpoints as retrieved from debugger
	CurBreaks []*Break `desc:"current, active breakpoints as retrieved from debugger"`

	// all system threads
	Threads []*Thread `desc:"all system threads"`

	// all tasks
	Tasks []*Task `desc:"all tasks"`

	// current stack frame for current thread / task
	Stack []*Frame `desc:"current stack frame for current thread / task"`

	// current local variables and args for current frame
	Vars []*Variable `desc:"current local variables and args for current frame"`

	// global variables for current thread / task
	GlobalVars []*Variable `desc:"global variables for current thread / task"`

	// current find-frames result
	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 {

	// unique numerical ID of the breakpoint
	ID int `inactive:"+" desc:"unique numerical ID of the breakpoint"`

	// whether the breakpoint is currently enabled
	On bool `width:"4" desc:"whether the breakpoint is currently enabled"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `inactive:"+" format:"%#X" desc:"program counter (address) -- may be subset of multiple"`

	// file name (trimmed up to point of project base path)
	File string `inactive:"+" desc:"file name (trimmed up to point of project base path)"`

	// line within file
	Line int `inactive:"+" desc:"line within file"`

	// [view: -] [tableview: -] full path to file
	FPath string `inactive:"+" view:"-" tableview:"-" desc:"full path to file"`

	// the name of the function
	Func string `inactive:"+" desc:"the name of the function"`

	// condition for conditional breakbpoint
	Cond string `desc:"condition for conditional breakbpoint"`

	// if true, execution does not stop -- just a message is reported when this point is hit
	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 in overall stack -- 0 is the bottom (currently executing) frame, and it counts up from there
	Depth int `desc:"depth in overall stack -- 0 is the bottom (currently executing) frame, and it counts up from there"`

	// the Task or Thread id that this frame belongs to
	ThreadID int `desc:"the Task or Thread id that this frame belongs to"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`

	// file name (trimmed up to point of project base path)
	File string `desc:"file name (trimmed up to point of project base path)"`

	// line within file
	Line int `desc:"line within file"`

	// [tableview: -] full path to file
	FPath string `tableview:"-" tableview:"-" desc:"full path to file"`

	// the name of the function
	Func string `desc:"the name of the function"`

	// [tableview: -] values of the local variables at this frame
	Vars []*Variable `tableview:"-" desc:"values of the local variables at this frame"`

	// [tableview: -] values of the local function args 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 {

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`

	// file name (trimmed up to point of project base path)
	File string `desc:"file name (trimmed up to point of project base path)"`

	// line within file
	Line int `desc:"line within file"`

	// [view: -] [tableview: -] full path to file
	FPath string `view:"-" tableview:"-" desc:"full path to file"`

	// the name of the function
	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 {

	// [view: -] mode for running the debugger
	Mode Modes `xml:"-" json:"-" view:"-" desc:"mode for running the debugger"`

	// [view: -] process id number to attach to, for Attach mode
	PID uint64 `xml:"-" json:"-" view:"-" desc:"process id number to attach to, for Attach mode"`

	// optional extra args to pass to the debugger.  Use double-dash -- and then add args to pass args to the executable (double-dash is by itself as a separate arg first)
	Args []string `` /* 171-byte string literal not displayed */

	// [view: -] status function for debugger updating status
	StatFunc func(stat Status) `xml:"-" json:"-" view:"-" desc:"status function for debugger updating status"`

	// parameters for level of detail on overall list of variables
	VarList VarParams `desc:"parameters for level of detail on overall list of variables"`

	// parameters for level of detail retrieving a specific variable
	GetVar VarParams `desc:"parameters for level of detail retrieving a specific variable"`
}

Params are overall debugger parameters

type State 

type State struct {

	// currently executing system thread
	Thread Thread `desc:"currently executing system thread"`

	// currently executing task
	Task Task `desc:"currently executing task"`

	// true if the process is running and no other information can be collected.
	Running bool `desc:"true if the process is running and no other information can be collected."`

	// if true, a Next or Step is already in progress and another should not be attempted until after a Continue
	NextUp bool `desc:"if true, a Next or Step is already in progress and another should not be attempted until after a Continue"`

	// if true, the program has exited
	Exited bool `desc:"if true, the program has exited"`

	// indicates the exit status if Exited
	ExitStatus int `desc:"indicates the exit status if Exited"`

	// error communicated to client -- if non-empty, something bad happened
	Err error `desc:"error communicated to client -- if non-empty, something bad happened"`

	// if this is > 0, then we just hit that tracepoint -- the Continue process will continue execution
	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 {

	// task identifier
	ID int `desc:"task identifier"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`

	// file name (trimmed up to point of project base path)
	File string `desc:"file name (trimmed up to point of project base path)"`

	// line within file
	Line int `desc:"line within file"`

	// [tableview: -] full path to file
	FPath string `tableview:"-" tableview:"-" desc:"full path to file"`

	// the name of the function
	Func string `desc:"the name of the function"`

	// id of the current Thread this task is running on
	Thread int `format:"%#X" desc:"id of the current Thread this task is running on"`

	// [tableview: -] where did this task first start running?
	StartLoc Location `tableview:"-" desc:"where did this task first start running?"`

	// [tableview: -] at what point was this task launched from another task?
	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 {

	// thread identifier
	ID int `format:"%#X" desc:"thread identifier"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X" desc:"program counter (address) -- may be subset of multiple"`

	// file name (trimmed up to point of project base path)
	File string `desc:"file name (trimmed up to point of project base path)"`

	// line within file
	Line int `desc:"line within file"`

	// [tableview: -] full path to file
	FPath string `tableview:"-" desc:"full path to file"`

	// the name of the function
	Func string `desc:"the name of the function"`

	// id of the current Task within this system thread (if relevant)
	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 {

	// [def: false] requests pointers to be automatically dereferenced -- this can be very dangerous in terms of size of variable data returned and is not recommended.
	FollowPointers bool `` /* 166-byte string literal not displayed */

	// how far to recurse when evaluating nested types.
	MaxRecurse int `desc:"how far to recurse when evaluating nested types."`

	// the maximum number of bytes read from a string
	MaxStringLen int `desc:"the maximum number of bytes read from a string"`

	// the maximum number of elements read from an array, a slice or a map.
	MaxArrayValues int `desc:"the maximum number of elements read from an array, a slice or a map."`

	// the maximum number of fields read from a struct, -1 will read all fields.
	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 of variable -- may be truncated if long
	Value string `inactive:"-" width:"60" desc:"value of variable -- may be truncated if long"`

	// type of variable as a string expression (shortened for display)
	TypeStr string `inactive:"-" desc:"type of variable as a string expression (shortened for display)"`

	// [view: -] type of variable as a string expression (full length)
	FullTypeStr string `view:"-" inactive:"-" desc:"type of variable as a string expression (full length)"`

	// kind of element
	Kind syms.Kinds `inactive:"-" desc:"kind of element"`

	// [view: -] own elemental value of variable (blank for composite types)
	ElValue string `inactive:"-" view:"-" desc:"own elemental value of variable (blank for composite types)"`

	// length of variable (slices, maps, strings etc)
	Len int64 `inactive:"-" desc:"length of variable (slices, maps, strings etc)"`

	// [tableview: -] capacity of vaiable
	Cap int64 `inactive:"-" tableview:"-" desc:"capacity of vaiable"`

	// address where variable is located in memory
	Addr uintptr `inactive:"-" desc:"address where variable is located in memory"`

	// if true, the variable is stored in the main memory heap, not the stack
	Heap bool `inactive:"-" desc:"if true, the variable is stored in the main memory heap, not the stack"`

	// [tableview: -] location where the variable was defined in source
	Loc Location `inactive:"-" tableview:"-" desc:"location where the variable was defined in source"`

	// [tableview: -] if kind is a list type (array, slice), and elements are primitive types, this is the contents
	List []string `tableview:"-" desc:"if kind is a list type (array, slice), and elements are primitive types, this is the contents"`

	// [tableview: -] if kind is a map, 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"`

	// [tableview: -] if kind is a map, and elements are not 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"`

	// [view: -] our debugger -- for getting further variable data
	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 any)

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.