パッケージングとリリースレイアウト

ドキュメントのバージョン v0.1.0-beta.3GitHub でソースを見る

このページは OmsiLaunch 0.1.0-beta3 の英語版の原文ページの翻訳です。規範となるのは英語版です。内容が異なる場合は、英語版のページとコードが優先されます。

このページでは、OmsiLaunch 0.1.0-beta3 のリリースパッケージについて説明します。tools\New-ReleasePackage.ps1 が生成するもの、release-manifest.json のフィールド、コントローラーが実行時にマニフェストを使って常駐プラグインのクロージャーを検証する方法、OMSI のインストールルートへのパッケージのインストールと削除の方法、使用後に .omsilaunch ディレクトリに含まれるもの、および検証スクリプト（tools\Test-ReleaseIdentity.ps1、tools\Test-ReleasePresentation.ps1、tools\Invoke-OfflineValidation.ps1）を扱います。製品のアイデンティティは OmsiLaunch.Version.props から取得されます。利用者向けのインストール手順は インストール を、プラグインクロージャーの実行時の役割は 常駐プラグイン を参照してください。

製品アイデンティティ（OmsiLaunch.Version.props）#

Directory.Build.props は InformationalVersion をソースリビジョンなしで OmsiLaunchProductVersion に設定するため、OmsiLaunch.exe /version は正確に 0.1.0-beta3 を出力します。

ビルド（tools\New-ReleasePackage.ps1）#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished]（既定の出力先は artifacts\release）は、ビルド済みの成果物からパッケージをステージングします。OmsiLaunch-<product_version>.zip がすでに存在する場合、-AllowOverwritePublished を指定しない限り artifacts\release への書き込みは拒否されます。候補パッケージは別のディレクトリに出力します（オフライン検証では artifacts\candidate\post-round-a を使用します）。

ステージングの前に、すべてのビルド出力が古くなっていないかチェックされます。

• OmsiLaunch.Native.x86.dll: タイムスタンプではなく内容で判定します。 ネイティブビルドは artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt（.vcxproj 内のターゲット WriteOmsiLaunchNativeBuildReceipt）を書き出します。これには、生成した DLL の SHA-256（output=）と、ビルド元となったすべてのソース（source=<sha256>|<path>: .cpp、.rc、.vcxproj および OmsiLaunch.Version.props）の SHA-256 が記録されます。パッケージングは、DLL のハッシュが記録された出力と一致しない場合（does not match its build receipt: タイムスタンプにかかわらず、古いコピーまたは別のビルドのコピー）、記録されたソースが変更された場合（Native source changed after the recorded build）、レシートに含まれないネイティブソースがある場合、またはレシートが存在しない場合に、その DLL を拒否します。
• シムとマネージドアセンブリ: タイムスタンプで判定します。 それぞれ、自身のプロジェクトのソース（各シムの .cpp/.rc/.vcxproj、各マネージドアセンブリ自身のプロジェクト）より古くてはなりません。古い入力があると、Stale build artifact でパッケージングが中止されます。

その後、パッケージは一意の名前を持つ新規のステージングディレクトリ（出力ディレクトリ内の .staging-<guid>）で組み立てられるため、以前の実行で残ったファイルがクロージャーに入り込むことはありません。以前の OmsiLaunch-current フォルダーとアーカイブは、以下のすべてのチェックに合格した後にのみ置き換えられます。

続いてスクリプトは、ステージングされたすべてのファイルのハッシュを計算し、パッケージルートに release-manifest.json を BOM なしの UTF-8 で書き出し（結果は PowerShell のエディションに依存しなくなりました）、ステージに対して Test-ReleasePackageIntegrity.ps1 を実行し、ステージングされた各プラグインファイルと OmsiLaunch.Native.x86.dll をビルド出力と再比較し、ステージを圧縮し、アーカイブを新しい一時ディレクトリに展開して、展開されたクロージャーを同じマニフェストに照らして検証します（アーカイブ内のマニフェストは検証済みのマニフェストとバイト単位で一致している必要があります）。その後、ステージを OmsiLaunch-current として、アーカイブを OmsiLaunch-current.zip として公開し、それを OmsiLaunch-<product_version>.zip（OmsiLaunch-0.1.0-beta3.zip）にコピーして、<SHA-256> <file name> を含む OmsiLaunch-0.1.0-beta3.zip.sha256 を書き出します。成果物が 1 つでも欠けているとスクリプトは中止されます。このスクリプトはビルドを行いません。先に Invoke-OfflineValidation.ps1（または個別の dotnet build / MSBuild の手順）を実行してください。

