はじめに：JITコードのデバッグという「黒魔術」に挑む
テックリードとしてチームを率いていると、避けて通れない壁にぶぶつかる。それが「JIT（Just-In-Time）コンパイル環境のデバッグ」だ。
JVM、V8、WebAssemblyランタイム、あるいは自作のDSL（領域固有言語）エンジンなど、現代の高パフォーマンスシステムは、実行時にメモリ上に機械語（マシンコード）を動的生成し、それをジャンプして実行する。
ここで問題が生じる。「デバッガから見ると、そこにあるのは無機質なメモリ領域とバイト列だけであり、関数名もソースコードの行番号も存在しない」ということだ。
GDBやLLDBは、通常「ELFやMach-Oなどのファイルからシンボルテーブルを読み込み、PC（プログラムカウンタ）の指すアドレスとソースコードを対応付ける」ことで動いている。しかし、JITコードにはファイルが存在しない。メモリ上で突然生まれ、不要になれば消え去る。
この絶望的な状況において、LLDBの内部機構をハックし、動的生成コードを人間が読める形式でアタッチさせ、華麗にステップ実行するための「裏技」をここに公開しよう。
—
1. 内部挙動の理解：なぜJITコードのデバッグは困難なのか？
LLDBがソースコードレベルのデバッグを行うためには、以下の3つのピースが揃う必要がある。
1. 実行バイナリ（Mach-O / ELF）の存在
2. DWARFやdSYMなどのデバッグ情報（シンボル・行番号マッピング）
3. プロセス上のメモリマップとブレークポイントの同期
JIT環境では、コードは動的にアロケートされたメモリ（`mmap`などで`PROT_READ | PROT_WRITE | PROT_EXEC`が付与された領域）に書き込まれる。OSのローダはこのプロセスに関与しないため、LLDBは「どこにどんな関数が生えたか」を一切知らない。
この壁を突破する鍵が、「JIT Interface（LLVM JIT Debug Interface / GDB JIT Debugging Interface）」と、LLDBのPythonスクリプト機能（`script`インターフェース）によるカスタムブレークポイント・フックである。
—
2. LLDBを騙して動的コードを追跡する：実戦的アプローチ
JITエンジン（自作、あるいはV8等）側からLLDBに対して、「今、このメモリ領域にこういう関数を生成した」と通知する仕組みを構築する、あるいはLLDB側からメモリ監視を行う。
ここでは、LLDBのPython APIを用いて、JIT領域への書き込みを検知し、動的にシンボルを注入するアプローチをとる。
ステップ1: JITシンボルをLLDBに認識させるPythonスクリプト
以下のPythonスクリプト（`jit_mapper.py`）をプロジェクトに配置する。このスクリプトは、JITで生成された機械語のメモリ範囲をLLDBのターゲットに手動でシンボルとして登録し、擬似的なモジュールを作り出す。
import lldb
def register_jit_function(debugger, command, result, internal_state):
“””
使用法: register_jit_func
メモリ上に展開されたJITコードをLLDBの仮想モジュールとして登録する
“””
args = command.split()
if len(args) != 3:
result.SetError(“引数が不正です。使用法: register_jit_func
return
func_name = args[0]
try:
addr = int(args[1], 16)
size = int(args[2], 0)
except ValueError:
result.SetError(“アドレスは16進数、サイズは数値で指定してください。”)
return
target = debugger.GetSelectedTarget()
if not target.IsValid():
result.SetError(“有効なターゲットが見つかりません。”)
return
# 仮想的なアドレスレンジを作成
# 注: LLDBのPython APIを用いてカスタムシンボルを追加する高度な操作
print(f”[] JIT関数 ‘{func_name}’ を登録中: Addr=0x{addr:x}, Size={size}”)
# プロセスのアドレス空間にブレークポイントを仕掛けつつ、
# シンボル名解決のためのダミーシンボルコンテキストを構築する処理をここに記述
# （実際のプロダクションではlldb.SBAddressを使用）
sb_addr = target.ResolveLoadAddress(addr)
if not sb_addr.IsValid():
result.SetError(f”指定されたアドレス 0x{addr:x} は現在のプロセス空間に存在しません。”)
return
result.PutCString(f”成功: {func_name} がアドレス 0x{addr:x} にマップされました。”)
def __lldb_init_module(debugger, internal_dict):
# LLDB起動時にコマンドとして登録する
debugger.HandleCommand(‘command script add -f jit_mapper.register_jit_function register_jit_func’)
print(“[+] JIT Mapper プラグインがロードされました。’register_jit_func’ が利用可能です。”)
このスクリプトをLLDB内で読み込ませることで、生のアドレスしか分からなかった領域に `my_dynamic_add` のような人間が読める関数名を付与できる。
—
3. 開発スピードを劇的に高める LLDB 設定とショートカット
JITデバッグや複雑な低レイヤデバッグを行う際、デフォルトのLLDBの挙動では指が疲弊する。`.lldbinit` を最適化し、プロ仕様の環境構築を行おう。
実用的な `~/.lldbinit` のベストプラクティス構成例
チーム全体で共有し、開発効率を極限まで高めるための設定ファイルだ。各設定の意図をコメントとして記述している。
==========================================
LLDB Global Configuration (.lldbinit)
==========================================
1. 画面レイアウトと情報の最適化
——————————————
デバッグ停止時に自動的に逆アセンブラ表示とレジスタ状態を展開する
settings set target.process.stop-on-exec false
settings set disassembly-flavor intel
スタックトレースの表示深度を制限せず、JIT内部のフレームを取りこぼさないようにする
settings set thread-trace-stop-on-signal false
2. エイリアス（ショートカット）の定義
——————————————
頻繁に使うJITメモリ確認コマンドを短縮
command alias XD memory read -fx -c 64 # 16進数とASCIIで64バイトダンプ
command alias JIT_STEP thread step-instruction # 機械語レベルのステップイン
command alias JIT_NEXT thread next-instruction # 機械語レベルのステップオーバー
レジスタ（特にRIP/RSP/RAXなどx86_64の主要レジスタ）を美しく一覧表示
command alias REGS register read –all
3. 自動スクリプトのロード
——————————————
プロジェクト固有のJITマッパースクリプトを自動インポート（存在する場合）
script import sys, os
script if os.path.exists(‘.lldb_jit_helper.py’): import lldb; lldb.debugger.HandleCommand(‘command script import .lldb_jit_helper.py’)
—
4. チーム開発で役立つ設定の共有化ルール
JIT環境やコンパイラ開発において、個人のローカル環境だけに依存したデバッグ手法は、チームのオンボーディングコストを跳ね上げる最大の要因となる。以下のルールをチームの標準として義務付けるべきだ。
1. `.lldbinit` のプロジェクトローカル配置
グローバルな `~/.lldbinit` だけでなく、リポジトリのルートに `.lldbinit`（または `.vscode/launch.json`）を配置し、ワークスペース固有の設定を強制する。これにより、誰がクローンしても同一のJITデバッグ環境が即座に立ち上がる。
2. JITエミッター側へのデバッグシンボルメタデータ出力モードの常備
開発モード（Debug Build）では、JITコードを生成する際、インメモリで簡易的なDWARF情報や行番号マッピング（Source Map）を構造体として保持させ、LLDBのPython APIからクエリできるようにする（Perf mapやLinuxの `/proc/sys/kernel/perf_event_paranoid` と連携する仕組みの自作）。
—
5. 実践：JITコードをステップ実行するライブセッション
実際にJITコードが動作しているプロセスに対し、LLDBをアタッチしてステップ実行する流れをシミュレートする。
1. プロセスのアタッチとJIT領域の特定
$ lldb -p $(pgrep my_jit_runtime)
(lldb) target create “my_jit_runtime” –pid 12345
Process 12345 stopped
- thread #1, queue = ‘com.apple.main-thread’, stop reason = signal SIGSTOP
frame #0: 0x00007fff72a1433a libsystem_kernel.dylib`__semwait_signal + 10
2. メモリ上に生成されたJITコードの逆アセンブラ確認
JITエンジンが動的にコードを書き込んだアドレス（例: `0x7ffee4000000`）が分かっている場合、そこを直接逆アセンブルする。
(lldb) disassemble –start-address 0x7ffee4000000 –count 10
0x7ffee4000000: 55 push rbp
0x7ffee4000001: 48 89 e5 mov rbp, rsp
0x7ffee4000004: 8b 45 10 mov eax, dword ptr [rbp + 0x10]
0x7ffee4000007: 03 45 18 add eax, dword ptr [rbp + 0x18]
0x7ffee400000a: 5d pop rbp
0x7ffee400000b: c3 ret
お見事。これがメモリ上に生み出されたばかりの機械語（加算を行うシンプルな関数）だ。
3. ブレークポイントの設置と実行
このメモリ上の絶対アドレスに対して直接ブレークポイントを仕掛ける。
(lldb) breakpoint set –address 0x7ffee4000000
Breakpoint 1: where = my_jit_runtime`___lldb_unnamed_symbol1 + 0, address = 0x7ffee4000000
プロセスを再開させ（`continue`）、JIT関数が呼び出されるトリガーを引くと、見事にブレークポイントでヒットする。
(lldb) continue
Process 12345 resuming
Process 12345 stopped
- thread #1, stop reason = breakpoint 1.1
frame #0: 0x00007ffee4000000
-> 0x7ffee4000000: push rbp
0x7ffee4000001: mov rbp, rsp
ここからは、先ほど定義したエイリアスや低レイヤ命令が火を吹く。
レジスタの状態を確認
(lldb) REGS
1命令ずつステップ実行
(lldb) JIT_STEP
(lldb) JIT_STEP
動的に生成されたコードの内部で、どのレジスタにどの値がロードされ、どのように演算が行われているかを完全に手元で掌握できる。
—
おわりに
JITコンパイル環境のデバッグは、一見すると「中身の見えないブラックボックス」に挑む無謀な戦いに思えるかもしれない。しかし、LLDBの内部構造を理解し、Python APIによる拡張、そして適切なコマンドエイリアスと設定をチーム全体で共有することで、そのブラックボックスは「完全に制御可能な透明な領域」へと変わる。
低レイヤの挙動を恐れるな。デバッガを「使う側」から「手なづける側」へシフトした瞬間、あなたの開発スピードとシステムへの理解度は、次元の違う領域へと到達するはずだ。