Pacchetto e struttura del rilascio

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

Questa pagina descrive il pacchetto di rilascio di OmsiLaunch 0.1.0-beta3: che cosa produce tools\New-ReleasePackage.ps1, i campi di release-manifest.json, come il controller usa il manifest a runtime per verificare la chiusura del plugin permanente, come il pacchetto viene installato in una radice dell'installazione di OMSI e rimosso da essa, che cosa contiene la directory .omsilaunch dopo l'uso e gli script di validazione (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). L'identità del prodotto proviene da OmsiLaunch.Version.props. I passaggi di installazione per gli utenti sono in installazione; il ruolo a runtime della chiusura del plugin è descritto in plugin permanente.

Identità del prodotto (OmsiLaunch.Version.props)#

Directory.Build.props imposta InformationalVersion su OmsiLaunchProductVersion senza una revisione del codice sorgente, quindi OmsiLaunch.exe /version stampa esattamente 0.1.0-beta3.

Build (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (output predefinito artifacts\release) prepara un pacchetto a partire da artefatti già compilati. La scrittura in artifacts\release quando OmsiLaunch-<product_version>.zip esiste già viene rifiutata a meno che non venga specificato -AllowOverwritePublished; i pacchetti candidati vanno in un'altra directory (la validazione offline usa artifacts\candidate\post-round-a).

Prima della preparazione, ogni output del build viene controllato per verificare che non sia obsoleto.

• OmsiLaunch.Native.x86.dll: in base al contenuto, non al timestamp. Il build nativo scrive artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (target WriteOmsiLaunchNativeBuildReceipt nel .vcxproj): lo SHA-256 della DLL prodotta (output=) e di ogni sorgente da cui è stata compilata (source=<sha256>|<path>: il .cpp, il .rc, il .vcxproj e OmsiLaunch.Version.props). La creazione del pacchetto rifiuta la DLL quando il suo hash non corrisponde all'output registrato (does not match its build receipt: una copia obsoleta o estranea, qualunque sia il suo timestamp), quando un sorgente registrato è cambiato (Native source changed after the recorded build), quando un sorgente nativo non è coperto dalla ricevuta o quando la ricevuta manca.
• Shim e assembly gestiti: in base al timestamp. Ciascuno non deve essere più vecchio dei sorgenti del proprio progetto (.cpp/.rc/.vcxproj di ogni shim; il progetto di ogni assembly gestito). Un input obsoleto interrompe la creazione del pacchetto con Stale build artifact.

Il pacchetto viene quindi assemblato in una directory di staging nuova e con nome univoco (.staging-<guid> nella directory di output), in modo che nessun file di un'esecuzione precedente possa entrare nella chiusura. La cartella OmsiLaunch-current e gli archivi precedenti vengono sostituiti solo dopo che tutti i controlli descritti di seguito sono stati superati.

Lo script calcola quindi l'hash di ogni file preparato, scrive release-manifest.json nella radice del pacchetto come UTF-8 senza BOM (il risultato non dipende più dall'edizione di PowerShell), esegue Test-ReleasePackageIntegrity.ps1 sullo staging, confronta di nuovo ogni file del plugin preparato e OmsiLaunch.Native.x86.dll con il relativo output del build, comprime lo staging, estrae l'archivio in una directory temporanea nuova e valida la chiusura estratta rispetto allo stesso manifest (il manifest archiviato deve essere identico byte per byte a quello validato), quindi pubblica lo staging come OmsiLaunch-current e l'archivio come OmsiLaunch-current.zip, lo copia in OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) e scrive OmsiLaunch-0.1.0-beta3.zip.sha256 contenente <SHA-256> <file name>. Qualsiasi artefatto mancante interrompe lo script. Lo script non esegue il build; eseguire prima Invoke-OfflineValidation.ps1 (o i singoli passaggi dotnet build / MSBuild).

Struttura del pacchetto#

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

Solo i file del prodotto nella radice, plugins\OmsiLaunch.* e .omsilaunch\ sono di proprietà del prodotto. I plugin di terze parti in plugins\ non vengono mai enumerati, copiati, sottoposti a hash, rimossi o ripristinati da OmsiLaunch.

release-manifest.json#

Il manifest è costituito da dati, mai da criteri eseguibili: il controller legge solo le voci plugins/. Il lettore accetta il file con o senza BOM UTF-8 (i manifest scritti da Windows PowerShell 5.1 prima di questa correzione ne contengono uno).

