vvvv-debugging

vvvv gamma C# プロジェクトのデバッグ

CLI 引数とセッションファイルについては、vvvv-startup スキルを参照してください。

コンテキスト対応セットアップワークフロー

ユーザーがデバッグのセットアップを依頼した場合は、次のワークフローに従ってください。ファイルを生成する前に、AskUserQuestion を使用してすべての設定に関する質問を事前に行ってください。デフォルト値を前提とせず、必ずユーザーに確認してください。

1. vvvv のインストールを検出する

C:\Program Files\vvvv\ をスキャンして vvvv_gamma_* ディレクトリを探し、vvvv.exe を自動的に見つけます。

ls -d "/c/Program Files/vvvv/vvvv_gamma_"* 2>/dev/null | sort -r

ディレクトリ名の形式は vvvv_gamma_MAJOR.MINOR[-BUILD-gHASH-PLATFORM] です。バージョンの降順で並べ替えます。安定版が存在しない場合を除き、-beta、-alpha、-rc、-test、-dev の各バリアントは除外してください。

2. ワークスペースをスキャンする

ワークスペースに存在するものを検出します。

• .csproj / .sln ファイル（ビルドタスクが必要な場合と不要な場合があります — 手順 3 を参照）
• .vl ファイル（--open の候補）
• help/ フォルダー（テストパッチの一般的な場所）
• 既存の .vscode/launch.json（上書きせず拡張する）
• Git サブモジュール（特に VL.StandardLibs — 後述のパッケージリポジトリに関する警告を参照）
• リポジトリのフォルダー名、メインの *.vl ファイル、または .csproj の <PackageId> から取得したパッケージ名（--editable-packages 用）

3. ユーザーへの質問 — 生成前にすべての質問を行う

重要: 設定を生成する前に、AskUserQuestion を使用してこれらの質問をすべて行ってください。 複数質問形式を使用して、関連する質問をまとめてください。すべての回答が集まるまで launch.json を生成しないでください。

質問グループ 1: vvvv のバージョンとパッチ

• どの vvvv バージョンを使用しますか? — 検出されたバージョンを提示し、最新の安定版を推奨します。ユーザーに選択させるか、カスタムパスを指定させます。
• どの .vl パッチを開きますか? — 見つかった .vl ファイルを選択肢としてリストします。help/ フォルダーが存在する場合は、そこにあるものを提案します。

質問グループ 2: 起動フラグ

• --debug フラグ? — ブレークポイント用のデバッグシンボルを有効にしますが、パッチ適用が遅くなります。質問: 「ブレークポイントのために --debug を有効にしますか?（起動が遅くなります）」デフォルト: 高速な反復作業ならいいえ、ユーザーが明示的にブレークポイントを希望する場合ははい。
• --allowmultiple? — 2 つ目の vvvv インスタンスの起動を許可します。質問: 「複数の vvvv インスタンスを許可しますか? いいえの場合、vvvv がすでに実行中のときは起動が失敗します（古いインスタンスの検出に便利です）。」デフォルト: いいえ。
• --package-repositories? — パッケージをスキャンするフォルダーを vvvv に指定します。警告: ワークスペースに VL.StandardLibs/ のような Git サブモジュールが含まれている場合、--package-repositories ${workspaceFolder} を使用すると、vvvv がすべてのコアライブラリをソースから再コンパイルし、数分かかります。 質問: 「--package-repositories を追加しますか? vvvv がパッケージを見つけられない場合にのみ必要です。警告: リポジトリに VL.StandardLibs やその他のライブラリサブモジュールがある場合、完全な再コンパイルが発生します。」デフォルト: いいえ。
• --editable-packages? — 指定したパッケージをソースから読み込みます。--package-repositories と併用する場合にのみ有効です。package-repositories が有効な場合にのみ質問してください。

質問グループ 3: ビルドモード

• ソース参照または DLL? — 「.vl ドキュメントは .csproj を直接参照していますか（ソース参照、最も一般的）、それともビルド済みの DLL を参照していますか?」ソース参照 = ビルドタスク不要。DLL = preLaunchTask: "build" を追加。

4. 設定を生成する

