cli-anything-lldb

Habilidade CLI LLDB

Use esta CLI para executar fluxos de trabalho de depuração LLDB estruturados com saída JSON.

Capacidades

• Criar destino de depuração a partir do caminho do executável
• Lançar processo ou anexar por PID/nome
• Gerenciar breakpoints (definir/listar/deletar/habilitar/desabilitar)
• Inspecionar threads, frames, variáveis locais e backtrace
• Avaliar expressões no frame atual
• Ler/encontrar memória do processo
• Carregar core dumps
• REPL interativo com estado de sessão persistente
• Servidor formal do Debug Adapter Protocol (DAP) via stdio para clientes de IA/editores

Comandos Rápidos

cli-anything-lldb --json target create --exe /caminho/para/exe
cli-anything-lldb --json process launch --arg foo --arg bar
cli-anything-lldb --json breakpoint set --function main
cli-anything-lldb --json breakpoint set --function PluginEntry --allow-pending
cli-anything-lldb --json process continue
cli-anything-lldb --json process interrupt
cli-anything-lldb --json thread backtrace --limit 20
cli-anything-lldb --json frame locals
cli-anything-lldb --json expr "myVar"
cli-anything-lldb --json memory read --address 0x1000 --size 64
cli-anything-lldb --json session close

Debug Adapter Protocol

Use o ponto de entrada DAP quando um cliente de IA precisar de um ciclo de vida real do adaptador de depuração em vez de chamar comandos CLI separados:

cli-anything-lldb-dap
cli-anything-lldb-dap --profile /caminho/para/regras-de-parada.json

ou:

cli-anything-lldb dap
cli-anything-lldb dap --profile /caminho/para/regras-de-parada.json

O servidor DAP se comunica via quadros Content-Length no stdio e deve ter stdout exclusivo. Não imprima logs no stdout ao redor dele. Requisições suportadas incluem initialize, launch, attach, configurationDone, setBreakpoints, setFunctionBreakpoints, threads, stackTrace, scopes, variables, setVariable, evaluate, continue, pause, next, stepIn, stepOut, source, loadedSources, readMemory, modules, exceptionInfo, disassemble e disconnect.

Variáveis DAP podem expor referências filhas para structs/classes/arrays. Use setVariable apenas quando parado; o LLDB pode rejeitar escritas em valores otimizados ou somente leitura.

Para processos com interface gráfica de longa duração, o DAP continue é não bloqueante do ponto de vista do cliente: o adaptador envia primeiro a resposta e o evento continued, depois aguarda o LLDB em uma thread de fundo. O DAP pause usa interrupção assíncrona do LLDB. Se um agente precisar alterar breakpoints enquanto o depurador estiver em execução, o adaptador interrompe primeiro e aguarda um estado de parada antes de modificar os breakpoints do LLDB; se o alvo não parar a tempo, tente novamente após um ciclo explícito de pause/stopped.

Para aplicações GUI que param em breakpoints internos de inicialização do depurador ou shader-JIT, launch e attach aceitam o argumento booleano não padrão autoContinueInternalBreakpoints. Ative-o apenas quando essas paradas internas forem ruído para a tarefa; o adaptador emite um evento output antes de continuar automaticamente. Para ruído específico do alvo, prefira regras de parada estruturadas através de stopRules embutidas ou de um arquivo JSON externo stopRuleProfile/--profile. As regras podem corresponder por reason, module, function e/ou regex, e então stop com metadados claros cliAnythingStop.origin ou continue automaticamente. Use perfis para aplicações como C4D para que seus traps de shader-JIT/inicialização da NVIDIA fiquem fora do adaptador genérico.

Eventos DAP stopped incluem body.cliAnythingStop.origin: manualPause para uma requisição de pausa do cliente, internalTrap para uma regra interna correspondida e debuggee para paradas comuns do programa. Processos cli-anything-lldb-dap existentes não carregam novo código ou conteúdo de perfil a quente; reinicie o adaptador e reanexe ou relance antes de esperar que novas regras se apliquem.

Grupos de Comandos

target

cli-anything-lldb --json target create --exe /caminho/para/exe [--arch x86_64]
cli-anything-lldb --json target info

process

cli-anything-lldb --json process launch [--arg ARG ...] [--env KEY=VALUE ...] [--cwd DIR] [--stop-at-entry]
cli-anything-lldb --json process attach --pid 1234
cli-anything-lldb --json process attach --name myapp --wait-for
cli-anything-lldb --json process continue
cli-anything-lldb --json process interrupt
cli-anything-lldb --json process detach
cli-anything-lldb --json process info

breakpoint

cli-anything-lldb --json breakpoint set --function main
cli-anything-lldb --json breakpoint set --file main.c --line 42 --condition "i > 10"
cli-anything-lldb --json breakpoint set --function LateLoadedSymbol --allow-pending
cli-anything-lldb --json breakpoint list
cli-anything-lldb --json breakpoint delete --id 1
cli-anything-lldb --json breakpoint enable --id 1
cli-anything-lldb --json breakpoint disable --id 1

thread / frame / step

cli-anything-lldb --json thread list
cli-anything-lldb --json thread select --id 11111
cli-anything-lldb --json thread backtrace --limit 50
cli-anything-lldb --json frame select --index 0
cli-anything-lldb --json frame info
cli-anything-lldb --json frame locals
cli-anything-lldb --json step over
cli-anything-lldb --json step into
cli-anything-lldb --json step out

expr / memory / core

cli-anything-lldb --json expr "argc"
cli-anything-lldb --json memory read --address 0x1000 --size 128
cli-anything-lldb --json memory find "needle" --start 0x1000 --size 4096
cli-anything-lldb --json core load --path /caminho/para/core

Notas de Uso para Agentes

• Prefira --json para todos os fluxos automatizados.
• Invocações não REPL separadas compartilham um daemon de sessão persistente por padrão.
• Use --session-file CAMINHO ou CLI_ANYTHING_LLDB_SESSION_FILE para fixar uma sessão explícita para uma tarefa.
• Execute cli-anything-lldb --json session close quando terminar para que processos anexados sejam desanexados e depuradores lançados sejam limpos.
• Use REPL quando um shell interativo similar ao humano for mais conveniente, não porque a persistência o exige.
• Breakpoints CLI não resolvidos falham por padrão; passe --allow-pending apenas quando um carregamento futuro de módulo/símbolo for esperado.
• Breakpoints DAP não resolvidos usam semântica do protocolo: verified: false até serem resolvidos.
• DAP continue é não bloqueante para processos GUI de longa duração, e DAP pause usa interrupção assíncrona.
• Mudanças de breakpoints DAP durante um continue ativo primeiro interrompem e aguardam um estado de parada antes de modificar o LLDB.
• Use perfis de regras de parada DAP para traps internas específicas da aplicação; reinicie e reanexe/relance após alterações no perfil.
• memory find usa uma varredura fragmentada limitada a 1 MiB por chamada.
• Chame target create antes de comandos de processo ou core.
• Espere erros estruturados: {"error": "...", "type": "..."}