Empacotamento e estrutura do release

Documentação da versão v0.1.0-beta.3Ver fonte no GitHub

Tradução da página original em inglês do OmsiLaunch 0.1.0-beta3. A página em inglês é a referência normativa: se as duas divergirem, valem a página em inglês e o código.

Esta página descreve o pacote de release 0.1.0-beta3 do OmsiLaunch: o que tools\New-ReleasePackage.ps1 produz, os campos de release-manifest.json, como o controlador usa o manifesto em runtime para verificar o conjunto de arquivos do plugin permanente, como o pacote é instalado em uma raiz de instalação do OMSI e removido dela, o que o diretório .omsilaunch contém após o uso e os scripts de validação (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). A identidade do produto vem de OmsiLaunch.Version.props. As etapas de instalação para usuários estão em instalação; a função do conjunto de arquivos do plugin em runtime está em plugin permanente.

Identidade do produto (OmsiLaunch.Version.props)#

Directory.Build.props define InformationalVersion como OmsiLaunchProductVersion sem revisão de código-fonte, de modo que OmsiLaunch.exe /version imprime exatamente 0.1.0-beta3.

Build (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (saída padrão artifacts\release) prepara um pacote a partir de artefatos já compilados. A gravação em artifacts\release quando OmsiLaunch-<product_version>.zip já existe é recusada, a menos que -AllowOverwritePublished seja informado; pacotes candidatos vão para outro diretório (a validação offline usa artifacts\candidate\post-round-a).

Antes da preparação, toda saída de build é verificada quanto a estar desatualizada.

• OmsiLaunch.Native.x86.dll: pelo conteúdo, não pelo timestamp. O build nativo grava artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (target WriteOmsiLaunchNativeBuildReceipt no .vcxproj): o SHA-256 da DLL que produziu (output=) e de cada fonte a partir da qual ela foi compilada (source=<sha256>|<path>: o .cpp, o .rc, o .vcxproj e OmsiLaunch.Version.props). O empacotamento recusa a DLL quando seu hash não é a saída registrada (does not match its build receipt: uma cópia desatualizada ou alheia, qualquer que seja seu timestamp), quando uma fonte registrada mudou (Native source changed after the recorded build), quando uma fonte nativa não está coberta pelo recibo ou quando o recibo está ausente.
• Shims e assemblies gerenciados: pelo timestamp. Cada um não pode ser mais antigo que as fontes de seu próprio projeto (.cpp/.rc/.vcxproj de cada shim; o próprio projeto de cada assembly gerenciado). Uma entrada desatualizada aborta o empacotamento com Stale build artifact.

O pacote é então montado em um diretório de preparação totalmente novo e com nome exclusivo (.staging-<guid> no diretório de saída), de modo que nenhum arquivo de uma execução anterior possa entrar no conjunto de arquivos. A pasta OmsiLaunch-current e os arquivos compactados anteriores só são substituídos depois que todas as verificações abaixo forem aprovadas.

Em seguida, o script calcula o hash de cada arquivo preparado, grava release-manifest.json na raiz do pacote como UTF-8 sem BOM (o resultado não depende mais da edição do PowerShell), executa Test-ReleasePackageIntegrity.ps1 sobre a preparação, compara novamente cada arquivo de plugin preparado e OmsiLaunch.Native.x86.dll com sua saída de build, compacta a preparação, extrai o arquivo compactado em um diretório temporário novo e valida o conjunto de arquivos extraído contra o mesmo manifesto (o manifesto dentro do arquivo compactado precisa ser idêntico byte a byte ao validado), depois publica a preparação como OmsiLaunch-current, o arquivo compactado como OmsiLaunch-current.zip, copia-o para OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) e grava OmsiLaunch-0.1.0-beta3.zip.sha256 contendo <SHA-256> <file name>. Qualquer artefato ausente aborta o script. O script não compila; execute antes Invoke-OfflineValidation.ps1 (ou as etapas individuais de dotnet build / MSBuild).

Estrutura do pacote#

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

Somente os arquivos do produto na raiz, plugins\OmsiLaunch.* e .omsilaunch\ pertencem ao produto. Plugins de terceiros em plugins\ nunca são enumerados, copiados, submetidos a hash, removidos nem restaurados pelo OmsiLaunch.

release-manifest.json#

