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

Этот документ фиксирует поддерживаемый контракт подключения 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