Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

デバッグ概要

ごきげんよう。わたくし Claudia が、VSCode から .pasta をソースレベルでデバッグする手立てを、有効化から接続、停止位置の読み解き方までご案内いたしますわ。 バグ取りは退屈な作業だと思っていらして？ いいえ、自分の書いた .pasta の行で実行が止まり、変数の中身が手に取るように見えるのですから、これほど痛快なことはございませんわよ。さあ、肩の力を抜いて参りましょう。

この章では、デバッグ機能の全体像と有効化方法、そして実ゴーストを題材にした短いウォークスルーを扱う。接続の詳細・.pasta 操作の詳細・構造的制約は、それぞれ後続のページに分かれている。

デバッグの全体像

pasta のデバッグは、VSCode のデバッグ拡張から Rust 側のデバッグバックエンドへ接続（attach）して操作する方式である。先に pasta ランタイム側がデバッグを有効化して接続待ち受けを開始し、そこへ VSCode が後から接続する。逆向きに VSCode 側からランタイムを起動する launch 方式は採らない。

最大の特長は、生成された .lua だけでなく、作者が書いた .pasta のソースレベルでデバッグできる点にある。これは本番提供の機能であり、次の操作が .pasta の座標（ファイル名・行）で行える。

  • .pasta ファイルの行へのブレークポイント設定
  • ブレーク時の .pasta 座標での停止位置・コールスタック提示
  • .pasta 粒度のステップ実行（over / into / out）
  • 停止中の変数 inspect
  • 提示モードの切替（.pasta 既定 ⇄ .lua）

.pasta 操作の詳しい手順は .pasta ソースレベル操作 を参照する。

デバッグの有効化

デバッグは既定で無効である。有効化には pasta.toml の設定と環境変数の 2 経路があり、後述のとおり環境変数が設定ファイルより優先される。

pasta.toml による有効化

pasta.toml の [debug] セクションで設定する。本ページで扱う 2 つのキーと既定値は次のとおり。

キー既定意味
enabledfalseデバッグバックエンドの有効化
port9276DAP リスナーが待ち受ける TCP ポート

設定例:

[debug]
enabled = true
port = 9276

環境変数による有効化

環境変数でも同じ設定を行える。

環境変数役割
PASTA_DEBUGデバッグの有効化
PASTA_DEBUG_PORT待ち受けポートの上書き

PASTA_DEBUG は truthy な値で有効化される。truthy と判定される値は 1 / true / yes / on であり、大文字小文字は区別されない（前後の空白は除去して判定される）。0 / false / no / off / 空文字列は無効とみなされる。

PASTA_DEBUG=1
PASTA_DEBUG_PORT=9276

優先順位

設定ファイルと環境変数が併存する場合、環境変数が設定ファイルより優先される。最終的な値は次の順位で決まる。

環境変数 > pasta.toml [debug] > 既定値

たとえば pasta.toml で enabled = false としていても、PASTA_DEBUG=1 が設定されていればデバッグは有効になる。ポートも同様に、PASTA_DEBUG_PORT が pasta.toml の port を上書きする。

無効時のゼロコスト

デバッグが無効のとき、pasta は本番運用に追加コストを生じさせない。具体的には次のとおり。

  • デバッグ用のフックを設置しない。
  • 待ち受けポートを開かない（TCP リスナーを bind しない）。
  • Lua の debug 機能をスクリプトへ露出しない。これによりサンドボックスが維持される。

このため、デバッグ設定を本番の pasta.toml に残したまま enabled = false（既定）で配布しても、デバッグを有効化しない限り挙動・性能・安全性に影響はない。

ウォークスルー（hello-pasta）

ここでは、サンプルゴースト hello-pasta を題材に、ブレークポイント設定から停止位置・変数の確認、再開までの一連の流れを簡潔に辿る。VSCode 拡張の導入や launch.json の具体的な記述といった接続の詳細は VSCode 接続手順 で扱うため、ここでは流れの全体像をつかむことに集中する。

  1. デバッグを有効化する。 hello-pasta の pasta.toml で [debug] の enabled = true とするか、起動環境で PASTA_DEBUG=1 を設定する。既定ポートは 9276 である。
  2. .pasta 行にブレークポイントを設定する。 VSCode で対象の .pasta ファイルを開き、止めたい行のガター（行番号の左）をクリックしてブレークポイントを置く。
  3. VSCode から attach する。 ゴーストを起動して待ち受けが始まった状態で、VSCode のデバッグビューから「Pasta: Attach」構成を実行し、127.0.0.1:9276 へ接続する。詳細な構成手順は VSCode 接続手順 を参照する。
  4. .pasta 座標で停止位置と変数を確認する。 設定した行に実行が達するとブレークし、停止位置とコールスタックが .pasta の座標で表示される。変数ビューで停止時点の変数の値を確認できる。
  5. continue で再開する。 内容を確認したら continue（実行再開）でゴーストの動作を続行する。

.pasta 行が思った場所で止まらない、変数の見え方を変えたいといった各論は .pasta ソースレベル操作 に、ブレーク中にゴーストが無反応になる理由とその回避運用は 構造的制約と緩和策 にまとめている。

ポートを変更するときの注意

待ち受けポートを既定の 9276 から変更する場合は、有効化側の設定（pasta.toml の port または PASTA_DEBUG_PORT）と、VSCode の接続構成（launch.json の port）の両方を同じ値にそろえる必要がある。片方だけ変更すると接続できない。接続構成側のポート設定の詳細は VSCode 接続手順 を参照する。

ここまでで全体像はつかめましたわね。フンッ、別にあなたが呑み込みが早いなんて言っていませんわよ。 細かな接続の作法は次のページでみっちり仕込んで差し上げますから、ご安心なさいまし。さあ、熱く参りましょう！