Création des paquets et organisation de la version

Documentation de la version v0.1.0-beta.3Voir la source sur GitHub

Traduction de la page originale en anglais d’OmsiLaunch 0.1.0-beta3. La page anglaise fait foi : en cas de divergence, la page anglaise et le code prévalent.

Cette page décrit le paquet de version OmsiLaunch 0.1.0-beta3 : ce que produit tools\New-ReleasePackage.ps1, les champs de release-manifest.json, la façon dont le contrôleur utilise le manifeste à l'exécution pour vérifier la closure du plugin permanent, la façon dont le paquet est installé dans une racine d'installation OMSI et en est retiré, ce que contient le répertoire .omsilaunch après utilisation, et les scripts de validation (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). L'identité du produit provient de OmsiLaunch.Version.props. Les étapes d'installation destinées aux utilisateurs se trouvent dans installation ; le rôle de la closure du plugin à l'exécution est décrit dans plugin permanent.

Identité du produit (OmsiLaunch.Version.props)#

Directory.Build.props définit InformationalVersion à OmsiLaunchProductVersion sans révision source, de sorte que OmsiLaunch.exe /version affiche exactement 0.1.0-beta3.

Build (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (sortie par défaut artifacts\release) prépare un paquet à partir d'artefacts déjà compilés. L'écriture dans artifacts\release alors que OmsiLaunch-<product_version>.zip existe déjà est refusée sauf si -AllowOverwritePublished est fourni ; les paquets candidats vont dans un autre répertoire (la validation hors ligne utilise artifacts\candidate\post-round-a).

Avant la préparation, chaque sortie de build est vérifiée pour détecter les artefacts périmés.

• OmsiLaunch.Native.x86.dll : par contenu, pas par horodatage. Le build natif écrit artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (cible WriteOmsiLaunchNativeBuildReceipt dans le .vcxproj) : le SHA-256 de la DLL qu'il a produite (output=) et de chaque source à partir de laquelle elle a été compilée (source=<sha256>|<path> : le .cpp, le .rc, le .vcxproj et OmsiLaunch.Version.props). La création du paquet refuse la DLL lorsque son hash n'est pas la sortie enregistrée (does not match its build receipt : une copie périmée ou étrangère, quel que soit son horodatage), lorsqu'une source enregistrée a changé (Native source changed after the recorded build), lorsqu'une source native n'est pas couverte par le reçu, ou lorsque le reçu est absent.
• Shims et assemblys managés : par horodatage. Chacun ne doit pas être plus ancien que les sources de son propre projet (.cpp/.rc/.vcxproj de chaque shim ; le propre projet de chaque assembly managé). Une entrée périmée interrompt la création du paquet avec Stale build artifact.

Le paquet est ensuite assemblé dans un répertoire de préparation entièrement neuf et nommé de manière unique (.staging-<guid> dans le répertoire de sortie), de sorte qu'aucun fichier d'une exécution précédente ne puisse entrer dans la closure. Le dossier OmsiLaunch-current et les archives précédents ne sont remplacés qu'une fois toutes les vérifications ci-dessous réussies.

Ensuite, il calcule le hash de chaque fichier préparé, écrit release-manifest.json à la racine du paquet en UTF-8 sans BOM (le résultat ne dépend plus de l'édition de PowerShell), exécute Test-ReleasePackageIntegrity.ps1 sur la préparation, compare à nouveau chaque fichier de plugin préparé et OmsiLaunch.Native.x86.dll avec sa sortie de build, compresse la préparation, extrait l'archive dans un nouveau répertoire temporaire et valide la closure extraite par rapport au même manifeste (le manifeste archivé doit être identique octet pour octet au manifeste validé), puis publie la préparation sous le nom OmsiLaunch-current, l'archive sous le nom OmsiLaunch-current.zip, la copie vers OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) et écrit OmsiLaunch-0.1.0-beta3.zip.sha256 contenant <SHA-256> <file name>. Tout artefact manquant interrompt le script. Le script ne compile pas ; exécutez d'abord Invoke-OfflineValidation.ps1 (ou les étapes individuelles dotnet build / MSBuild).

Organisation du paquet#

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

Seuls les fichiers produit à la racine, plugins\OmsiLaunch.* et .omsilaunch\ appartiennent au produit. Les plugins tiers sous plugins\ ne sont jamais énumérés, copiés, hachés, supprimés ni restaurés par OmsiLaunch.

release-manifest.json#

Le manifeste est une donnée, jamais une politique exécutable : le contrôleur ne lit que les entrées plugins/. Le lecteur accepte le fichier avec ou sans BOM UTF-8 (les manifestes écrits par Windows PowerShell 5.1 avant cette correction en comportent un).

Utilisation du manifeste à l'exécution (intégrité du plugin)#

Avant chaque plan et chaque démarrage, OmsiLaunchService.LoadArtifacts construit la closure attendue du plugin (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs) :

1. Le contrôleur recherche release-manifest.json à côté de OmsiLaunch.exe (AppContext.BaseDirectory). S'il est présent, ReleaseManifest.TryReadPluginHashes extrait les hashes plugins/* (OL_E_RELEASE_MANIFEST_INVALID si le fichier ne peut pas être lu comme un manifeste).
2. Le hash (SHA-256) de chaque fichier installé <root>\plugins\OmsiLaunch.* est calculé et comparé :
   • avec un manifeste : au hash du manifeste ; le diagnostic de plan plugin.integrity.reference = manifest est enregistré. Fichier manquant → OL_E_PERMANENT_PLUGIN_MISSING ; fichier présent mais non listé → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE ; hash différent → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • sans manifeste (disposition de développement, ou installation dans laquelle le manifeste a été omis) : seules la présence et la cohérence interne par rapport à la copie empaquetée à côté du contrôleur peuvent être vérifiées ; plugin.integrity.reference = self.
3. Un échec rend le plan non exécutable (OL_E_RUNTIME_ARTIFACT_MISSING avec le détail) ou rejette le démarrage (code de sortie 7).

Les fichiers du plugin ne sont jamais préparés, capturés dans un instantané, restaurés ni supprimés par une session ; la closure est une partie permanente de l'installation. La DLL x86 OmsiLaunch.Native.x86.dll n'est chargée que depuis plugins\ ; les assemblys managés déclarent DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Installation dans la racine OMSI#

1. Vérifiez l'archive : comparez OmsiLaunch-0.1.0-beta3.zip avec OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Extrayez l'archive directement dans la racine de l'installation OMSI (le répertoire qui contient Omsi.exe). Cela place les fichiers à la racine, plugins\OmsiLaunch.* (à côté des éventuels plugins tiers) et .omsilaunch\.
3. Conservez release-manifest.json à côté de OmsiLaunch.exe : il permet la vérification d'intégrité du plugin basée sur le manifeste. Le manifeste et les binaires doivent provenir du même paquet : de nouveaux binaires avec un manifeste plus ancien (ou l'inverse) font échouer chaque démarrage avec OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage copie désormais le manifeste avec les fichiers du produit ; auparavant il l'ignorait, ce qui laissait un manifeste plus ancien à côté de binaires plus récents (Round A RA-007).
4. Vérifiez la cohérence en lecture seule avec tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root> : installation_comparison.coherent_with_package doit valoir true.
5. Ne déplacez pas les binaires du plugin dans .omsilaunch\ et ne renommez pas plugins\OmsiLaunch.*.
6. Vérifiez avec OmsiLaunch.exe /version, OmsiLaunch.exe profiles et un /plan (voir première session).

Les fichiers .omsilaunch\assets\splash\*.bmp existants ne sont jamais écrasés par une session (un ensemble de ressources explicitement géré persiste) ; les écraser en extrayant un nouveau paquet est une action délibérée de l'utilisateur.

Le répertoire .omsilaunch après utilisation#

Aucune donnée ne quitte la machine. Voir transactions et récupération.

Désinstallation#

1. Assurez-vous qu'aucune session n'est en cours (OmsiLaunch.exe detect, OmsiLaunch.exe session status) et qu'aucune récupération n'est en attente (OmsiLaunch.exe /recovery-status ; exécutez /recover si pending vaut true), afin que les fichiers OMSI soient déjà restaurés.
2. Supprimez 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. Ne touchez pas aux autres plugins.
3. Supprimez les fichiers produit à la racine listés dans l'organisation ci-dessus (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Supprimez .omsilaunch\ (cela supprime vos profils de session et vos diagnostics). Ne le supprimez jamais tant que journal.json existe.

Une session terminée restaure chaque fichier qu'elle possédait ; aucun nettoyage supplémentaire n'est donc nécessaire. Les fichiers qu'OMSI écrit lui-même pendant son exécution (par exemple [last_map] dans options.cfg, les caches, laststn.osn, les journaux) constituent l'état normal d'OMSI et ne sont pas rétablis ; voir transactions et récupération.

Scripts de validation#

Les deux scripts Test-* lisent OmsiLaunch.Version.props pour connaître la version attendue.