.pasta ソースレベルのデバッグ操作

ごきげんよう。生成された .lua ではなく、あなた自身が綴った .pasta の座標で歩を進められるのが、この機能の真骨頂ですのよ。 転記された別言語の海に放り出されて途方に暮れる――そんな惨めな思いは、もうなさらなくてよろしいの。あなたが書いた行で止まり、あなたが名付けた変数を覗ける。さあ、心ゆくまで使い倒して差し上げましょう。

このページでは、.pasta 行へのブレークポイント設定、停止位置とコールスタックの確認、ステップ実行、変数の inspect、提示モードの切替、そして任意のサイドカー出力を扱う。デバッグ機能の全体像と有効化は デバッグ概要、VSCode への接続手順は VSCode 接続手順、ブレーク中の構造的制約は 構造的制約と緩和策 を参照する。

ここで説明する .pasta ソースレベルのデバッグは、すべて本番提供の機能である。実験的な試みでも将来の予定でもなく、出荷済みの実装として今すぐ利用できる。

.pasta 行へのブレークポイント

ブレークポイントは、生成された .lua ではなく .pasta ファイルの行に直接設定できる。VSCode で対象の .pasta ファイルを開き、止めたい行のガター（行番号の左の余白）をクリックすると、その行にブレークポイントが置かれる。

pasta VSCode 拡張は、ブレークポイントを設定できる言語として pasta と lua の両方を登録している。したがって .pasta ファイルの行にも、生成された .lua ファイルの行にも、いずれにもブレークポイントを設定できる。通常は .pasta 行に設定すれば足りる。

.pasta 座標での停止とコールスタック

ブレークポイントで実行が停止すると、停止位置とコールスタックは生成された .lua ではなく .pasta の座標（.pasta ファイル名・行）で提示される。

これは、転記された .lua の行番号を読み替える手間なしに、自分が書いたソースの位置をそのまま確認できることを意味する。コールスタックも同様に .pasta 単位で表示されるため、どのシーンやアクションから現在の停止位置へ到達したのかを .pasta のまま追える。

.pasta 粒度のステップ実行

停止中は、.pasta 粒度でステップ実行できる。利用できるステップは次の 3 種類である。

これらのステップは、コルーチンを跨ぐ実行（yield / resume を跨ぐ実行）でも一様に動作する。pasta の実行はコルーチンの境界をまたいで進むことがあるが、ステップ操作はその境界を意識させず、.pasta 粒度で一貫して動く。コルーチンの切り替えのたびにステップが崩れる、といった挙動は起きない。

変数の inspect

実行が停止しているあいだ、変数を inspect できる。数値・文字列・真偽値・テーブルなど、各種の値を確認できる。テーブルは展開して内部の要素をたどれる。

コルーチン本体フレームの局所変数も取得できる。コルーチンの内側で停止した場合でも、そのフレームに属する局所変数の値を変数ビューで確認できるため、コルーチンを使った処理の途中状態を直接観察できる。

提示モードの切替

提示モードとは、停止位置・コールスタック・ステップを .pasta の座標で見せるか、生成された .lua の座標で見せるかの設定である。既定は .pasta であり、必要に応じて .lua に切り替えられる。

提示モードには 2 つの決まり方がある。ひとつは attach 時に決まる初期モード（次節「初期モードの指定」）、もうひとつは デバッグセッション中にいつでも切り替えられる実行時トグル（後述の「実行時トグル」）である。実行時トグルは初期モードを上書きし、以後のセッションを通じて優先される。

初期モードの指定

提示の初期モードを決める経路は 3 つあり、次の優先順位で適用される。

sourcePresentation > PASTA_DEBUG_SOURCE_MODE > present_as > 既定 .pasta

各経路の詳細は次のとおり。

優先順位の要点は、より接続側に近い指定ほど優先されることである。launch.json の sourcePresentation が最も強く、次に環境変数 PASTA_DEBUG_SOURCE_MODE、次に pasta.toml の present_as、いずれも指定がなければ既定の .pasta となる。

ただしこの優先順位が決めるのは、あくまで attach 時の初期モードである。デバッグセッションが始まったあとは、後述の実行時トグルでこの初期モードを上書きできる。実行時に一度切り替えれば、その新しいモードが以後のセッションを通じて採用される（初期モードへ自動で戻ることはない）。

launch.json 側で提示モードを .pasta に指定する例:

