SPICEを死なせないと決意する

Spice VD Agent for Windows

SPICE 用のコミュニティ主導の Windows ゲストエージェントです。このリポジトリは、放棄された freedesktop.org spice/win32/vd_agent プロジェクトのパブリックミラーです。公式のダウンロードは GitHub Releases で提供されています。

このエージェントは以下の機能を提供します:

• ポインターを掴まずに動作するクライアントマウスモード
• クライアントに合わせたデスクトップ解像度
• クリップボード共有（テキストおよび画像）
• ゲストへのファイル転送
• 各セッションで vdagent.exe を起動する Windows サービス (spice-agent)

状況

Red Hat は SPICE のアップストリームメンテナンスを終了しました。このフォークは、特に Linux 上の Windows 11 VM 向けに、エージェントのビルドと提供を継続します。

ツリーには、d7405ee からのマルチGPUマウス修正（vdagent/desktop_layout.cpp）が含まれています。SPICE ディスプレイデバイスと同時に実際の GPU がパススルーされる場合、エージェントはマウスの動きを失わなくなります。

ライセンスと出所

エージェントは GPL-2.0-or-later です。COPYING および各ソースファイルの著作権ヘッダーを参照してください。元の著作権は Red Hat, Inc. およびその他のアップストリーム作成者に帰属します。このフォークは Red Hat または SPICE の商標を主張しません。

ビルド時にピン留めされたサブモジュール（安易に更新しないでください）:

サブモジュール URL は HTTPS を使用します。MSI アップグレードは、履歴のある WiX UpgradeCode (7eb9b146-db04-42d7-a8ba-71fc8ced7eed) を保持します。関連製品は InstallValidate の後に、インストールトランザクションが開始される前に削除されるため、共有コンポーネントは古いパッケージのアンインストールによって削除されるのではなく、再コピーされます。wixl は PE バージョンリソースを読み取らないため、File テーブルには明示的に RC_FILEVERSION が設定されます。これは VS_VERSION_INFO の4つのフィールドと同一に保つ必要があります。x64 インストーラーは依然として vdagent.exe と vdservice.exe のみを C:\Program Files\SPICE agent\bin に出荷します。

クローン

git clone --recursive https://github.com/nefarius/vd_agent.git
cd vd_agent

サブモジュールなしで既にクローンした場合:

git submodule update --init --recursive

ミラー作成後、freedesktop GitLab リモートは upstream として保持されます。以下でフェッチできます:

git fetch upstream

ローカルビルド (MSYS2 UCRT64)

Autotools + MinGW-w64 UCRT64 パスは、インストーラーを作成するためのサポートされている方法です。CMake + MSVC はローカル開発用に引き続き利用可能ですが、MSI はビルドしません。

前提条件

• MSYS2
• UCRT64 シェル (C:\msys64\ucrt64.exe または MSYSTEM=UCRT64)

UCRT64 シェルで、リポジトリのルートにて:

bash msys2/install.sh
autoreconf -i
bash msys2/build.sh builducrt64
bash msys2/package.sh builducrt64

install.sh は autotools、autoconf-archive、UCRT64 ツールチェーン、msitools (wixl)、および ImageMagick（テスト用）を取得します。PNG クリップボード変換は、Windows Vista 以降に付属する Windows Imaging Component を使用します。

build.sh は設定、vdagent.exe / vdservice.exe のコンパイル、および test-png、test-log、test-shell の実行を行います。その後 package.sh が make msi を呼び出し、以下を書き出します:

builducrt64/spice-vdagent-x64-<version>.msi

バージョン文字列は、build-aux/git-version-gen を介した git describe から取得されます。リリースタグは v0.11.0（マイナーアップデート）のようにする必要があります。これにより、プログラムと機能にタグが正確に表示されます。タグ付けされていないビルドは、最後のタグからのコミット数を追加します（例: v0.11.0 に 83 コミット追加されると 0.11.0.83-<hash> になります）。カウントが --with-buildid と合わせて 256 に達すると、次のマイナーバージョンと衝突するため、Configure は失敗します。

ローカルビルドに署名するには、package.sh の前に 2つの実行可能ファイルに署名し、その後 MSI に署名します。

オプションの MSVC ビルド

git submodule update --init --recursive
cmake -S . -B build64 -A x64
cmake --build build64 --config Release
cmake --build build64 --config Release --target check

