Debugger.hpp

浏览该文件的文档.

#pragma once
 
#include "common/Export.h"
#include "devtools/CallGraph.hpp"
 
#include <atomic>
#include <cstdint>
#include <functional>
#include <mutex>
#include <string>
#include <unordered_map>
#include <vector>
 
struct SQVM;
typedef struct SQVM* HSQUIRRELVM;
 
namespace eve::dev {
 
enum class PauseReason : uint8_t {
    None = 0,
    PauseKey,
    Breakpoint,
    Step,
    Exception,
    Snapshot,
};
 
enum class RunMode : uint8_t {
    Running = 0,
    Paused,      // frame-level or script-level pause
    StepFrame,   // run one game frame then pause
    StepInto,    // next script line (any call depth) — DAP stepIn
    StepOver,    // next script line at ≤ start depth — DAP next
    StepOut,     // next script line at < start depth — DAP stepOut
};
 
struct EVENGINE_API_FOUNDATION_INLINE Breakpoint {
    std::string source;  // normalized path or basename
    int         line    = 0;
    bool        enabled = true;
    bool        verified = false;
    std::string condition;  // optional GDScript-style condition; empty = always
    int         id      = 0;
};
 
struct EVENGINE_API_FOUNDATION_INLINE WatchEntry {
    std::string expression;
    std::string value;  // last evaluated (display)
    bool        ok = false;
};
 
struct EVENGINE_API_FOUNDATION_INLINE StackFrameInfo {
    int         id = 0;
    SourceLoc   loc;
    std::string name;
};
 
struct EVENGINE_API_FOUNDATION_INLINE VariableInfo {
    std::string name;
    std::string value;
    std::string type;
    bool        expensive = false;
    bool        expandable = false;  // container / instance: children available
    int         childCount = -1;     // -1 = unknown
};
 
enum class VarKind : uint8_t {
    Locals   = 0,  // frame locals
    Globals  = 1,  // roottable
    // Closure upvalues are children of a closure value, not a third root.
};
 
class EVENGINE_API_FOUNDATION Debugger {
public:
    static Debugger& instance();
 
    Debugger(const Debugger&)            = delete;
    Debugger& operator=(const Debugger&) = delete;
 
    void attach(HSQUIRRELVM vm);
    void detach();
    bool isAttached() const { return vm_ != nullptr; }
    HSQUIRRELVM vm() const { return vm_; }
 
    // ---- run control ----
    void     pause(PauseReason reason = PauseReason::PauseKey);
    void     pauseAt(PauseReason reason, SourceLoc loc);
    void     resume();
    void     stepFrame();
    void     stepFrames(int count);
    void     stepInto();
    void     stepOver();
    void     stepOut();
    void     stepLine() { stepInto(); }
    void     step();
    bool     isPaused() const { return mode_.load() == RunMode::Paused; }
    RunMode  mode() const { return mode_.load(); }
    PauseReason lastPauseReason() const { return reason_.load(); }
    const SourceLoc& pauseLocation() const { return pauseLoc_; }
    int      scriptStackDepth() const;
 
    bool shouldRunUpdate();
    void notifyFrameDone();
 
    void setCallGraph(CallGraph* graph);
    void setVirtualSource(std::string source, std::string text);
 
    std::string onCall(SourceLoc loc);
    void onReturn(const SourceLoc& loc);
 
    bool onScriptLine(const SourceLoc& loc);
    void waitWhilePaused(const std::function<void()>& pump = {});
 
    // ---- breakpoints ----
    int  setBreakpoint(std::string source, int line, bool enabled = true,
                       std::string condition = {});
    bool clearBreakpoint(std::string source, int line);
    void clearBreakpoints(const std::string& source = {});
    bool setBreakpointEnabled(int id, bool enabled);
    std::vector<Breakpoint> breakpoints() const;
    bool hasBreakpoint(const std::string& source, int line) const;
 
    // ---- watches ----
    void addWatch(std::string expression);
    bool removeWatch(const std::string& expression);
    void clearWatches();
    std::vector<WatchEntry> watches() const;
    void refreshWatches();
    VariableInfo evaluate(const std::string& expression, int frameLevel = 0) const;
    std::vector<VariableInfo> locals(int stackLevel = 0) const;
    std::vector<VariableInfo> globals() const;
    std::vector<VariableInfo> containerChildren(VarKind kind, int frame,
                                                const std::vector<std::string>& path) const;
    std::vector<StackFrameInfo> stackTrace(int maxFrames = 32) const;
 
    // ---- error / breakpoint policy ----
    void setBreakOnError(bool on) { breakOnError_.store(on); }
    bool breakOnError() const { return breakOnError_.load(); }
    void setBreakpointsEnabled(bool on) { bpsEnabled_.store(on); }
    bool breakpointsEnabled() const { return bpsEnabled_.load(); }
    using BreakpointEventFn = std::function<void(int id, const std::string& source, int line,
                                                 bool verified)>;
    void setBreakpointEventFn(BreakpointEventFn fn) { bpEventFn_ = std::move(fn); }
 
    using PumpFn = std::function<void()>;
    void setPump(PumpFn pump) { pump_ = std::move(pump); }
 
    static std::string normalizeSource(std::string source);
    static std::string sourceBasename(const std::string& source);
    static bool sourcesMatch(const std::string& a, const std::string& b);
 
private:
    Debugger() = default;
 
    bool matchBreakpoint(const std::string& source, int line) const;
    bool matchBreakpointAny(const std::string& source, int line) const;
    bool conditionHolds(const Breakpoint& bp) const;
    bool pushPathValue(HSQUIRRELVM vm, VarKind kind, int frame,
                       const std::vector<std::string>& path) const;
    VariableInfo readLocal(HSQUIRRELVM vm, unsigned level, const std::string& name) const;
    VariableInfo readRoot(HSQUIRRELVM vm, const std::string& name) const;
    VariableInfo evaluateLegacy(const std::string& expression) const;
    bool pushLocalValue(HSQUIRRELVM vm, unsigned level, const std::string& name) const;
    void beginScriptStep(RunMode mode);
    CallGraph& activeGraph();
    const CallGraph& activeGraph() const;
    std::string resolveCallName(const SourceLoc& loc) const;
    std::string lineAt(const std::string& source, int line) const;
    std::string nameFromPrototype(int level, const char* rawName, const SourceLoc& loc) const;
    void applyCallGraphNames(std::vector<StackFrameInfo>& frames) const;
 
    HSQUIRRELVM           vm_ = nullptr;
    std::atomic<RunMode>  mode_{RunMode::Running};
    std::atomic<PauseReason> reason_{PauseReason::None};
    std::atomic<bool>     breakOnError_{false};
    std::atomic<bool>     bpsEnabled_{true};
    SourceLoc             pauseLoc_;
    mutable std::mutex    mu_;
    std::vector<Breakpoint> bps_;
    std::vector<std::string> watchExprs_;
    std::vector<WatchEntry>  watchCache_;
    int                   nextBpId_ = 1;
    PumpFn                pump_;
    bool                  stepFrameArmed_ = false;
    int                   remainingHostFrames_ = 0;
    int                   stepStartDepth_ = 0;
    SourceLoc             stepSkipLoc_;
    BreakpointEventFn     bpEventFn_;
    CallGraph*            callGraph_ = nullptr;
    CallGraph             ownGraph_;
    std::unordered_map<std::string, std::string> virtualSources_;
};
 
}  // namespace eve::dev