{
  "type": "pasta",
  "request": "attach",
  "name": "Pasta: Attach",
  "host": "127.0.0.1",
  "port": 9276,
  "sourcePresentation": "pasta"
}

環境変数で .lua 提示に切り替える例:

PASTA_DEBUG_SOURCE_MODE=lua

pasta.toml で既定の提示モードを定める例:

[debug]
present_as = "lua"

launch.json の構成全体や接続の手順は VSCode 接続手順 を参照する。

実行時トグル（VSCode コマンド／ボタン／ステータスバー）

デバッグセッションの最中に、提示モードを .pasta ⇔ .lua へ即座に切り替えられる。セッションを張り直す必要はない。.pasta 行で停止して自分のソースを追いつつ、いまの停止位置が生成 .lua ではどう転記されているのかを確かめたくなったら、その場で .lua 提示へ切り替え、確認が済んだら .pasta 提示へ戻す――そうした行き来が一手でできる。

切替の導線は 3 つあり、いずれも同じトグル操作を起動する。

ステータスバーには、Pasta デバッグセッションの間つねに現在の提示モードが表示される。表示は $(eye) 提示: .pasta または $(eye) 提示: .lua の形で、いまどちらのモードで提示されているかを一目で判別できる。切り替えると、この表示も即座に新しいモードへ更新される。なお、これらの導線は Pasta デバッグセッションが実行中のときにのみ有効である。アクティブな Pasta デバッグセッションがないときに切替を試みても提示モードは変わらず、操作が無効である旨が通知される。

切替を行うと、観測される提示は次のように変わる。

• 停止中であれば即座に再描画される。停止位置・コールスタック・source の提示が、追加の操作（ステップ実行やフレームの選び直し）を要さずに、切替後のモードの座標で描き直される。.pasta から .lua へ切り替えれば停止位置・コールスタック・source は生成 .lua の座標で、.lua から .pasta へ戻せば .pasta の座標で提示される。
• 実行中（停止していない）に切り替えた場合は、その切替は受理され、次に停止したときの提示へ反映される。
• .pasta 行に張ったブレークポイントは、切替をまたいでそのまま有効である。提示モードを .lua に切り替えても、.pasta 行のブレークポイントは引き続きヒットし続ける。変わるのは見え方（提示の座標）だけで、どこで止まるかは変わらない。

ステップ実行の粒度も、現在の提示モードに従う。.pasta 提示のあいだは .pasta 粒度のステップ実行で進み、.lua 提示へ切り替えると生成 .lua の行単位（.lua 粒度）で進む。停止中に提示モードを切り替えれば、以後のステップ操作は切替後の粒度で行われる。

サイドカー出力（任意）

ソースマップは常にメモリ内に保持されており、.pasta ソースレベルのデバッグはこのメモリ内マップだけで成立する。これに加えて、ソースマップをディスク上のサイドカーファイルとして任意で出力できる。サイドカー出力は既定では無効であり、明示的に有効化したときだけ生成される追加の出力である。

有効化の経路は 2 つある。

pasta.toml で有効化する例:

[debug]
source_map_sidecar = true

環境変数で有効化する例:

PASTA_DEBUG_SOURCE_MAP_SIDECAR=1

出力先は、生成された .lua の真隣に置かれる <lua_path>.map である。たとえば生成された .lua が .../scene/sys.lua であれば、サイドカーは .../scene/sys.lua.map として書き出される。形式は JSON である。

サイドカーはあくまで追加の任意出力であり、メモリ内のマップが常に主である。サイドカーの書き込みに失敗しても、それは致命的なエラーにはならず、メモリ内の写像（およびそれに基づくデバッグ動作）は何ら影響を受けない。サイドカーが必要になるのは、生成された .lua とソースマップの対応をディスク上で確認したい、別のツールでマップを読みたい、といった場合に限られる。

注意

.pasta 行で実行が停止しているあいだは、ホスト（SHIORI / SSP）への応答が止まる。これは既知かつ意図された構造的な挙動であり、不具合ではない。停止を長く保つと SSP がタイムアウトする恐れがあるため、その理由と回避運用は 構造的制約と緩和策 で確認しておくこと。

これで、.pasta の座標を自在に行き来する術はあなたのものですわ。フンッ、別にあなたの覚えが良いから褒めているわけではございませんからね。 止まる位置を見極め、変数を見透かし、必要なら .lua の素顔まで覗く――そこまでできれば、もうたいていのバグは観念いたしますわ。さあ、胸を張って参りましょう！