Empaquetado y estructura de la versión

Documentación de la versión v0.1.0-beta.3Ver fuente en GitHub

Traducción de la página original en inglés de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si difieren, prevalecen la página en inglés y el código.

Esta página describe el paquete de la versión 0.1.0-beta3 de OmsiLaunch: qué produce tools\New-ReleasePackage.ps1, los campos de release-manifest.json, cómo usa el controlador el manifiesto en runtime para verificar el conjunto de archivos del plugin permanente, cómo se instala el paquete en la raíz de una instalación de OMSI y cómo se quita, qué contiene el directorio .omsilaunch tras su uso, y los scripts de validación (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). La identidad del producto procede de OmsiLaunch.Version.props. Los pasos de instalación para usuarios están en instalación; la función en runtime del conjunto de archivos del plugin está en plugin permanente.

Identidad del producto (OmsiLaunch.Version.props)#

Directory.Build.props establece InformationalVersion en OmsiLaunchProductVersion sin revisión de código fuente, por lo que OmsiLaunch.exe /version imprime exactamente 0.1.0-beta3.

Compilación (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (salida predeterminada artifacts\release) prepara un paquete a partir de artefactos ya compilados. Se rechaza escribir en artifacts\release cuando ya existe OmsiLaunch-<product_version>.zip, salvo que se indique -AllowOverwritePublished; los paquetes candidatos van a otro directorio (la validación offline usa artifacts\candidate\post-round-a).

Antes de la preparación, se comprueba que ninguna salida de compilación esté desactualizada.

• OmsiLaunch.Native.x86.dll: por contenido, no por marca de tiempo. La compilación nativa escribe artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (destino WriteOmsiLaunchNativeBuildReceipt en el .vcxproj): el SHA-256 de la DLL que produjo (output=) y de cada fuente a partir de la cual se compiló (source=<sha256>|<path>: el .cpp, el .rc, el .vcxproj y OmsiLaunch.Version.props). El empaquetado rechaza la DLL cuando su hash no es la salida registrada (does not match its build receipt: una copia desactualizada o ajena, sea cual sea su marca de tiempo), cuando una fuente registrada ha cambiado (Native source changed after the recorded build), cuando una fuente nativa no está cubierta por el recibo o cuando falta el recibo.
• Shims y ensamblados administrados: por marca de tiempo. Ninguno debe ser más antiguo que las fuentes de su propio proyecto (.cpp/.rc/.vcxproj de cada shim; el proyecto propio de cada ensamblado administrado). Una entrada desactualizada aborta el empaquetado con Stale build artifact.

A continuación, el paquete se monta en un directorio de preparación completamente nuevo y con nombre único (.staging-<guid> en el directorio de salida), de modo que ningún archivo de una ejecución anterior pueda entrar en el conjunto de archivos. La carpeta OmsiLaunch-current y los archivos comprimidos anteriores solo se sustituyen después de que se hayan superado todas las comprobaciones siguientes.

Después calcula el hash de cada archivo preparado, escribe release-manifest.json en la raíz del paquete como UTF-8 sin BOM (el resultado ya no depende de la edición de PowerShell), ejecuta Test-ReleasePackageIntegrity.ps1 sobre la preparación, vuelve a comparar cada archivo del plugin preparado y OmsiLaunch.Native.x86.dll con su salida de compilación, comprime la preparación, extrae el archivo comprimido en un directorio temporal nuevo y valida el conjunto de archivos extraído contra el mismo manifiesto (el manifiesto archivado debe ser idéntico byte a byte al validado), y después publica la preparación como OmsiLaunch-current y el archivo comprimido como OmsiLaunch-current.zip, lo copia en OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) y escribe OmsiLaunch-0.1.0-beta3.zip.sha256 con el contenido <SHA-256> <file name>. Cualquier artefacto que falte aborta el script. El script no compila; ejecuta antes Invoke-OfflineValidation.ps1 (o los pasos individuales de dotnet build / MSBuild).

Estructura del paquete#

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 los archivos del producto de la raíz, plugins\OmsiLaunch.* y .omsilaunch\ son propiedad del producto. OmsiLaunch nunca enumera, copia, calcula el hash, elimina ni restaura los plugins de terceros de plugins\.

release-manifest.json#

