Zxdb Console (`zxdb/console`)

Overview

//src/developer/debug/zxdb/console implements the interactive and non-interactive command-line interface (Layer 5) for zxdb. It handles CLI flag parsing, noun/verb tokenization and dispatch, active object tracking via ConsoleContext, input location resolution, and terminal formatting for frames, registers, and tables.

Interface

Public headers and subdirectories expose these console components:

Console frontends and session context (console.h, console_impl.h, console_noninteractive.h, console_context.h): zxdb::Console, zxdb::Console::OutputObserver, zxdb::ConsoleImpl, zxdb::ConsoleNoninteractive, and zxdb::ConsoleContext (tracks active 1-based target/thread/breakpoint IDs and 0-based frame indices).
Command parsing, completion, and execution (command.h, command_parser.h, command_context.h, command_sequence.h, command_line_options.h): zxdb::Command, zxdb::CommandCallback, zxdb::DispatchCommand, zxdb::CommandContext, zxdb::ConsoleCommandContext, zxdb::OfflineCommandContext, and zxdb::NestedCommandContext. Also exposes zxdb::CommandToken, zxdb::TokenizeCommand, zxdb::ParseCommand, zxdb::FillCommandContextCallback, zxdb::GetCommandCompletions, zxdb::RunCommandSequence, zxdb::ReadCommandsFromFile, zxdb::CommandLineOptions, and zxdb::ParseCommandLine.
Noun, verb, and switch registries (nouns.h, verbs.h, switch_record.h): zxdb::Noun, zxdb::NounRecord, zxdb::GetNouns, zxdb::NounToString, zxdb::NounToRecord, zxdb::GetStringNounMap, zxdb::ExecuteNoun, zxdb::AppendNouns, and zxdb::GetNounSwitches. Also exposes zxdb::SourceAffinity, zxdb::Verb, zxdb::VerbRecord, zxdb::GetVerbs, zxdb::VerbToString, zxdb::GetVerbRecord, zxdb::GetStringVerbMap, zxdb::AppendSettingsVerbs, and zxdb::SwitchRecord.
Command validation and evaluation helpers (command_utils.h): zxdb::AssertRunningTarget, zxdb::AssertStoppedThreadWithFrameCommand, zxdb::AssertAllStoppedThreadsCommand, zxdb::CheckHexPrefix, zxdb::ReadUint64Arg, zxdb::ThreadStateToString, zxdb::ExecutionScopeToString, zxdb::ExecutionScopeForCommand, zxdb::ResolveBreakpointsForModification, zxdb::FormatBreakpoint, zxdb::FormatInputLocation, and zxdb::FormatInputLocations. Also exposes zxdb::GetEvalContextForCommand, zxdb::EvalCommandExpression, zxdb::EvalCommandAddressExpression, zxdb::RewriteCommandExpressionError, zxdb::FormatConsoleString, zxdb::GetNumberFormatForTarget, zxdb::GetRunnableTarget, zxdb::GetRunningProcesses, zxdb::VerifySystemHasRunningProcess, zxdb::ProcessCommandCallback, and zxdb::ScheduleAsyncPrintReturnValue.
Input location parsing and resolution (input_location_parser.h): zxdb::ParseGlobalInputLocation, zxdb::EvalGlobalInputLocation, zxdb::ParseLocalInputLocation, zxdb::EvalLocalInputLocation, zxdb::ResolveInputLocations, zxdb::ResolveUniqueInputLocation, and zxdb::CompleteInputLocation.
Stack, location, register, target, and table formatters (format_frame.h, format_location.h, format_register.h, format_table.h, format_target.h): zxdb::FormatFrameOptions, zxdb::FormatStackOptions, zxdb::FormatStack, zxdb::FormatFrame, zxdb::FormatAllThreadStacks, zxdb::FormatLocationOptions, zxdb::FormatLocation, zxdb::FormatFileName, and zxdb::FormatFileLine. Also exposes zxdb::FormatRegisterOptions, zxdb::FormatRegisters, zxdb::FormatGeneralRegisters, zxdb::FormatGeneralVectorRegisters, zxdb::DescribeRegister, zxdb::Align, zxdb::ColSpec, zxdb::FormatTable, zxdb::FormatTarget, zxdb::FormatTargetList, and zxdb::TargetStateToString.
commands: Individual console verb implementations (attach, break, step, run, print, backtrace, and memory/symbol inspection) exposing VerbRecord descriptors.

Invariants

Callers and implementations must preserve these invariants:

Console maintains a global singleton pointer accessible via Console::get().
Console::output_enabled_, Console::streaming_enabled_, and ConsoleImpl::input_enabled_ act as balanced reference counters. Each feature is active only when its counter is greater than 0.
Command::targets_ is never empty for valid commands, and Command::target() asserts !targets_.empty().
Single-object getters on Command (frame(), thread(), breakpoint(), filter(), sym_server()) return non-null only when the command has exactly one instance of that noun.
CommandContext is reference-counted and must stay alive across asynchronous command execution. Pending AsyncOutputBuffer instances hold a RefPtr<CommandContext>, and the completion callback runs when CommandContext destructs.
ConsoleContext assigns 1-based user IDs to targets, threads, breakpoints, filters, and symbol servers (0 means none or invalid). Frame IDs use 0-based indices into the thread's backtrace.
The active target in ConsoleContext always exists outside setup and teardown, whereas the active thread, breakpoint, filter, and symbol server may be null or 0.
GetNouns() and GetVerbs() return static maps that never change after initialization.

Side Effects

zxdb/console produces these terminal, file I/O, and session side effects:

ConsoleImpl watches stdin via debug::MessageLoop, writes formatted output to stdout, and reads and writes $HOME/.zxdb_history.
Console::Output and CommandContext::Output register completion callbacks and hold RefPtr references to pending AsyncOutputBuffer instances until they finish.
ConsoleContext observes Session, System, Target, Process, Thread, Breakpoint, Download, Component, and SettingStore. It updates active selections, evaluates display expressions on thread stop, and switches between Embedded and EmbeddedInteractive console modes.
RunCommandSequence reads script files from disk and dispatches commands on Console in order until completion or the first error.
ScheduleAsyncPrintReturnValue registers a PostStopTask on a stopped thread to evaluate and print function return values before normal stop handling.

Verification

Run these commands to build and test zxdb/console: