Skip to content

library-integration-guidelines-RU.md

Latest commit

 

History

History
70 lines (43 loc) · 4.82 KB

library-integration-guidelines-RU.md

File metadata and controls

70 lines (43 loc) · 4.82 KB

Рекомендации по интеграции библиотеки

Этот документ фиксирует поддерживаемый контракт подключения Time Shield как header-only зависимости.

Канонический язык

Канонической версией этого документа является английская:

  • docs/library-integration-guidelines.md

Поддерживаемые варианты интеграции

Time Shield является header-only библиотекой. Обычные поддерживаемые пути подключения:

  • CMake find_package(TimeShield CONFIG REQUIRED)
  • CMake add_subdirectory(...)
  • ручное подключение include path в non-CMake сборках

Если доступен CMake, подключайте экспортируемый target:

target_link_libraries(app PRIVATE time_shield::time_shield)

Несколько статических библиотек

Допустимо, чтобы несколько статических библиотек в составе одной итоговой программы зависели от time_shield::time_shield.

Это не создаёт проблемы дублирования исходников, пока потребители:

  • обычным образом подключают публичные заголовки Time Shield
  • не компилируют приватные копии внутренностей библиотеки как отдельные .cpp файлы
  • не смешивают несовместимую compile-time конфигурацию в одной итоговой программе

Контракт NTP сервиса

NtpTimeService является header-only и поддерживает стандарты C++11, C++14 и C++17.

  • сервис использует immortal singleton, чтобы избежать проблем порядка разрушения статических объектов
  • во время обычной работы геттеры сохраняют ленивый старт
  • во время завершения процесса сервис не перезапускает фоновую работу и переходит на fallback через realtime и последний закешированный offset
  • в общем случае C++17+ позволяет использовать более простой singleton-storage паттерн через inline variables, а для NtpTimeService пользовательский contract одинаков в C++11/C++14/C++17

Линковка на Windows

Когда на Windows включён TIME_SHIELD_ENABLE_NTP_CLIENT=ON, NTP-стек требует платформенную socket library.

Поддерживаемое поведение:

  • если используется экспортируемый CMake target time_shield::time_shield, нужная Windows socket library приходит транзитивно
  • при ручной интеграции без CMake target эту библиотеку нужно добавить самостоятельно (для Windows это ws2_32)

Согласованность конфигурации

Не смешивайте несовместимую compile-time конфигурацию в рамках одной итоговой программы.

В частности:

  • все потребители в составе одной программы должны одинаково трактовать TIME_SHIELD_ENABLE_NTP_CLIENT
  • публичное поведение, зависящее от compile-time конфигурации, должно быть согласованным между статическими библиотеками и финальным приложением

Практический checklist

Перед финализацией интеграции проверьте:

  • программа по возможности линкуется через CMake target time_shield::time_shield
  • несколько статических библиотек подключают только публичные заголовки Time Shield и не собирают приватные копии внутренностей
  • NtpTimeService используется без ownership-макросов и без специального owning TU
  • Windows-сборки с включённым NTP получают socket library транзитивно либо добавляют её вручную в non-CMake сценариях
  • все target-ы итоговой программы используют совместимую compile-time конфигурацию Time Shield