El manifiesto son datos, nunca una política ejecutable: el controlador solo lee las entradas plugins/. El lector acepta el archivo con o sin BOM UTF-8 (los manifiestos escritos por Windows PowerShell 5.1 antes de esta corrección llevan uno).

Uso del manifiesto en runtime (integridad del plugin)#

Antes de cada plan y de cada inicio, OmsiLaunchService.LoadArtifacts construye el conjunto de archivos del plugin esperado (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. El controlador busca release-manifest.json junto a OmsiLaunch.exe (AppContext.BaseDirectory). Si existe, ReleaseManifest.TryReadPluginHashes extrae los hashes de plugins/* (OL_E_RELEASE_MANIFEST_INVALID si el archivo no puede leerse como manifiesto).
2. Se calcula el hash (SHA-256) de cada archivo instalado <root>\plugins\OmsiLaunch.* y se compara:
   • con manifiesto: contra el hash del manifiesto; se registra el diagnóstico del plan plugin.integrity.reference = manifest. Archivo que falta → OL_E_PERMANENT_PLUGIN_MISSING; archivo presente pero no listado → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; hash distinto → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • sin manifiesto (estructura de desarrollo, o una instalación que omitió el manifiesto): solo pueden comprobarse la presencia y la coherencia interna frente a la copia empaquetada junto al controlador; plugin.integrity.reference = self.
3. Un fallo marca el plan como no ejecutable (OL_E_RUNTIME_ARTIFACT_MISSING con el detalle) o rechaza el inicio (salida 7).

Una sesión nunca prepara, incluye en un snapshot, restaura ni elimina los archivos del plugin; el conjunto de archivos es una parte permanente de la instalación. La OmsiLaunch.Native.x86.dll x86 solo se carga desde plugins\; los ensamblados administrados declaran DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Instalación en la raíz de OMSI#

1. Verifica el archivo comprimido: compara OmsiLaunch-0.1.0-beta3.zip con OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Extrae el archivo comprimido directamente en la raíz de la instalación de OMSI (el directorio que contiene Omsi.exe). Así se colocan los archivos de la raíz, plugins\OmsiLaunch.* (junto a cualquier plugin de terceros) y .omsilaunch\.
3. Mantén release-manifest.json junto a OmsiLaunch.exe: habilita la integridad del plugin basada en el manifiesto. El manifiesto y los binarios deben proceder del mismo paquete: binarios nuevos con un manifiesto más antiguo (o al revés) hacen que todos los inicios fallen con OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage copia ahora el manifiesto junto con los archivos del producto; antes lo omitía, lo que dejaba un manifiesto más antiguo junto a binarios más nuevos (Round A RA-007).
4. Comprueba la coherencia en modo de solo lectura con tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package debe ser true.
5. No muevas los binarios del plugin a .omsilaunch\ ni cambies el nombre de plugins\OmsiLaunch.*.
6. Verifica con OmsiLaunch.exe /version, OmsiLaunch.exe profiles y un /plan (consulta primera sesión).

Una sesión nunca sobrescribe los archivos .omsilaunch\assets\splash\*.bmp existentes (un conjunto de recursos gestionado explícitamente se conserva); sobrescribirlos al extraer un paquete nuevo es una acción deliberada del usuario.

El directorio .omsilaunch tras su uso#

Ningún dato sale del ordenador. Consulta transacciones y recuperación.

Desinstalación#

1. Asegúrate de que no hay ninguna sesión en ejecución (OmsiLaunch.exe detect, OmsiLaunch.exe session status) ni ninguna recuperación pendiente (OmsiLaunch.exe /recovery-status; ejecuta /recover si pending es true), para que los archivos de OMSI ya estén restaurados.
2. Elimina 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. No toques los demás plugins.
3. Elimina los archivos del producto de la raíz enumerados en la estructura anterior (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Elimina .omsilaunch\ (esto elimina tus perfiles de sesión y tus diagnósticos). No lo elimines nunca mientras exista journal.json.

Una sesión completada restaura todos los archivos que le pertenecían, por lo que no hace falta ninguna limpieza adicional. Los archivos que el propio OMSI escribe mientras se ejecuta (por ejemplo [last_map] en options.cfg, cachés, laststn.osn, registros) forman parte del estado normal de OMSI y no se revierten; consulta transacciones y recuperación.

Scripts de validación#

Ambos scripts Test-* leen OmsiLaunch.Version.props para conocer la versión esperada.