パッケージレイアウト#

OmsiLaunch.exe                       console shim (x64 native)
OmsiLaunchW.exe                      Windows-subsystem shim (x64 native)
nethost.dll                          .NET host locator used by both shims
OmsiLaunch.Controller.dll            managed controller (x64, net6.0-windows)
OmsiLaunch.Controller.deps.json
OmsiLaunch.Controller.runtimeconfig.json   requires Microsoft.NETCore.App 6.0 + Microsoft.WindowsDesktop.App 6.0
OmsiLaunch.Api.dll  OmsiLaunch.Core.dll  OmsiLaunch.Process.dll  OmsiLaunch.Configuration.dll
OmsiLaunch.Content.dll  OmsiLaunch.Builds.Omsi23004.dll  YamlDotNet.dll
LICENSE  THIRD-PARTY-NOTICES.md
release-manifest.json                package inventory and expected plugin hashes
plugins\                             the permanent plugin closure (9 files, all named OmsiLaunch.*)
  OmsiLaunch.Plugin.opl              OMSI plugin descriptor
  OmsiLaunch.PluginNE.dll            native export shim loaded by OMSI (x86)
  OmsiLaunch.Plugin.dll              managed plugin (x86, net6.0-windows)
  OmsiLaunch.Plugin.deps.json  OmsiLaunch.Plugin.runtimeconfig.json   requires Microsoft.NETCore.App 6.0 (x86)
  OmsiLaunch.Api.dll  OmsiLaunch.Builds.Omsi23004.dll  OmsiLaunch.Interop.dll   x86 copies
  OmsiLaunch.Native.x86.dll          native bridge (loaded from plugins\ only)
.omsilaunch\
  assets\splash\{PTB,ENG,DEU,FRA}.bmp   640x480 24-bit managed splash assets
  docs\                               English documentation (README.md, getting-started\, reference\, concepts\, status\, ...)
  docs\localized\<locale>\             translations of the 0.1.0-beta3 pages (not normative)
  examples\release-session.example.json
  examples\session-profiles\rmg-leste\profile.yaml

製品が所有するのは、ルートの製品ファイル、plugins\OmsiLaunch.* および .omsilaunch\ のみです。plugins\ 配下のサードパーティ製プラグインを、OmsiLaunch が列挙、コピー、ハッシュ計算、削除、復元することは一切ありません。

release-manifest.json#

マニフェストはデータであり、実行可能なポリシーではありません。コントローラーが読み取るのは plugins/ のエントリのみです。リーダーは UTF-8 BOM の有無にかかわらずファイルを受け付けます（この修正以前に Windows PowerShell 5.1 で書き出されたマニフェストには BOM が付いています）。

マニフェストの実行時の利用（プラグインの整合性）#

プランの作成と開始のたびに、OmsiLaunchService.LoadArtifacts は想定されるプラグインクロージャーを構築します（RuntimeArtifactSet.Load、src\OmsiLaunch.Process\RuntimeDeployment.cs）。

