Paketierung und Release-Struktur

Dokumentation für Version v0.1.0-beta.3Quelle auf GitHub ansehen

Übersetzung der englischen Originalseite für OmsiLaunch 0.1.0-beta3. Maßgeblich ist die englische Seite: Bei Abweichungen gelten die englische Seite und der Code.

Diese Seite beschreibt das OmsiLaunch-Release-Paket 0.1.0-beta3: was tools\New-ReleasePackage.ps1 erzeugt, die Felder von release-manifest.json, wie der Controller das Manifest zur Laufzeit verwendet, um die Plugin-Gesamtheit (Closure) des permanenten Plugins zu verifizieren, wie das Paket in ein OMSI-Installationsstammverzeichnis installiert und daraus entfernt wird, was das .omsilaunch-Verzeichnis nach der Verwendung enthält, sowie die Validierungsskripte (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). Die Produktidentität stammt aus OmsiLaunch.Version.props. Installationsschritte für Benutzer finden Sie unter Installation; die Rolle der Plugin-Closure zur Laufzeit ist unter permanentes Plugin beschrieben.

Produktidentität (OmsiLaunch.Version.props)#

Directory.Build.props setzt InformationalVersion auf OmsiLaunchProductVersion ohne Quellrevision, sodass OmsiLaunch.exe /version genau 0.1.0-beta3 ausgibt.

Build (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (Standardausgabe artifacts\release) stellt ein Paket aus bereits gebauten Artefakten zusammen. Das Schreiben nach artifacts\release wird verweigert, wenn OmsiLaunch-<product_version>.zip bereits existiert, sofern nicht -AllowOverwritePublished angegeben ist; Kandidatenpakete werden in ein anderes Verzeichnis geschrieben (die Offline-Validierung verwendet artifacts\candidate\post-round-a).

Vor dem Staging wird jede Build-Ausgabe darauf geprüft, ob sie veraltet ist.

• OmsiLaunch.Native.x86.dll: nach Inhalt, nicht nach Zeitstempel. Der native Build schreibt artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (Target WriteOmsiLaunchNativeBuildReceipt in der .vcxproj): den SHA-256 der erzeugten DLL (output=) und jeder Quelle, aus der sie gebaut wurde (source=<sha256>|<path>: die .cpp, die .rc, die .vcxproj und OmsiLaunch.Version.props). Die Paketierung weist die DLL zurück, wenn ihr Hash nicht der erfassten Ausgabe entspricht (does not match its build receipt: eine veraltete oder fremde Kopie, unabhängig von ihrem Zeitstempel), wenn sich eine erfasste Quelle geändert hat (Native source changed after the recorded build), wenn eine native Quelle nicht vom Beleg erfasst ist oder wenn der Beleg fehlt.
• Shims und verwaltete Assemblys: nach Zeitstempel. Keines davon darf älter sein als die Quellen seines eigenen Projekts (.cpp/.rc/.vcxproj jedes Shims; das eigene Projekt jeder verwalteten Assembly). Eine veraltete Eingabe bricht die Paketierung mit Stale build artifact ab.

Das Paket wird dann in einem völlig neuen, eindeutig benannten Staging-Verzeichnis (.staging-<guid> im Ausgabeverzeichnis) zusammengestellt, sodass keine Datei aus einem früheren Lauf in die Closure gelangen kann. Der vorherige Ordner OmsiLaunch-current und die Archive werden erst ersetzt, nachdem alle unten aufgeführten Prüfungen bestanden wurden.

Anschließend hasht es jede bereitgestellte Datei, schreibt release-manifest.json im Paketstammverzeichnis als UTF-8 ohne BOM (das Ergebnis hängt nicht mehr von der PowerShell-Edition ab), führt Test-ReleasePackageIntegrity.ps1 auf dem Staging-Stand aus, vergleicht jede bereitgestellte Plugin-Datei und OmsiLaunch.Native.x86.dll erneut mit ihrer Build-Ausgabe, komprimiert den Staging-Stand, entpackt das Archiv in ein neues temporäres Verzeichnis und validiert die entpackte Closure gegen dasselbe Manifest (das archivierte Manifest muss bytegleich mit dem validierten sein), veröffentlicht dann den Staging-Stand als OmsiLaunch-current und das Archiv als OmsiLaunch-current.zip, kopiert es nach OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) und schreibt OmsiLaunch-0.1.0-beta3.zip.sha256 mit dem Inhalt <SHA-256> <file name>. Jedes fehlende Artefakt bricht das Skript ab. Das Skript baut nicht selbst; führen Sie zuerst Invoke-OfflineValidation.ps1 aus (oder die einzelnen dotnet build- / MSBuild-Schritte).

Paketstruktur#

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

Nur die Produktdateien im Stammverzeichnis, plugins\OmsiLaunch.* und .omsilaunch\ gehören dem Produkt. Plugins von Drittanbietern unter plugins\ werden von OmsiLaunch nie aufgezählt, kopiert, gehasht, entfernt oder wiederhergestellt.

release-manifest.json#

Das Manifest sind Daten, niemals ausführbare Richtlinien: Der Controller liest nur die plugins/-Einträge. Der Leser akzeptiert die Datei mit oder ohne UTF-8-BOM (Manifeste, die vor dieser Korrektur von Windows PowerShell 5.1 geschrieben wurden, enthalten eine).

