feat: add config flags and document namespace policy

Author: NewYaroslav

README-RU.md

@@ -35,6 +35,16 @@
 - **Поддержка MQL5** — адаптированные заголовки в каталоге `MQL5` позволяют использовать библиотеку в MetaTrader.
 - Совместимость с `C++11` – `C++17`.
 
+## Конфигурация
+
+Компиляционные флаги в `time_shield/config.hpp` позволяют адаптировать библиотеку под платформу и отключать необязательные модули:
+
+- `TIME_SHIELD_PLATFORM_WINDOWS` / `TIME_SHIELD_PLATFORM_UNIX` — определение целевой платформы.
+- `TIME_SHIELD_HAS_WINSOCK` — наличие WinSock API.
+- `TIME_SHIELD_ENABLE_NTP_CLIENT` — включает модуль `NtpClient` (по умолчанию `1` на Windows).
+
+Все заголовки библиотеки используют пространство имён `time_shield`. Для доступа к API можно писать `time_shield::` или подключать `using namespace time_shield;`.
+
 > Часть функций зависит от WinAPI и будет работать только под Windows (например, `NtpClient` или получение realtime через `QueryPerformanceCounter`).
 
 ## Установка и настройка

README.md

@@ -54,6 +54,21 @@ more academic solutions like `HowardHinnant/date`, the library:
   library in MetaTrader.
 - Compatible with `C++11`–`C++17`.
 
+
+## Configuration
+
+Compile-time flags in `time_shield/config.hpp` control optional parts of the
+library and report platform capabilities:
+
+- `TIME_SHIELD_PLATFORM_WINDOWS` / `TIME_SHIELD_PLATFORM_UNIX` — detected
+  target platform.
+- `TIME_SHIELD_HAS_WINSOCK` — set when WinSock APIs are available.
+- `TIME_SHIELD_ENABLE_NTP_CLIENT` — enables the optional `NtpClient` module
+  (defaults to `1` on Windows).
+
+All public headers place their declarations inside the `time_shield` namespace.
+Use `time_shield::` or `using namespace time_shield;` to access the API.
+
 > Some functions depend on WinAPI and work only on Windows (for example,
 > `NtpClient` or obtaining realtime via `QueryPerformanceCounter`).
 

docs/mainpage.md

@@ -27,6 +27,18 @@ portable, and suitable for scenarios like logging, serialization, MQL5 usage, an
 - ISO8601 string parsing
 - Utilities for time manipulation and conversion
 
+\section config_sec Configuration
+
+Compile-time macros in `time_shield/config.hpp` allow adapting the library to
+the target platform and toggling optional modules:
+
+- `TIME_SHIELD_PLATFORM_WINDOWS` / `TIME_SHIELD_PLATFORM_UNIX` — platform
+  detection.
+- `TIME_SHIELD_HAS_WINSOCK` — WinSock availability.
+- `TIME_SHIELD_ENABLE_NTP_CLIENT` — builds the NTP client when set to `1`.
+
+All public symbols are declared inside the `time_shield` namespace.
+
 \section examples_sec Examples
 
 Here is a simple demonstration:

include/time_shield_cpp/time_shield/config.hpp

@@ -3,10 +3,12 @@
 #define _TIME_SHIELD_CONFIG_HPP_INCLUDED
 
 /// \file config.hpp
-/// \brief Header file with preprocessor definitions for C++ standards and `constexpr` usage.
+/// \brief Configuration macros for the library.
 ///
-/// This file defines macros to check the C++ standard version being used and configure
-/// `constexpr` and `if constexpr` support accordingly.
+/// This header provides compile-time options for C++ standard detection,
+/// platform capabilities and optional features. The macros can be used to
+/// enable or disable parts of the library depending on the target platform or
+/// user preferences.
 
 #if defined(_MSVC_LANG)
 #   define TIME_SHIELD_CXX_VERSION _MSVC_LANG
@@ -41,4 +43,40 @@
 #endif
 #endif
 
+/// \name Platform detection
+///@{
+#if defined(_WIN32)
+#   define TIME_SHIELD_PLATFORM_WINDOWS 1
+#else
+#   define TIME_SHIELD_PLATFORM_WINDOWS 0
+#endif
+
+#if defined(__unix__) || defined(__unix) || defined(unix) || \
+    (defined(__APPLE__) && defined(__MACH__))
+#   define TIME_SHIELD_PLATFORM_UNIX 1
+#else
+#   define TIME_SHIELD_PLATFORM_UNIX 0
+#endif
+///@}
+
+/// \name Platform capabilities
+///@{
+#if TIME_SHIELD_PLATFORM_WINDOWS
+#   define TIME_SHIELD_HAS_WINSOCK 1
+#else
+#   define TIME_SHIELD_HAS_WINSOCK 0
+#endif
+///@}
+
+/// \name Optional features
+///@{
+#ifndef TIME_SHIELD_ENABLE_NTP_CLIENT
+#   if TIME_SHIELD_HAS_WINSOCK
+#       define TIME_SHIELD_ENABLE_NTP_CLIENT 1
+#   else
+#       define TIME_SHIELD_ENABLE_NTP_CLIENT 0
+#   endif
+#endif
+///@}
+
 #endif // _TIME_SHIELD_CONFIG_HPP_INCLUDED

