FOnline Engine
Current master GitHub
Документация Docs/ru/contributing/third-party/index.md

Сопровождение ThirdParty

Этот документ определяет переиспользуемый процесс движка для вендорных зависимостей в ThirdParty/. Проектные комплектные библиотеки принадлежат подключающему проекту; их выбор, интеграция, доставка и сопровождение описаны в разделе Проектные зависимости, а точный реестр и релизные свидетельства должны храниться в самом проекте.

Владение

Engine-owned build glue и FONLINE_PRUNED_FILES.md располагаются прямо в ThirdParty/<Library>/; сохранённое upstream-дерево — отдельно в ThirdParty/<Library>/<library>/, если такова структура библиотеки. Интеграция vkd3d следует этому правилу. Не считайте build glue upstream-патчем и не перезаписывайте его при обновлении upstream.

Каталоги ThirdParty/<Library>/ являются вендорными деревьями исходников во владении движка. Их используют BuildTools/cmake/stages/ThirdParty.cmake и связанные вспомогательные команды CMake.

Обычные файлы непосредственно в ThirdParty/, например emscripten, android-sdk, dotnet-runtime и xwin, закрепляют версии, которые потребляют BuildTools/buildtools.py и скрипты подготовки рабочей области или пакетов. Не добавляйте ThirdParty/FONLINE_PRUNED_FILES.md в корень: сведения об обрезке должны находиться внутри каталогов настоящих вендорных библиотек.

Сохраняйте лицензии, уведомления, README и журналы изменений библиотек, если для удаления нет ясной юридической или упаковочной причины. Неиспользуемые примеры, тесты, документацию, CI-файлы, вспомогательные скрипты, настройки редакторов, метаданные пакетов и автоматизацию релизов можно удалять, если движок не собирает и не распространяет эти части.

Запекатель полигональных спрайтов сейчас напрямую использует обрезанные деревья clipper2 и earcut: Clipper2 выполняет смещение, объединение и пересечение контуров, а earcut триангулирует внешние кольца и отверстия. Обновление любой из этих зависимостей должно охватывать Source/Tools/SpriteMeshing.cpp, Source/Tests/Test_ImageBaker.cpp, чистое запекание ресурсов и диагностику отчёта или атласа спрайтовой сетки. Проверка только компиляции не доказывает детерминированную геометрию или покрытие видимых пикселей.

Процесс обновления

Вся поверхность ThirdParty/ обновляется одним проходом: проверяются все сопровождаемые вендорные библиотеки и все корневые закрепления версий, а каждая изменившаяся зависимость получает отдельный коммит. Предпочитайте самый свежий стабильный релиз; используйте вершину master или другой ветки либо назначенный upstream тег только тогда, когда это собственная схема релизов библиотеки: стабильных релизов нет или проект намеренно отслеживает ветку.

  1. Определите upstream-релиз, тег, архив или версию пакета по домашней странице проекта, официальному каналу релизов или метаданным пакета. Сверьте кандидата с собственным каналом релизов проекта, а не только с git-тегами: в репозитории могут быть теги версий, которые никогда не выпускались в виде архива или объявления; такие теги не являются целью обновления.
  2. Подготовьте upstream-исходники вне репозитория, обычно в Workspace/ThirdPartyUpdate/, чтобы исходная загрузка оставалась доступной во время проверки вендорной разницы.
  3. Скопируйте новые исходники в соответствующий каталог ThirdParty/<Library>/. Для файлов, используемых сборкой движка, по возможности сохраняйте структуру upstream.
  4. Повторно примените обрезку из ThirdParty/<Library>/FONLINE_PRUNED_FILES.md. Обновляйте этот файл, когда намеренно удаляется новый upstream-каталог или файл.
  5. Сохраните файлы, необходимые сборке движка, публичные заголовки, исходники, лицензии и уведомления, README, журналы изменений и файлы CMake, которые по-прежнему входят в граф сборки.
  6. Отмечайте каждое локальное изменение движка внутри вендорного файла маркером (FOnline Patch) и краткой причиной. Предпочитайте однострочные комментарии рядом с изменённым условием или настройкой.
  7. Обновите версию в ThirdParty/README.md. Если обновление меняет закрепления платформенной рабочей области, обновите соответствующий обычный файл в ThirdParty/.
  8. Выполните как минимум git diff --check для затронутой зависимости. Затем проверьте минимальный путь конфигурации, сборки и тестирования подключающего проекта, использующий зависимость. Для критичных для сборки библиотек, таких как аллокатор, шейдерный инструментарий или сериализация, предпочтите функциональный проход по реальным данным, например полное запекание ресурсов или набор модульных тестов движка, а не только компиляцию и линковку. Если обновление вендорного C-кода повышает требование к стандарту языка, объявите его на цели зависимости через C_STANDARD / C_STANDARD_REQUIRED и включите нативный MSVC в проверку; кросс-сборка Windows через clang не доказывает, что MSVC принимает заголовки C11 вроде <stdatomic.h>. Текущему MSVC также требуется /experimental:c11atomics на затронутой C-цели. Помечайте вендорные каталоги включения как SYSTEM, когда их потребляют first-party единицы трансляции. Если слинкованная вендорная цель CMake публикует обычные INTERFACE_INCLUDE_DIRECTORIES, пометьте саму цель как SYSTEM; иначе её транзитивный путь может получить приоритет над прямым системным путём, и предупреждения заголовков зависимости обойдут политику сторонних предупреждений. Принадлежащая dependency копия вне ThirdParty/ меняется в том же commit: Android Java glue SDL под BuildTools/android-project/ должен точно совпадать с linked SDL, иначе JNI registration может завершить приложение в System.loadLibrary; BuildTools/tests/test_android_sdl_java_glue.py сравнивает его с vendored SDL tree.
  9. Коммитьте каждую зависимость или закрепление версии отдельно. Используйте прямое сообщение, например Update SDL to 3.4.10.