すべての質問に回答があった後にのみ、.vscode/launch.json と、必要に応じて .vscode/tasks.json を生成します。

常に次の構成を生成してください:

1. ユーザーが選択したフラグを含む起動構成
2. すでに実行中のインスタンスにアタッチするための「Attach to vvvv」構成

必要に応じて生成するもの:

• 最初の構成に --debug がない場合（またはその逆の場合）、--debug を含む 2 つ目の起動構成
• DLL / バイナリのビルドモードが選択された場合の tasks.json

VS Code launch.json

最小構成（ソース参照、追加設定なし）

可能な限りシンプルな構成 — パッチを開くだけです:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "vvvv — MyPatch",
      "type": "coreclr",
      "request": "launch",
      "program": "C:\\Program Files\\vvvv\\vvvv_gamma_7.1-win-x64\\vvvv.exe",
      "args": [
        "-o",
        "${workspaceFolder}/help/HowTo Use MyFeature.vl"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "internalConsole"
    },
    {
      "name": "Attach to vvvv",
      "type": "coreclr",
      "request": "attach",
      "processName": "vvvv.exe"
    }
  ]
}

完全な構成（すべてのオプションフラグ付き）

ユーザーがすべてのフラグを選択した場合:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with vvvv",
      "type": "coreclr",
      "request": "launch",
      "program": "C:\\Program Files\\vvvv\\vvvv_gamma_7.0-win-x64\\vvvv.exe",
      "args": [
        "--package-repositories",
        "${workspaceFolder}",
        "--editable-packages",
        "VL.MyPackage*",
        "-o",
        "${workspaceFolder}/help/HowTo Use MyFeature.vl",
        "--debug",
        "--allowmultiple"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "internalConsole"
    },
    {
      "name": "Attach to vvvv",
      "type": "coreclr",
      "request": "attach",
      "processName": "vvvv.exe"
    }
  ]
}

DLL/バイナリ参照（外部ビルドが必要）

vvvv を起動する前に C# をビルドするため、preLaunchTask を追加します：

{
  "name": "Debug with vvvv (pre-build)",
  "type": "coreclr",
  "request": "launch",
  "preLaunchTask": "build",
  "program": "C:\\Program Files\\vvvv\\vvvv_gamma_7.0-win-x64\\vvvv.exe",
  "args": [
    "-o",
    "${workspaceFolder}/help/HowTo Use MyFeature.vl",
    "--debug"
  ],
  "cwd": "${workspaceFolder}",
  "stopAtEntry": false,
  "console": "internalConsole"
}

重要なポイント：

• ソース参照の場合は preLaunchTask を省略 -- vvvv は Roslyn を介して C# のコンパイルを処理します
• DLL/バイナリ参照や複雑なビルドシナリオの場合のみ preLaunchTask: "build" を追加 します
• --debug はデバッグシンボルを有効にします（ブレークポイントに必要ですが、パッチ適用は遅くなります）
• --package-repositories は vvvv にパッケージの場所を伝えます — 警告: スキャンされたフォルダーツリー内で見つかったすべての VL ライブラリサブモジュールが再コンパイルされます
• --editable-packages は指定されたパッケージをソースから読み込みます（glob パターンをサポート）
• -o は起動時に指定された .vl パッチを開きます
• --allowmultiple は 2 つ目の vvvv インスタンスを許可します — 省略すると古いインスタンスを検出します
• 可読性のために、args には（単一の文字列ではなく）配列項目を使用してください

実行中の vvvv にアタッチ

vvvv がすでに実行中で、再起動せずにデバッグしたい場合はアタッチを使用します：

{
  "name": "Attach to vvvv",
  "type": "coreclr",
  "request": "attach",
  "processName": "vvvv.exe"
}

VS Code の tasks.json（DLL/バイナリ参照のセットアップ専用）

プロジェクトが外部ビルドを必要とする場合（DLL 参照、ネイティブ依存関係、Release ビルド）にのみ tasks.json を生成してください。vvvv が実行時に C# をコンパイルするソースプロジェクト参照の場合は、これを完全に省略してください。