include/time_shield_cpp/time_shield/ntp_client.hpp

@@ -8,10 +8,12 @@
 /// This module provides a minimal client that can query a remote NTP server over UDP
 /// and calculate the offset between local system time and the NTP-reported time.
 ///
-/// Currently only Windows is supported (WinSock-based implementation).
+/// The feature is optional and controlled by `TIME_SHIELD_ENABLE_NTP_CLIENT`.
 /// \ingroup ntp
 
-#if defined(_WIN32)
+#include "config.hpp"
+
+#if TIME_SHIELD_ENABLE_NTP_CLIENT
 
 #include "ntp_client/wsa_guard.hpp"
 #include "time_utils.hpp"
@@ -209,18 +211,22 @@ namespace time_shield {
 
 } // namespace time_shield
 
-#else // !_WIN32
+#else // !TIME_SHIELD_ENABLE_NTP_CLIENT
 
-#   warning "NtpClient is only supported on Windows for now."
+#   warning "NtpClient is disabled or unsupported on this platform."
 
 namespace time_shield {
 
+    /// \brief Placeholder used when NTP client is disabled.
     class NtpClient {
-        static_assert(sizeof(void*) == 0, "time_shield::NtpClient is only supported on Windows.");
+    public:
+        NtpClient() {
+            static_assert(sizeof(void*) == 0, "time_shield::NtpClient is disabled by configuration.");
+        }
     };
 
-}
+} // namespace time_shield
 
-#endif // _WIN32
+#endif // TIME_SHIELD_ENABLE_NTP_CLIENT
 
 #endif // _TIME_SHIELD_NTP_CLIENT_HPP_INCLUDED

include/time_shield_cpp/time_shield/ntp_client/wsa_guard.hpp

@@ -6,9 +6,15 @@
 /// \brief Singleton guard for WinSock initialization.
 /// \ingroup ntp
 
-#include <winsock2.h>  // Must be included before windows.h
-#include <ws2tcpip.h>
-#include <windows.h>   // (optional, but safe if later needed)
+#include "../config.hpp"
+
+#if TIME_SHIELD_HAS_WINSOCK
+#   include <winsock2.h>  // Must be included before windows.h
+#   include <ws2tcpip.h>
+#   include <windows.h>   // (optional, but safe if later needed)
+#else
+#   error "WsaGuard requires WinSock support"
+#endif
 #include <mutex>
 #include <string>
 
@@ -55,4 +61,5 @@ namespace time_shield {
 
 } // namespace time_shield
 
-#endif // _TIME_SHIELD_WSA_GUARD_HPP_INCLUDED
+#endif // _TIME_SHIELD_WSA_GUARD_HPP_INCLUDED
+

include/time_shield_cpp/time_shield/time_utils.hpp

@@ -16,15 +16,15 @@
 #include <time.h>       // For clock(), times(), etc.
 #include <mutex>        // For std::once_flag
 
-#if defined(_WIN32)
-    #include <Windows.h>
-#elif defined(__unix__) || defined(__APPLE__)
-    #include <unistd.h>
-    #include <sys/resource.h>
-    #include <sys/times.h>
-    #include <time.h>
+#if TIME_SHIELD_PLATFORM_WINDOWS
+#   include <Windows.h>
+#elif TIME_SHIELD_PLATFORM_UNIX
+#   include <unistd.h>
+#   include <sys/resource.h>
+#   include <sys/times.h>
+#   include <time.h>
 #else
-    #error "Unsupported platform for get_cpu_time()"
+#   error "Unsupported platform for get_cpu_time()"
 #endif
 
 namespace time_shield {
@@ -53,7 +53,7 @@ namespace time_shield {
     /// \return Current UTC timestamp in microseconds.
     /// \note Windows only. Not available on Unix-like systems.
     inline int64_t now_realtime_us() {
-#   if defined(_WIN32)
+#   if TIME_SHIELD_PLATFORM_WINDOWS
         static std::once_flag init_flag;
         static int64_t s_perf_freq = 0;
         static int64_t s_anchor_perf = 0;
@@ -196,15 +196,15 @@ namespace time_shield {
     /// \note This function attempts multiple fallback methods depending on platform capabilities.
     /// \see https://habr.com/ru/articles/282301/ — original implementation idea
     inline double get_cpu_time() noexcept {
-#   if defined(_WIN32)
+#   if TIME_SHIELD_PLATFORM_WINDOWS
         FILETIME create_time{}, exit_time{}, kernel_time{}, user_time{};
         if (GetProcessTimes(GetCurrentProcess(), &create_time, &exit_time, &kernel_time, &user_time)) {
             ULARGE_INTEGER li{};
             li.LowPart = user_time.dwLowDateTime;
             li.HighPart = user_time.dwHighDateTime;
             return static_cast<double>(li.QuadPart) / 10000000.0;
         }
-#   elif   defined(__unix__) || defined(__unix) || defined(unix) || (defined(__APPLE__) && defined(__MACH__))
+#   elif   TIME_SHIELD_PLATFORM_UNIX
         // AIX, BSD, Cygwin, HP-UX, Linux, OSX, and Solaris
 #       if defined(_POSIX_TIMERS) && (_POSIX_TIMERS > 0)
             clockid_t id = (clockid_t)-1;