Packaging and Release Layout

Documentation for version v0.1.0-beta.3View source on GitHub

This page describes the OmsiLaunch 0.1.0-beta3 release package: what tools\New-ReleasePackage.ps1 produces, the fields of release-manifest.json, how the controller uses the manifest at runtime to verify the permanent plugin closure, how the package is installed into and removed from an OMSI installation root, what the .omsilaunch directory contains after use, and the validation scripts (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). Product identity comes from OmsiLaunch.Version.props. Installation steps for users are in installation; the plugin closure's runtime role is in permanent plugin.

Product identity (OmsiLaunch.Version.props)#

Directory.Build.props sets InformationalVersion to OmsiLaunchProductVersion without a source revision, so OmsiLaunch.exe /version prints exactly 0.1.0-beta3.

Build (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (default output artifacts\release) stages a package from already built artifacts. Writing to artifacts\release when OmsiLaunch-<product_version>.zip already exists is refused unless -AllowOverwritePublished is given; candidate packages go to another directory (the offline validation uses artifacts\candidate\post-round-a).

Before staging, every build output is checked for staleness.

• OmsiLaunch.Native.x86.dll: by content, not by timestamp. The native build writes artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (target WriteOmsiLaunchNativeBuildReceipt in the .vcxproj): the SHA-256 of the DLL it produced (output=) and of every source it was built from (source=<sha256>|<path>: the .cpp, the .rc, the .vcxproj and OmsiLaunch.Version.props). Packaging refuses the DLL when its hash is not the recorded output (does not match its build receipt: a stale or foreign copy, whatever its timestamp), when a recorded source changed (Native source changed after the recorded build), when a native source is not covered by the receipt, or when the receipt is missing.
• Shims and managed assemblies: by timestamp. Each must not be older than the sources of its own project (.cpp/.rc/.vcxproj of each shim; each managed assembly's own project). A stale input aborts packaging with Stale build artifact.

The package is then assembled in a brand-new, uniquely named staging directory (.staging-<guid> in the output directory), so no file from an earlier run can enter the closure. The previous OmsiLaunch-current folder and archives are replaced only after every check below has passed.

Then it hashes every staged file, writes release-manifest.json at the package root as UTF-8 without a BOM (the result no longer depends on the PowerShell edition), runs Test-ReleasePackageIntegrity.ps1 on the stage, re-compares every staged plugin file and OmsiLaunch.Native.x86.dll with its build output, compresses the stage, extracts the archive into a fresh temporary directory and validates the extracted closure against the same manifest (the archived manifest must be byte-identical to the validated one), then publishes the stage as OmsiLaunch-current, the archive as OmsiLaunch-current.zip, copies it to OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) and writes OmsiLaunch-0.1.0-beta3.zip.sha256 containing <SHA-256> <file name>. Any missing artifact aborts the script. The script does not build; run Invoke-OfflineValidation.ps1 (or the individual dotnet build / MSBuild steps) first.

Package layout#

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

Only the root product files, plugins\OmsiLaunch.* and .omsilaunch\ are product-owned. Third-party plugins under plugins\ are never enumerated, copied, hashed, removed or restored by OmsiLaunch.

release-manifest.json#

The manifest is data, never executable policy: the controller reads only the plugins/ entries. The reader accepts the file with or without a UTF-8 BOM (manifests written by Windows PowerShell 5.1 before this correction carry one).

Runtime use of the manifest (plugin integrity)#

Before every plan and start, OmsiLaunchService.LoadArtifacts builds the expected plugin closure (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. The controller looks for release-manifest.json beside OmsiLaunch.exe (AppContext.BaseDirectory). When present, ReleaseManifest.TryReadPluginHashes extracts the plugins/* hashes (OL_E_RELEASE_MANIFEST_INVALID if the file cannot be read as a manifest).
2. Each installed file <root>\plugins\OmsiLaunch.* is hashed (SHA-256) and compared:
   • with a manifest: against the manifest hash; the plan diagnostic plugin.integrity.reference = manifest is recorded. Missing file → OL_E_PERMANENT_PLUGIN_MISSING; file present but not listed → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; hash differs → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • without a manifest (development layout, or an installation that omitted the manifest): only presence and self-consistency against the packaged copy beside the controller can be checked; plugin.integrity.reference = self.
3. A failure marks the plan not runnable (OL_E_RUNTIME_ARTIFACT_MISSING with the detail) or rejects the start (exit 7).

Plugin files are never staged, snapshotted, restored or removed by a session; the closure is a permanent part of the installation. The x86 OmsiLaunch.Native.x86.dll is loaded from plugins\ only; the managed assemblies declare DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Installation into the OMSI root#

1. Verify the archive: compare OmsiLaunch-0.1.0-beta3.zip against OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Extract the archive directly into the OMSI installation root (the directory containing Omsi.exe). This places the root files, plugins\OmsiLaunch.* (beside any third-party plugins) and .omsilaunch\.
3. Keep release-manifest.json beside OmsiLaunch.exe: it enables manifest-based plugin integrity. The manifest and the binaries must come from the same package: new binaries over an older manifest (or the reverse) make every start fail with OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage now copies the manifest together with the product files; it used to skip it, which left an older manifest beside newer binaries (Round A RA-007).
4. Check coherence read-only with tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package must be true.
5. Do not move plugin binaries into .omsilaunch\ and do not rename plugins\OmsiLaunch.*.
6. Verify with OmsiLaunch.exe /version, OmsiLaunch.exe profiles and a /plan (see first session).

Existing .omsilaunch\assets\splash\*.bmp files are never overwritten by a session (an explicitly managed asset set persists); overwriting them by extracting a new package is a deliberate user action.

The .omsilaunch directory after use#

No data leaves the machine. See transactions and recovery.

Uninstall#

1. Make sure no session is running (OmsiLaunch.exe detect, OmsiLaunch.exe session status) and no recovery is pending (OmsiLaunch.exe /recovery-status; run /recover if pending is true) so OMSI files are already restored.
2. Delete 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. Leave other plugins untouched.
3. Delete the root product files listed in the layout above (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Delete .omsilaunch\ (this removes your session profiles and diagnostics). Never delete it while journal.json exists.

A completed session restores every file it owned, so no further cleanup is needed. Files OMSI itself writes while it runs (for example [last_map] in options.cfg, caches, laststn.osn, logs) are OMSI's normal state and are not reverted; see transactions and recovery.

Validation scripts#

Both Test-* scripts read OmsiLaunch.Version.props to know the expected version.