CI とリリース

GitHub Actions (.github/workflows/build.yml) は、windows-2022 上で x64 UCRT64 MSI をビルドします。

署名は SignRelay を使用するため、証明書がランナーに配置されることはありません。フローは DsHidMini と一致します:

1. 署名されていないバイナリをビルドしてテストする
2. v* タグで、vdagent.exe と vdservice.exe にインプレース署名する
3. それらのバイナリから MSI をパッケージ化する
4. MSI に署名する
5. Authenticode を検証する (Get-AuthenticodeSignature Status = Valid)
6. <msi>.sha256 を書き出す
7. vdagent-win-x64 をアップロードし、タグ付きの場合は AppVeyorArtifactsReceiver に通知する
8. MSI とチェックサムを GitHub Release にアタッチする

SignRelay コンポジットアクションはコミット 39ccbe0cef16a383237130380a5aef8db040d5d0 にピン留めされています。CLI はランナー上で .NET 10 を必要とします (actions/setup-dotnet with 10.0.x)。

リポジトリ設定

nefarius/vd_agent で作成します（Settings → Secrets and variables）:

SIGN_RELAY_CI_TOKEN と WEBHOOK_URL は、DsHidMini のような既に動作しているリポジトリからコピーしてください。SIGN_RELAY_SERVER はリポジトリ変数として既に設定されています。秘密の値はコミットしないでください。

Windows SignRelay エージェントがコードサイニング証明書を保持します。サブジェクト/サムプリントとタイムスタンプは、このリポジトリではなく、そこで設定します。

リリースの公開

1. CHANGELOG.md を更新する

2. アノテートされたリリースにタグを付け、プッシュする:

   git tag -a v0.11.0 -m "vdagent-win 0.11.0"
   

git push origin v0.11.0
```

3. Build ワークフローを確認する:

   • 署名されていないパスが使用されていないこと
   • 実行可能ファイルと MSI の両方が Valid として検証されること
   • アーティファクトレシーバーがウェブフックを受け入れたこと
   • GitHub Release に MSI と .sha256 が含まれていること

4. Windows 11 SPICE ゲストに MSI をインストールし、以下のチェックリストを実行する

タグ付けされたビルドが署名開始後に失敗した場合、ツリーを修正し、タグを前に進めます（または新しいマイナーバージョンを使用します）。異なるバイトを持つ公開済み MSI 名を再利用しないでください。

失敗したリリースを復旧するには: GitHub Release ドラフトがあれば削除し、新しいタグをプッシュし、ユーザーがダウンロードした可能性のある以前の公開済みタグは不変のままにします。

appveyor.yml は、最後のアップストリーム UCRT64 MSI レイアウトとの履歴的な整合性のためにのみ保持されています。GitHub Actions が権威ある CI です。署名された Actions MSI がスモークテストされたら、AppVeyor を削除してください。

Windows 11 VM 検証

Linux 上の Windows 11 ゲスト（QEMU/KVM + SPICE）で、QXL または qxl-wddm-dod ディスプレイデバイスを使用します。

1. クリーンインストール — 管理者として spice-vdagent-x64-*.msi を実行する
2. サービス — spice-agent が実行中/自動であり、vdagent.exe がユーザーセッションに存在すること
3. SPICE 接続 — virt-viewer / spicy を再接続し、エージェントチャネルがアップしていること
4. クリップボード — テキストとビットマップの両方向での送受信
5. ファイル転送 — クライアントからファイルをドロップし、デスクトップに着地すること
6. 動的解像度 — クライアントウィンドウをリサイズし、WDDM QXL ドライバーが使用されている場合にゲストデスクトップが追従すること
7. マルチGPU / パススルーマウス — パススルー用に実際の GPU を追加し、SPICE ディスプレイを維持し、ポインターが動き続けることを確認する（d7405ee の修正）
8. アップグレード — 以前の Spice エージェント MSI の上にインストールし、サービスが復帰すること
9. アンインストール — 製品を削除し、spice-agent が消えること

オプションの CMake / Fedora ノート

• Fedora クロスビルドは、.gitlab-ci.yml および mingw-spice-vdagent.spec.in 経由で引き続き動作します。これらは GitHub Releases には使用されません。
• x86 MSI ビルドは、メンテナンスされているパイプラインではもはや生成されません。