O manifesto é dado, nunca política executável: o controlador lê somente as entradas plugins/. O leitor aceita o arquivo com ou sem BOM UTF-8 (manifestos gravados pelo Windows PowerShell 5.1 antes desta correção contêm um).

Uso do manifesto em runtime (integridade do plugin)#

Antes de cada plano e de cada inicialização, OmsiLaunchService.LoadArtifacts monta o conjunto de arquivos esperado do plugin (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. O controlador procura release-manifest.json ao lado de OmsiLaunch.exe (AppContext.BaseDirectory). Quando presente, ReleaseManifest.TryReadPluginHashes extrai os hashes de plugins/* (OL_E_RELEASE_MANIFEST_INVALID se o arquivo não puder ser lido como manifesto).
2. O hash de cada arquivo instalado <root>\plugins\OmsiLaunch.* é calculado (SHA-256) e comparado:
   • com um manifesto: com o hash do manifesto; o diagnóstico de plano plugin.integrity.reference = manifest é registrado. Arquivo ausente → OL_E_PERMANENT_PLUGIN_MISSING; arquivo presente, mas não listado → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; hash diferente → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • sem um manifesto (layout de desenvolvimento, ou uma instalação que omitiu o manifesto): somente a presença e a autoconsistência em relação à cópia empacotada ao lado do controlador podem ser verificadas; plugin.integrity.reference = self.
3. Uma falha marca o plano como não apto para execução (OL_E_RUNTIME_ARTIFACT_MISSING com o detalhe) ou rejeita a inicialização (saída 7).

Os arquivos do plugin nunca são preparados, incluídos em snapshot, restaurados nem removidos por uma sessão; o conjunto de arquivos é parte permanente da instalação. O OmsiLaunch.Native.x86.dll x86 é carregado somente de plugins\; os assemblies gerenciados declaram DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Instalação na raiz do OMSI#

1. Verifique o arquivo compactado: compare OmsiLaunch-0.1.0-beta3.zip com OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Extraia o arquivo compactado diretamente na raiz da instalação do OMSI (o diretório que contém Omsi.exe). Isso coloca os arquivos da raiz, plugins\OmsiLaunch.* (ao lado de eventuais plugins de terceiros) e .omsilaunch\.
3. Mantenha release-manifest.json ao lado de OmsiLaunch.exe: ele habilita a integridade do plugin baseada no manifesto. O manifesto e os binários precisam vir do mesmo pacote: binários novos sobre um manifesto mais antigo (ou o contrário) fazem toda inicialização falhar com OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage agora copia o manifesto junto com os arquivos do produto; antes ele o ignorava, o que deixava um manifesto mais antigo ao lado de binários mais novos (Round A RA-007).
4. Verifique a coerência em modo somente leitura com tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package precisa ser true.
5. Não mova binários do plugin para .omsilaunch\ e não renomeie plugins\OmsiLaunch.*.
6. Verifique com OmsiLaunch.exe /version, OmsiLaunch.exe profiles e um /plan (veja primeira sessão).

Arquivos .omsilaunch\assets\splash\*.bmp existentes nunca são sobrescritos por uma sessão (um conjunto de assets gerenciado explicitamente persiste); sobrescrevê-los extraindo um novo pacote é uma ação deliberada do usuário.

O diretório .omsilaunch após o uso#

Nenhum dado sai da máquina. Veja transações e recuperação.

Desinstalação#

1. Certifique-se de que nenhuma sessão esteja em execução (OmsiLaunch.exe detect, OmsiLaunch.exe session status) e de que nenhuma recuperação esteja pendente (OmsiLaunch.exe /recovery-status; execute /recover se pending for true), para que os arquivos do OMSI já estejam restaurados.
2. Exclua 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. Não toque nos outros plugins.
3. Exclua os arquivos do produto na raiz listados na estrutura acima (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Exclua .omsilaunch\ (isso remove seus perfis de sessão e diagnósticos). Nunca o exclua enquanto journal.json existir.

Uma sessão concluída restaura todos os arquivos que lhe pertenciam, portanto nenhuma limpeza adicional é necessária. Os arquivos que o próprio OMSI grava enquanto é executado (por exemplo [last_map] em options.cfg, caches, laststn.osn, logs) são o estado normal do OMSI e não são revertidos; veja transações e recuperação.

Scripts de validação#

Ambos os scripts Test-* leem OmsiLaunch.Version.props para saber a versão esperada.