dotnet でビルド

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
      "args": ["build", "${workspaceFolder}/src/MyProject.csproj", "-c", "Debug"],
      "problemMatcher": "$msCompile",
      "group": { "kind": "build", "isDefault": true }
    },
    {
      "label": "build-release",
      "command": "dotnet",
      "type": "process",
      "args": ["build", "${workspaceFolder}/src/MyProject.csproj", "-c", "Release"],
      "problemMatcher": "$msCompile"
    }
  ]
}

MSBuild でビルド（.sln、または Visual Studio ツールチェーンを必要とするプロジェクト向け）

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "& 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\MSBuild\\Current\\Bin\\MSBuild.exe' '${workspaceFolder}/src/MyProject.sln' -p:Configuration=Debug -p:Platform=x64 -t:Rebuild -v:minimal",
      "options": {
        "shell": { "executable": "powershell.exe", "args": ["-Command"] }
      },
      "problemMatcher": "$msCompile",
      "group": { "kind": "build", "isDefault": true }
    }
  ]
}

プロジェクトが MSBuild 固有の機能や、プラットフォームターゲットを持つ .sln を必要としない限り、dotnet build を優先してください。

Visual Studio のセットアップ

外部プログラムによるデバッグ

1. Visual Studio で .csproj を開きます
2. デバッグ > デバッグプロパティ（または プロジェクトプロパティ > デバッグ > 全般）
3. 新しい起動プロファイルを作成します：
   • コマンド: vvvv.exe のパス
   • コマンドライン引数: -o YourPatch.vl（ブレークポイントが必要な場合は --debug を追加）
   • 作業ディレクトリ: プロジェクトフォルダー
4. F5 を押してデバッガーをアタッチした状態で起動します

プロセスにアタッチ

1. vvvv を通常どおり起動します（ブレークポイントが必要な場合は --debug を追加）
2. デバッグ > プロセスにアタッチ（Ctrl+Alt+P）
3. プロセス一覧から vvvv.exe を見つけます
4. コードの種類として マネージド (.NET Core, .NET 5+) を選択します
5. アタッチをクリックします

launchSettings.json（dotnet ツール）

{
  "profiles": {
    "Debug vvvv": {
      "commandName": "Executable",
      "executablePath": "C:\\Program Files\\vvvv\\vvvv_gamma_6.8-win-x64\\vvvv.exe",
      "commandLineArgs": "-o YourPatch.vl",
      "workingDirectory": "$(ProjectDir)"
    }
  }
}

デバッグのヒント

• --debug -- 信頼性の高いブレークポイントのためにデバッグシンボルの出力を強制しますが、オーバーヘッドが追加されます。Debug 構成で使用し、パフォーマンス/デプロイのテストでは省略してください。
• --stoppedonstartup -- 一時停止した状態で起動するので、Update() が実行される前にブレークポイントを設定できます
• --nocache -- ブレークポイントがバインドされない場合は、ソースからの再コンパイルを強制します
• Debugger.Break() -- C# コードに追加して、プログラムでブレークポイントをトリガーします
• Update() 内の条件付きブレークポイント -- Update() は毎フレーム実行されるため、ヒット数や条件を使用してください
• コンストラクターのブレークポイント -- ライブリロードのサイクルごとにも発生します（Dispose の後に新しいコンストラクター）
• console: "internalConsole" -- VS Code のデバッグコンソールで Console.WriteLine の出力をキャプチャします
• デバッガーアタッチ時の動作 -- .NET デバッガーがアタッチされていると、vvvv の初期化は同期的に実行されるため（非同期の例外トラップなし）、起動時のブレークポイントが確実に機能します

よくある落とし穴

• ランタイムのティックとドキュメントのティックでは所有者が異なります。 プロセス全体の SDK ではランタイム全体に対して 1 つのティックが必要になる場合がありますが、各ドキュメントには独自のフレームクロックがあります。インストールされているランタイムの Update/Draw/Present シーケンスを追跡し、コールバックが実際にどこで実行されるかを検証してください。フレーム終了という名前だけでは、after-Present フックであることの証明にはなりません。個々のゲームシステムの EndDraw は、すべてのシステムがレンダリングを完了したことの証明にはなりません。共有 SDK のフレーム識別子を、定数、リソースタグ、マーカー全体で一貫させてください。

