Упаковка и структура релиза

Документация версии v0.1.0-beta.3Исходник на GitHub

Перевод исходной страницы на английском языке для OmsiLaunch 0.1.0-beta3. Нормативной является английская страница: при расхождениях приоритет имеют английская страница и код.

На этой странице описан релизный пакет OmsiLaunch 0.1.0-beta3: что создаёт tools\New-ReleasePackage.ps1, поля release-manifest.json, как контроллер использует манифест во время работы для проверки замыкания постоянного плагина (набора его файлов), как пакет устанавливается в корневой каталог установки OMSI и удаляется из него, что содержит каталог .omsilaunch после использования, а также скрипты проверки (tools\Test-ReleaseIdentity.ps1, tools\Test-ReleasePresentation.ps1, tools\Invoke-OfflineValidation.ps1). Идентичность продукта берётся из OmsiLaunch.Version.props. Шаги установки для пользователей приведены на странице установка; роль замыкания плагина во время работы описана на странице постоянный плагин.

Идентичность продукта (OmsiLaunch.Version.props)#

Directory.Build.props устанавливает InformationalVersion равным OmsiLaunchProductVersion без ревизии исходного кода, поэтому OmsiLaunch.exe /version выводит ровно 0.1.0-beta3.

Сборка (tools\New-ReleasePackage.ps1)#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished] (выходной каталог по умолчанию — artifacts\release) собирает пакет из уже собранных артефактов. Запись в artifacts\release, когда OmsiLaunch-<product_version>.zip уже существует, отклоняется, если не указан -AllowOverwritePublished; пакеты-кандидаты помещаются в другой каталог (офлайн-проверка использует artifacts\candidate\post-round-a).

Перед размещением каждый результат сборки проверяется на устаревание.

• OmsiLaunch.Native.x86.dll: по содержимому, а не по метке времени. Нативная сборка записывает artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt (цель WriteOmsiLaunchNativeBuildReceipt в .vcxproj): SHA-256 созданной DLL (output=) и каждого исходного файла, из которого она собрана (source=<sha256>|<path>: .cpp, .rc, .vcxproj и OmsiLaunch.Version.props). Упаковка отклоняет DLL, если её хеш не совпадает с записанным выходным (does not match its build receipt: устаревшая или посторонняя копия, какой бы ни была её метка времени), если записанный исходный файл изменился (Native source changed after the recorded build), если нативный исходный файл не учтён в квитанции или если квитанция отсутствует.
• Прослойки и управляемые сборки: по метке времени. Каждая из них должна быть не старше исходных файлов своего проекта (.cpp/.rc/.vcxproj каждой прослойки; собственный проект каждой управляемой сборки). Устаревший входной файл прерывает упаковку с Stale build artifact.

Затем пакет собирается в совершенно новом промежуточном каталоге с уникальным именем (.staging-<guid> в выходном каталоге), поэтому ни один файл от предыдущего запуска не может попасть в замыкание. Предыдущая папка OmsiLaunch-current и архивы заменяются только после прохождения всех перечисленных ниже проверок.

Затем скрипт вычисляет хеш каждого размещённого файла, записывает release-manifest.json в корень пакета в кодировке UTF-8 без BOM (результат больше не зависит от редакции PowerShell), запускает Test-ReleasePackageIntegrity.ps1 для промежуточного каталога, повторно сравнивает каждый размещённый файл плагина и OmsiLaunch.Native.x86.dll с результатом сборки, сжимает промежуточный каталог, распаковывает архив в новый временный каталог и проверяет распакованное замыкание по тому же манифесту (манифест в архиве должен быть побайтово идентичен проверенному), затем публикует промежуточный каталог как OmsiLaunch-current, архив — как OmsiLaunch-current.zip, копирует его в OmsiLaunch-<product_version>.zip (OmsiLaunch-0.1.0-beta3.zip) и записывает OmsiLaunch-0.1.0-beta3.zip.sha256, содержащий <SHA-256> <file name>. Отсутствие любого артефакта прерывает скрипт. Скрипт не выполняет сборку; сначала следует запустить Invoke-OfflineValidation.ps1 (или отдельные шаги dotnet build / MSBuild).

Структура пакета#

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

Продукту принадлежат только корневые файлы продукта, plugins\OmsiLaunch.* и .omsilaunch\. Сторонние плагины в plugins\ OmsiLaunch никогда не перечисляет, не копирует, не хеширует, не удаляет и не восстанавливает.

release-manifest.json#

Манифест — это данные, а не исполняемая политика: контроллер читает только записи plugins/. Читатель принимает файл как с UTF-8 BOM, так и без него (манифесты, записанные Windows PowerShell 5.1 до этого исправления, содержат BOM).

Использование манифеста во время работы (целостность плагина)#