Вендорная логика CMake входит в контракт цепочки инструментов. В частности, выбор x64 assembler в AngelScript должен проверять CMAKE_ASM_MASM_COMPILER для пути MSVC/MASM и CMAKE_ASM_COMPILER для других ассемблеров после включения языка; общая проверка CMAKE_ASM_COMPILER_WORKS не является переносимой заменой в современных CMake и генераторах Visual Studio. Сохраняйте локальные исправления с маркером (FOnline Patch), выполняйте python -m unittest BuildTools.tests.test_angelscript_cmake и завершайте хотя бы один путь конфигурации, ассемблирования и линковки на затронутом хосте.

Корневые закрепления версий

Обычные файлы непосредственно в ThirdParty/ (emscripten, android-ndk, android-sdk, android-api, dotnet-runtime, iOS-sdk, xwin) закрепляют версии инструментов, которые BuildTools/buildtools.py загружает при подготовке рабочей области и пакетов. Они входят в регулярный проход обновления: изменяйте файл закрепления и соответствующую запись ThirdParty/README.md одним коммитом на каждое закрепление и проверяйте через использующую его платформенную сборку: web, Android, iOS или кросс-сборку Windows. Два закрепления являются значениями политики, а не целями свежести: android-api задаёт намеренный минимум поддерживаемых устройств, а iOS-sdk следует требованиям релиза подключающего проекта. Меняйте их только как явное продуктовое решение, а не в рамках механического обновления.

Сильно изменённые форки

Зависимость, вендорная копия которой содержит существенные семантические изменения (FOnline Patch), не охватывается механическим процессом «скопировать и обрезать». Текущий пример — AngelScript: поверх upstream-форка в него встроены nullable-система типов T? движка, выравнивание стека VM, нормализация аргументов native call, дополнительная инструкция байткода и режим современных потоков. Повторная вендоризация требует сверки каждого изменённого участка с новым upstream; рассматривайте её как отдельную задачу с собственным планом и полной регрессионной проверкой скриптов и VM и пропускайте такие зависимости в обычном проходе обновления.

Для fork, отслеживающего branch или WIP-состояние, записывайте точный upstream commit вместе с датой snapshot в ThirdParty/README.md; одной строки upstream version недостаточно для воспроизводимого дерева исходников.

Добавление новой зависимости движка

Добавляйте переиспользуемые зависимости в движок, только если они действительно являются частью его поверхности. Проектные нативные мосты и SDK принадлежат подключающему проекту и проходят проверку владельца из раздела Проектные зависимости.

Для новой зависимости движка:

  • добавьте вендорные исходники в ThirdParty/<Library>/;
  • добавьте ThirdParty/<Library>/FONLINE_PRUNED_FILES.md;
  • добавьте запись о версии в ThirdParty/README.md;
  • подключите зависимость в BuildTools/cmake/stages/ThirdParty.cmake или соседней переиспользуемой вспомогательной команде;
  • зарегистрируйте необходимый перехват find_package(), чтобы исключить случайное использование библиотеки хоста;
  • отмечайте локальные изменения вендорных файлов как (FOnline Patch);
  • проверьте, предоставляет ли библиотека хук аллокатора, и либо подключите его к SafeAlloc, либо зафиксируйте причину отказа. Библиотеки, выделяющие память через C malloc, используют кучу CRT вместо rpmalloc, оказываются вне контракта движка при нехватке памяти и невидимы статистике аллокатора и Tracy. Хуки бывают разными: setter времени выполнения (SDL_SetMemoryFunctions, asSetGlobalMemoryFunctions, Effekseer::SetMallocFunc), структура при инициализации (png_create_read_struct_2, bson_mem_set_vtable) или символ времени компиляции, определяемый потребителем (UFBX_EXTERNAL_MALLOC). Читайте реализацию хука, а не только объявление: LibreSSL по-прежнему экспортирует CRYPTO_set_mem_functions, но его тело лишь возвращает 0. Также проверьте, копируется ли vtable или сохраняется по указателю и освобождается ли выровненное выделение тем же обратным вызовом, что и невыровненное: обе ошибки уже встречались в этой кодовой базе. См. Essentials;
  • проверьте как минимум один путь конфигурации и сборки, потребляющий зависимость.

Сведения об обрезке

Каждый каталог библиотеки должен описывать удалённые upstream-пути в FONLINE_PRUNED_FILES.md. Запись должна быть механической и простой для повторного применения:

FOnline ThirdParty pruning notes

This vendored copy is intentionally trimmed for the engine build. When updating
from upstream, remove these paths again after copying the new version.

Removed paths:
- docs/
- examples/
- tests/

Не перечисляйте сохранённые файлы многострочными пунктами, которые простые скрипты сопровождения могут принять за удалённые пути. Если сохранённые файлы нужно отметить, перечислите их в одной строке.

Маркер локального патча

Используйте (FOnline Patch) только для изменений сторонних файлов. Маркер должен объяснять отличие от upstream, например:

option(ZLIB_BUILD_SHARED "Enable zlib shared library" OFF) # (FOnline Patch) engine links zlib statically.

Не переформатируйте крупные upstream-файлы только ради добавления маркера. Сохраняйте локальную разницу достаточно небольшой, чтобы следующее обновление можно было применить вручную.

Введите запрос.