Uso del manifest a runtime (integrità del plugin)#

Prima di ogni piano e di ogni avvio, OmsiLaunchService.LoadArtifacts costruisce la chiusura del plugin attesa (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. Il controller cerca release-manifest.json accanto a OmsiLaunch.exe (AppContext.BaseDirectory). Se presente, ReleaseManifest.TryReadPluginHashes estrae gli hash di plugins/* (OL_E_RELEASE_MANIFEST_INVALID se il file non può essere letto come manifest).
2. Di ogni file installato <root>\plugins\OmsiLaunch.* viene calcolato l'hash (SHA-256), che viene confrontato:
   • con un manifest: con l'hash del manifest; viene registrata la voce di diagnostica del piano plugin.integrity.reference = manifest. File mancante → OL_E_PERMANENT_PLUGIN_MISSING; file presente ma non elencato → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; hash diverso → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • senza un manifest (layout di sviluppo, oppure un'installazione che ha omesso il manifest): è possibile controllare solo la presenza e la coerenza interna rispetto alla copia del pacchetto accanto al controller; plugin.integrity.reference = self.
3. Un errore rende il piano non eseguibile (OL_E_RUNTIME_ARTIFACT_MISSING con il dettaglio) oppure rifiuta l'avvio (uscita 7).

I file del plugin non vengono mai preparati, sottoposti a snapshot, ripristinati o rimossi da una sessione; la chiusura è una parte permanente dell'installazione. La DLL x86 OmsiLaunch.Native.x86.dll viene caricata solo da plugins\; gli assembly gestiti dichiarano DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Installazione nella radice di OMSI#

1. Verificare l'archivio: confrontare OmsiLaunch-0.1.0-beta3.zip con OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Estrarre l'archivio direttamente nella radice dell'installazione di OMSI (la directory che contiene Omsi.exe). In questo modo vengono collocati i file della radice, plugins\OmsiLaunch.* (accanto a eventuali plugin di terze parti) e .omsilaunch\.
3. Mantenere release-manifest.json accanto a OmsiLaunch.exe: abilita l'integrità del plugin basata sul manifest. Il manifest e i binari devono provenire dallo stesso pacchetto: binari nuovi con un manifest più vecchio (o viceversa) fanno fallire ogni avvio con OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage ora copia il manifest insieme ai file del prodotto; in precedenza lo tralasciava, lasciando un manifest più vecchio accanto a binari più recenti (Round A RA-007).
4. Controllare la coerenza in sola lettura con tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package deve essere true.
5. Non spostare i binari del plugin in .omsilaunch\ e non rinominare plugins\OmsiLaunch.*.
6. Verificare con OmsiLaunch.exe /version, OmsiLaunch.exe profiles e un /plan (vedere prima sessione).

I file .omsilaunch\assets\splash\*.bmp esistenti non vengono mai sovrascritti da una sessione (un insieme di asset gestito esplicitamente rimane); sovrascriverli estraendo un nuovo pacchetto è un'azione deliberata dell'utente.

La directory .omsilaunch dopo l'uso#

Nessun dato lascia la macchina. Vedere transazioni e recupero.

Disinstallazione#

1. Assicurarsi che nessuna sessione sia in esecuzione (OmsiLaunch.exe detect, OmsiLaunch.exe session status) e che nessun recupero sia in sospeso (OmsiLaunch.exe /recovery-status; eseguire /recover se pending è true), in modo che i file di OMSI siano già ripristinati.
2. Eliminare 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. Lasciare intatti gli altri plugin.
3. Eliminare i file del prodotto nella radice elencati nella struttura sopra (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Eliminare .omsilaunch\ (in questo modo vengono rimossi i profili di sessione e la diagnostica). Non eliminarla mai finché esiste journal.json.

Una sessione completata ripristina ogni file di sua proprietà, quindi non è necessaria alcuna ulteriore pulizia. I file che OMSI stesso scrive durante l'esecuzione (ad esempio [last_map] in options.cfg, le cache, laststn.osn, i log) sono il normale stato di OMSI e non vengono riportati allo stato precedente; vedere transazioni e recupero.

Script di validazione#

Entrambi gli script Test-* leggono OmsiLaunch.Version.props per conoscere la versione attesa.