Verwendung des Manifests zur Laufzeit (Plugin-Integrität)#

Vor jeder Planung und jedem Start erstellt OmsiLaunchService.LoadArtifacts die erwartete Plugin-Closure (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. Der Controller sucht release-manifest.json neben OmsiLaunch.exe (AppContext.BaseDirectory). Ist sie vorhanden, extrahiert ReleaseManifest.TryReadPluginHashes die plugins/*-Hashes (OL_E_RELEASE_MANIFEST_INVALID, wenn die Datei nicht als Manifest gelesen werden kann).
2. Jede installierte Datei <root>\plugins\OmsiLaunch.* wird gehasht (SHA-256) und verglichen:
   • mit einem Manifest: mit dem Hash im Manifest; die Plandiagnose plugin.integrity.reference = manifest wird erfasst. Fehlende Datei → OL_E_PERMANENT_PLUGIN_MISSING; Datei vorhanden, aber nicht aufgeführt → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; Hash weicht ab → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • ohne Manifest (Entwicklungsstruktur oder eine Installation, bei der das Manifest weggelassen wurde): Es können nur Vorhandensein und Selbstkonsistenz gegenüber der paketierten Kopie neben dem Controller geprüft werden; plugin.integrity.reference = self.
3. Ein Fehler kennzeichnet den Plan als nicht ausführbar (OL_E_RUNTIME_ARTIFACT_MISSING mit dem Detail) oder weist den Start zurück (Exitcode 7).

Plugin-Dateien werden von einer Sitzung nie bereitgestellt, in einen Snapshot aufgenommen, wiederhergestellt oder entfernt; die Closure ist ein permanenter Bestandteil der Installation. Die x86-Datei OmsiLaunch.Native.x86.dll wird ausschließlich aus plugins\ geladen; die verwalteten Assemblys deklarieren DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Installation in das OMSI-Stammverzeichnis#

1. Verifizieren Sie das Archiv: Vergleichen Sie OmsiLaunch-0.1.0-beta3.zip mit OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Entpacken Sie das Archiv direkt in das OMSI-Installationsstammverzeichnis (das Verzeichnis, das Omsi.exe enthält). Dadurch werden die Dateien im Stammverzeichnis, plugins\OmsiLaunch.* (neben etwaigen Plugins von Drittanbietern) und .omsilaunch\ angelegt.
3. Belassen Sie release-manifest.json neben OmsiLaunch.exe: Es ermöglicht die manifestbasierte Plugin-Integritätsprüfung. Manifest und Binärdateien müssen aus demselben Paket stammen: Neue Binärdateien über einem älteren Manifest (oder umgekehrt) lassen jeden Start mit OL_E_PERMANENT_PLUGIN_HASH_MISMATCH fehlschlagen. Test-ReleasePresentation.ps1 -InstallPackage kopiert das Manifest jetzt zusammen mit den Produktdateien; früher wurde es übersprungen, wodurch ein älteres Manifest neben neueren Binärdateien zurückblieb (Runde A RA-007).
4. Prüfen Sie die Kohärenz schreibgeschützt mit tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package muss true sein.
5. Verschieben Sie keine Plugin-Binärdateien nach .omsilaunch\ und benennen Sie plugins\OmsiLaunch.* nicht um.
6. Verifizieren Sie mit OmsiLaunch.exe /version, OmsiLaunch.exe profiles und einem /plan (siehe erste Sitzung).

Vorhandene .omsilaunch\assets\splash\*.bmp-Dateien werden von einer Sitzung nie überschrieben (ein explizit verwalteter Asset-Satz bleibt bestehen); sie durch Entpacken eines neuen Pakets zu überschreiben, ist eine bewusste Aktion des Benutzers.

Das .omsilaunch-Verzeichnis nach der Verwendung#

Keine Daten verlassen den Rechner. Siehe Transaktionen und Recovery.

Deinstallation#

1. Stellen Sie sicher, dass keine Sitzung läuft (OmsiLaunch.exe detect, OmsiLaunch.exe session status) und keine Recovery aussteht (OmsiLaunch.exe /recovery-status; führen Sie /recover aus, wenn pending gleich true ist), damit die OMSI-Dateien bereits wiederhergestellt sind.
2. Löschen Sie 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. Lassen Sie andere Plugins unverändert.
3. Löschen Sie die oben in der Struktur aufgeführten Produktdateien im Stammverzeichnis (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Löschen Sie .omsilaunch\ (dadurch werden Ihre Sitzungsprofile und Diagnosen entfernt). Löschen Sie es niemals, solange journal.json existiert.

Eine abgeschlossene Sitzung stellt jede Datei wieder her, die ihr gehörte, sodass keine weitere Bereinigung erforderlich ist. Dateien, die OMSI selbst während der Ausführung schreibt (z. B. [last_map] in options.cfg, Caches, laststn.osn, Protokolle), sind der normale Zustand von OMSI und werden nicht zurückgesetzt; siehe Transaktionen und Recovery.

Validierungsskripte#

Beide Test-*-Skripte lesen OmsiLaunch.Version.props, um die erwartete Version zu ermitteln.