• チェックアウトした API は、インストールされている公開 API と異なる場合があります。 プラグインやテストハーネスを作成する前に、対象のアセンブリバージョン、メンバーの可視性、実際に出力される API を確認してください。逆コンパイルされたコードに見える内部ランタイムメソッドが、パッケージから呼び出せるとは限りません。サポートされている公開エントリポイントを使用してください。

• C++/CLI のソースはマネージド IL を出力することがあります。 /clr:netcore では、デバッガーを選択する前に、対象メソッドの出力を確認してください。ネイティブシンボルが一致していても、マネージドメソッドではネイティブソースのブレークポイントがバインドされないままになることがあります。デバッガー式の評価に失敗したからといって、そのメソッドが一度も実行されなかったことの証明にはなりません。混在モードの評価が利用できない場合は、アクセス可能なマネージド呼び出し元の状態を確認してください。

• ネイティブ Windows PDB は、読み込まれたバイナリと正確に一致している必要があります。 DLL の CodeView RSDS GUID と age を、PDB の識別情報と比較してください。ファイル名が一致していても、シンボルディレクトリを追加しても、識別情報の不一致は解消されません。ビルドした成果物だけでなく、読み込まれたモジュールのパスも確認してください。

• メモリカウンターは、それぞれ異なる所有権スコープを測定します。 プロセスごとの専用 GPU 使用量とアダプター全体の使用量は別の量であり、共有リソースや常駐状態が帰属に影響することがあります。カウンターの不一致だけでは、リークを証明することも、説明のつかない増加を否定することもできません。割り当て/解放のライフタイム、GPU フェンスの進行状況と常駐状態を関連付け、調査中もメモリ予算を有効に保ってください。

• --package-repositories + VL.StandardLibs サブモジュール — ワークスペースに VL.StandardLibs/ git サブモジュールがある場合（vvvv の contrib リポジトリでよく見られます）、--package-repositories ${workspaceFolder} を指定すると、vvvv がすべての標準ライブラリをソースから検出して再コンパイルします。これには何分もかかり、望む結果になることはほぼありません。--package-repositories を省略するか、ライブラリのサブモジュールを含まない特定のサブフォルダを指定してください。

• --allowmultiple が古いインスタンスを隠す — このフラグがないと、別のインスタンスが実行中の場合に vvvv は起動を拒否します。これは有用で、古い vvvv プロセスがあることを知らせてくれます。--allowmultiple を使うと、誤って 2 つのインスタンスを実行し、リソースを二重に消費してしまう可能性があります。

• --debug がすべてを遅くする — デバッグシンボルの出力は、vvvv のライブコンパイルを大幅に遅くします。ブレークポイントが本当に必要なときだけ有効にしてください。素早い反復（UI のテスト、動作の確認）では省略してください。

このナレッジを育て続けましょう

次にパッチを当てる人の謎を1つ減らしましょう。このコレクション内のスキルを初めて使用する際、7日以内に成功したチェックがない場合は、ソースを tebjan/vvvv-skills と比較してください。記録が存在しない場合は、一度だけチェックしてください。 これらのスキル全体で、ローカルのチェックのタイムスタンプ/リビジョンを1つ共有してください。呼び出しごとにポーリングしないでください。 ローカルの拡張機能と固定されたプロジェクトバージョンは保持してください。チェックすることは、更新をインストールする許可ではありません。オフラインの場合は、延期されたチェックを記録し、タスクを続行してください。

実際の作業でギャップが明らかになった場合は、テスト済みの vvvv/パッケージのバージョン、最小限の再現または信頼できる情報源、および観察された結果を記録してください。他のユーザーの報告は、検証されるまでは事実ではなく手がかりとして扱ってください。最も小さく関連する指示を改善してください。1つの例を普遍的なルールにしないでください。プライベートデータを編集で除去し、アップストリームに提出する前に公開の許可を取得してください。 コントリビューションポリシーをご覧ください。 マージされた改善は、ローカルの編集や全員のスキルの自動上書きではなく、ユーザーのインストーラー/アップデートワークフローを通じてユーザーに届きます。