1. コントローラーは OmsiLaunch.exe と同じ場所（AppContext.BaseDirectory）で release-manifest.json を探します。存在する場合、ReleaseManifest.TryReadPluginHashes が plugins/* のハッシュを取り出します（ファイルをマニフェストとして読み取れない場合は OL_E_RELEASE_MANIFEST_INVALID）。
2. インストールされている各ファイル <root>\plugins\OmsiLaunch.* のハッシュ（SHA-256）を計算し、次のように比較します。
   • マニフェストがある場合: マニフェストのハッシュと比較し、プラン診断 plugin.integrity.reference = manifest を記録します。ファイルがない → OL_E_PERMANENT_PLUGIN_MISSING、ファイルはあるがマニフェストに記載されていない → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE、ハッシュが異なる → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH（reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree）。
   • マニフェストがない場合（開発用レイアウト、またはマニフェストを省いたインストール環境）: 存在と、コントローラーと同じ場所にあるパッケージ内のコピーとの自己整合性のみをチェックできます。plugin.integrity.reference = self となります。
3. 失敗すると、プランは実行不可とマークされる（詳細付きの OL_E_RUNTIME_ARTIFACT_MISSING）か、開始が拒否されます（終了コード 7）。

プラグインファイルがセッションによってステージング、スナップショット取得、復元、削除されることはありません。クロージャーはインストール環境の恒久的な一部です。x86 の OmsiLaunch.Native.x86.dll は plugins\ からのみ読み込まれ、マネージドアセンブリは DefaultDllImportSearchPaths(AssemblyDirectory | System32) を宣言しています。

OMSI ルートへのインストール#

1. アーカイブを検証します。OmsiLaunch-0.1.0-beta3.zip を OmsiLaunch-0.1.0-beta3.zip.sha256 と照合してください。
2. アーカイブを OMSI のインストールルート（Omsi.exe があるディレクトリ）に直接展開します。これにより、ルートのファイル、plugins\OmsiLaunch.*（サードパーティ製プラグインと並んで配置）および .omsilaunch\ が配置されます。
3. release-manifest.json は OmsiLaunch.exe と同じ場所に置いたままにしてください。これによりマニフェストベースのプラグイン整合性チェックが有効になります。マニフェストとバイナリは同じパッケージのものでなければなりません。古いマニフェストの上に新しいバイナリを置く（またはその逆の）場合、すべての開始が OL_E_PERMANENT_PLUGIN_HASH_MISMATCH で失敗します。Test-ReleasePresentation.ps1 -InstallPackage は現在、製品ファイルと一緒にマニフェストもコピーします。以前はマニフェストをスキップしていたため、新しいバイナリの横に古いマニフェストが残っていました（Round A RA-007）。
4. tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root> で整合性を読み取り専用でチェックします。installation_comparison.coherent_with_package が true でなければなりません。
5. プラグインのバイナリを .omsilaunch\ に移動したり、plugins\OmsiLaunch.* の名前を変更したりしないでください。
6. OmsiLaunch.exe /version、OmsiLaunch.exe profiles および /plan で確認します（最初のセッション を参照）。

既存の .omsilaunch\assets\splash\*.bmp ファイルがセッションによって上書きされることはありません（明示的に管理されたアセットセットは保持されます）。新しいパッケージを展開してこれらを上書きすることは、利用者による意図的な操作です。

使用後の .omsilaunch ディレクトリ#

データがマシンの外に送信されることはありません。トランザクションとリカバリ を参照してください。

アンインストール#

1. 実行中のセッションがないこと（OmsiLaunch.exe detect、OmsiLaunch.exe session status）と、保留中のリカバリがないこと（OmsiLaunch.exe /recovery-status。pending が true の場合は /recover を実行）を確認し、OMSI のファイルがすでに復元された状態にします。
2. plugins\OmsiLaunch.Plugin.opl、plugins\OmsiLaunch.PluginNE.dll、plugins\OmsiLaunch.Plugin.dll、plugins\OmsiLaunch.Plugin.deps.json、plugins\OmsiLaunch.Plugin.runtimeconfig.json、plugins\OmsiLaunch.Api.dll、plugins\OmsiLaunch.Builds.Omsi23004.dll、plugins\OmsiLaunch.Interop.dll、plugins\OmsiLaunch.Native.x86.dll を削除します。その他のプラグインには手を触れないでください。
3. 上記レイアウトに記載されたルートの製品ファイル（OmsiLaunch.exe、OmsiLaunchW.exe、nethost.dll、OmsiLaunch.*.dll、OmsiLaunch.Controller.*.json、YamlDotNet.dll、release-manifest.json、LICENSE、THIRD-PARTY-NOTICES.md）を削除します。
4. .omsilaunch\ を削除します（これにより、セッションプロファイルと診断情報も削除されます）。journal.json が存在する間は、決して削除しないでください。

完了したセッションは、自身が所有していたすべてのファイルを復元するため、それ以上のクリーンアップは不要です。OMSI 自身が実行中に書き込むファイル（たとえば options.cfg 内の [last_map]、キャッシュ、laststn.osn、ログ）は OMSI の通常の状態であり、元に戻されません。トランザクションとリカバリ を参照してください。

検証スクリプト#

どちらの Test-* スクリプトも、想定バージョンを知るために OmsiLaunch.Version.props を読み取ります。