Перед каждым планированием и запуском OmsiLaunchService.LoadArtifacts строит ожидаемое замыкание плагина (RuntimeArtifactSet.Load, src\OmsiLaunch.Process\RuntimeDeployment.cs):

1. Контроллер ищет release-manifest.json рядом с OmsiLaunch.exe (AppContext.BaseDirectory). Если он есть, ReleaseManifest.TryReadPluginHashes извлекает хеши plugins/* (OL_E_RELEASE_MANIFEST_INVALID, если файл не удаётся прочитать как манифест).
2. Для каждого установленного файла <root>\plugins\OmsiLaunch.* вычисляется хеш (SHA-256), который сравнивается:
   • при наличии манифеста — с хешем из манифеста; записывается диагностическое сообщение плана plugin.integrity.reference = manifest. Файл отсутствует → OL_E_PERMANENT_PLUGIN_MISSING; файл есть, но не указан в манифесте → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE; хеш отличается → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH (reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree).
   • без манифеста (раскладка разработки или установка без манифеста) — можно проверить только наличие и самосогласованность относительно копии из пакета рядом с контроллером; plugin.integrity.reference = self.
3. Ошибка делает план неисполнимым (OL_E_RUNTIME_ARTIFACT_MISSING с подробностями) или приводит к отклонению запуска (код выхода 7).

Сеанс никогда не размещает, не включает в снимок, не восстанавливает и не удаляет файлы плагина; замыкание — постоянная часть установки. x86-библиотека OmsiLaunch.Native.x86.dll загружается только из plugins\; управляемые сборки объявляют DefaultDllImportSearchPaths(AssemblyDirectory | System32).

Установка в корневой каталог OMSI#

1. Проверьте архив: сравните OmsiLaunch-0.1.0-beta3.zip с OmsiLaunch-0.1.0-beta3.zip.sha256.
2. Распакуйте архив непосредственно в корневой каталог установки OMSI (каталог, содержащий Omsi.exe). При этом размещаются корневые файлы, plugins\OmsiLaunch.* (рядом со сторонними плагинами, если они есть) и .omsilaunch\.
3. Оставьте release-manifest.json рядом с OmsiLaunch.exe: он включает проверку целостности плагина по манифесту. Манифест и двоичные файлы должны быть из одного пакета: новые двоичные файлы поверх более старого манифеста (или наоборот) приводят к тому, что каждый запуск завершается ошибкой OL_E_PERMANENT_PLUGIN_HASH_MISMATCH. Test-ReleasePresentation.ps1 -InstallPackage теперь копирует манифест вместе с файлами продукта; раньше он его пропускал, из-за чего рядом с более новыми двоичными файлами оставался старый манифест (Round A RA-007).
4. Проверьте согласованность в режиме только для чтения с помощью tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root>: installation_comparison.coherent_with_package должно быть true.
5. Не перемещайте двоичные файлы плагина в .omsilaunch\ и не переименовывайте plugins\OmsiLaunch.*.
6. Проверьте установку с помощью OmsiLaunch.exe /version, OmsiLaunch.exe profiles и /plan (см. первый сеанс).

Существующие файлы .omsilaunch\assets\splash\*.bmp сеанс никогда не перезаписывает (явно управляемый набор ресурсов сохраняется); их перезапись при распаковке нового пакета — намеренное действие пользователя.

Каталог .omsilaunch после использования#

Никакие данные не покидают компьютер. См. транзакции и восстановление после сбоя.

Удаление#

1. Убедитесь, что ни один сеанс не запущен (OmsiLaunch.exe detect, OmsiLaunch.exe session status) и нет незавершённого восстановления (OmsiLaunch.exe /recovery-status; выполните /recover, если pending равно true), чтобы файлы OMSI уже были восстановлены.
2. Удалите 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. Другие плагины не трогайте.
3. Удалите корневые файлы продукта, перечисленные в структуре выше (OmsiLaunch.exe, OmsiLaunchW.exe, nethost.dll, OmsiLaunch.*.dll, OmsiLaunch.Controller.*.json, YamlDotNet.dll, release-manifest.json, LICENSE, THIRD-PARTY-NOTICES.md).
4. Удалите .omsilaunch\ (при этом удаляются ваши профили сеанса и диагностика). Никогда не удаляйте его, пока существует journal.json.

Завершённый сеанс восстанавливает каждый файл, которым владел, поэтому дополнительная очистка не требуется. Файлы, которые сама OMSI записывает во время работы (например, [last_map] в options.cfg, кеши, laststn.osn, логи), — это обычное состояние OMSI, и они не откатываются; см. транзакции и восстановление после сбоя.

Скрипты проверки#

Оба скрипта Test-* читают OmsiLaunch.Version.props, чтобы узнать ожидаемую версию.