Debugging - Glass

Glass provides a comprehensive debugging experience through the Debug Adapter Protocol (DAP), supporting multiple programming languages and debugging scenarios.

Debug Panel

The Debug Panel is your central hub for all debugging activities in Glass.

Panel Overview

// From crates/debugger_ui/src/debugger_panel.rs
pub struct DebugPanel {
    active_session: Option<Entity<DebugSession>>,
    project: Entity<Project>,
    workspace: WeakEntity<Workspace>,
    focus_handle: FocusHandle,
    breakpoint_list: Entity<BreakpointList>,
    // ...
}

Variables
Call Stack
Breakpoints
Console

Inspect local variables, arguments, and captured values in the current scope. The variables view updates automatically as you step through code.

Panel Actions

Common debug panel actions:

// From crates/debugger_ui/src/debugger_panel.rs
FocusVariables,
FocusFrames,
FocusBreakpointList,
FocusConsole,
FocusTerminal,
FocusLoadedSources,
FocusModules,

Starting Debug Sessions

Glass supports multiple ways to start debugging your code.

Launch Configuration

Define debug scenarios in your project’s .glass/tasks.json or .vscode/launch.json:

{
  "adapter": "debugpy",
  "label": "Debug Python App",
  "config": {
    "request": "launch",
    "program": "${file}",
    "console": "integratedTerminal"
  }
}

Attach to Process

Attach to already-running processes using the attach request type:

// From crates/task/src/debug_format.rs
pub enum Request {
    Launch(LaunchRequest),
    Attach(AttachRequest),
}

Quick Debug

Use quick debug actions to start debugging without manual configuration, using sensible defaults for your language.

Debug Adapters

// From crates/dap/src/adapters.rs
pub struct DebugAdapterName(pub String);

Glass supports multiple debug adapters:

debugpy - Python debugging
lldb / codelldb - C, C++, Rust debugging
node - JavaScript/TypeScript debugging
go - Go debugging
And more through DAP extensions

Debug adapters are automatically detected and installed based on your project’s language. You can also manually configure adapter paths in settings.

Breakpoints

Set and manage breakpoints to pause execution at specific locations.

Breakpoint Types

// From crates/project/src/debugger/breakpoint_store.rs
pub struct Breakpoint {
    // Breakpoint configuration
}

pub enum BreakpointState {
    // Active, disabled, or pending
}

Line Breakpoints
Conditional Breakpoints
Hit Count Breakpoints
Logpoints

Click the gutter next to any line number to set a breakpoint. The breakpoint will pause execution when that line is reached.

Add conditions to breakpoints so they only trigger when specific criteria are met:

// Only break when count > 10
count > 10

Breakpoint Management

pub enum BreakpointEditAction {
    Add,
    Remove,
    Toggle,
}

Breakpoint actions:

Toggle breakpoint at current line
Clear all breakpoints in the project
Enable/disable individual breakpoints
Add conditions or hit counts

Breakpoints in files that haven’t been loaded by the debugger will show as “pending” until the debugger loads that code.

Execution Control

Control program execution with precision.

Step Commands

// Available stepping actions
Continue,
Pause,
StepOver,
StepInto,
StepOut,
Stop,

Continue

Resume execution until the next breakpoint or program completion.

Step Over

Execute the current line and move to the next line, treating function calls as single steps.

Step Into

Step into function calls to debug their internals.

Step Out

Complete execution of the current function and pause at the caller.

Session Management

// From crates/debugger_ui/src/debugger_panel.rs
pub fn start_session(
    &mut self,
    scenario: DebugScenario,
    task_context: SharedTaskContext,
    active_buffer: Option<Entity<Buffer>>,
    worktree_id: Option<WorktreeId>,
    window: &mut Window,
    cx: &mut Context<Self>,
)

Session actions:

Start new session with a debug scenario
Stop session to terminate debugging
Restart session to rerun with same configuration
Detach from attached processes

RerunSession,
Stop,
Detach,

Variable Inspection

Examine and modify program state while debugging.

Variables View

// Variables are represented with references for complex objects
pub type VariableReference = u64;

Inspect variables:

Local variables in current scope
Global variables and static values
Closure captures in functional languages
Object properties expanded hierarchically

Scopes

pub type ScopeId = u64;

Glass shows variables organized by scope:

Local - Function parameters and local variables
Global - Module-level and global variables
Closure - Captured variables from outer scopes

Expand complex objects in the variables view to explore nested properties. Some debuggers support lazy loading of large data structures.

Call Stack

Understand the execution path that led to the current state.

Stack Frames

pub type StackFrameId = u64;

pub enum ThreadStatus {
    // Thread state: running, stopped, etc.
}

The call stack shows:

Function names at each level
Source locations with file and line
Frame indices for reference
Thread information in multi-threaded apps

Click any frame to:

View its source code
Inspect its variables
Evaluate expressions in its context

Debug Console

Interact with your running application through the debug console.

Evaluate Expressions

Type expressions to evaluate them in the context of the current stack frame:

# Python example
len(my_list)
obj.property + 10

REPL Integration

Some debug adapters provide full REPL functionality, allowing you to:

Execute arbitrary code
Call functions
Modify variables
Import modules

Debug Adapter Protocol

Glass implements the Debug Adapter Protocol for universal debugging support.

DAP Implementation

// From crates/dap/src/dap.rs
pub use dap_types::*;
pub use registry::{DapRegistry, DapLocator};

DAP features:

Standardized protocol across languages
Extensible through adapters
Rich debugging capabilities
Terminal integration for console output

Session Configuration

pub struct SessionQuirks {
    pub compact: bool,
    pub prefer_thread_name: bool,
}

Glass handles adapter-specific quirks and behaviors automatically, ensuring consistent debugging experience.

TCP Debugging

For remote debugging scenarios:

pub async fn configure_tcp_connection(
    tcp_connection: TcpArgumentsTemplate,
) -> anyhow::Result<(Ipv4Addr, u16, Option<u64>)>

Connect to remote debug servers:

Specify host and port
Configure connection timeout
Debug containerized applications
Remote server debugging

Build Tasks

Run build tasks before debugging:

// From crates/task/src/debug_format.rs
pub struct DebugScenario {
    pub adapter: String,
    pub label: String,
    pub config: serde_json::Value,
    pub build: Option<BuildTaskDefinition>,
}

Debug scenarios can specify build tasks that run automatically before launching the debugger.

Build tasks ensure your code is compiled with debug symbols before debugging starts, providing accurate source mapping and variable information.

Advanced Features

Multiple Sessions

pub(crate) sessions_with_children:
    IndexMap<Entity<DebugSession>, Vec<WeakEntity<DebugSession>>>,

Glass supports:

Multiple concurrent debug sessions
Parent-child session relationships
Session picker to switch between active sessions

Thread Management

For multi-threaded applications:

Thread picker to select which thread to inspect
Per-thread call stacks
Thread-specific stepping

Inline Values

// From crates/dap/src/inline_value.rs

Some adapters support inline value display, showing variable values directly in the editor without opening the variables panel.

Best Practices

Use conditional breakpoints to avoid stopping on every iteration in loops
Leverage logpoints for non-intrusive debugging in production-like environments
Organize breakpoints - disable rather than delete breakpoints you might need later
Use the debug console to quickly test hypotheses without modifying code
Configure build tasks in debug scenarios to ensure code is always up-to-date
Master stepping - know when to step over vs. step into
Explore stack frames to understand call chains and variable scopes

Troubleshooting

Debugger Won’t Start

Verify debug adapter is installed
Check debug configuration syntax
Review console output for error messages
Ensure build tasks complete successfully

Breakpoints Not Hitting

Confirm code is compiled with debug symbols
Check that source maps are correct
Verify the file path matches the running code
Look for “pending” breakpoint status

Variables Show “optimized out”

Compile with debug symbols and without optimizations
Some values may be legitimately optimized away by the compiler

Testing - Run tests and tasks from the editor
Navigation - Navigate code while debugging
Git Integration - Debug specific commits or branches

Get Started

Core Features

AI Capabilities

Development

Customization

Language Support

​Debug Panel

​Panel Overview

​Panel Actions

​Starting Debug Sessions

​Debug Adapters

​Breakpoints

​Breakpoint Types

​Breakpoint Management

​Execution Control

​Step Commands

​Session Management

​Variable Inspection

​Variables View

​Scopes

​Call Stack

​Stack Frames

​Debug Console

​Evaluate Expressions

​REPL Integration

​Debug Adapter Protocol

​DAP Implementation

​Session Configuration

​TCP Debugging

​Build Tasks

​Advanced Features

​Multiple Sessions

​Thread Management

​Inline Values

​Best Practices

​Troubleshooting

​Debugger Won’t Start

​Breakpoints Not Hitting

​Variables Show “optimized out”

​Related Features

Build docs developers (and LLMs) love

Debug Panel

Panel Overview

Panel Actions

Starting Debug Sessions

Debug Adapters

Breakpoints

Breakpoint Types

Breakpoint Management

Execution Control

Step Commands

Session Management

Variable Inspection

Variables View

Scopes

Call Stack

Stack Frames

Debug Console

Evaluate Expressions

REPL Integration

Debug Adapter Protocol

DAP Implementation

Session Configuration

TCP Debugging

Build Tasks

Advanced Features

Multiple Sessions

Thread Management

Inline Values

Best Practices

Troubleshooting

Debugger Won’t Start

Breakpoints Not Hitting

Variables Show “optimized out”

Related Features