remove windows.h from all headers in std folder (#623)

CMakeLists.txt

@@ -210,7 +210,7 @@ set(HEADER_FILES
         include/quill/core/ThreadContextManager.h
         include/quill/core/TimeUtilities.h
         include/quill/core/UnboundedSPSCQueue.h
-        include/quill/core/Utf8Conv.h
+        include/quill/backend/Utf8Conv.h
 
         include/quill/filters/Filter.h
 

examples/recommended_usage/CMakeLists.txt

@@ -2,6 +2,7 @@ add_subdirectory(quill_wrapper)
 
 set(EXAMPLE_TARGETS
         quill_example_recommended_usage
+        quill_example_std_types_logging
         quill_example_use_overwrite_macros
 )
 

examples/recommended_usage/std_types_logging.cpp

@@ -0,0 +1,64 @@
+/**
+ * This example demonstrates the recommended setup for the Quill library.
+ *
+ * It is advisable to encapsulate the header-only library into a static library, which
+ * you build once and link to your main  application.
+ * This library should include `quill/backend` in the .cpp files.
+ *
+ * In your application, include only the following headers for logging:
+ *
+ * - For logger lookup or creation:
+ *   #include "quill/Frontend.h"
+ *
+ * - For sink creation:
+ *   #include "quill/sinks/.."
+ *
+ * - For logging:
+ *   #include "quill/Logger.h"
+ *   #include "quill/LogMacros.h"
+ */
+
+// Include our wrapper lib
+#include "quill_wrapper/quill_wrapper.h"
+
+// We need only those two headers in order to log
+#include "quill/LogMacros.h"
+#include "quill/Logger.h"
+
+// include the relevant header from `std` folder for serialising STL types performing the formatting
+// on the backend logging thread see
+// https://quillcpp.readthedocs.io/en/latest/cheat_sheet.html#logging-stl-library-types for example:
+#include "quill/std/Array.h"
+#include "quill/std/Pair.h"
+
+#if defined(_WIN32)
+  // also required for wide string logging on windows
+  #include "quill/std/WideString.h"
+#endif
+
+// We utilize the global_logger_a from the quill_wrapper library.
+// The use of a global logger is optional.
+// Alternatively, we could include "quill/Frontend.h" and use `quill::Frontend::get_logger(..)`
+// to obtain the created logger, or we could store it as a class member.
+extern quill::Logger* global_logger_a;
+
+int main()
+{
+  setup_quill("std_types_logging.log");
+
+  // Change the LogLevel to print everything
+  global_logger_a->set_log_level(quill::LogLevel::TraceL3);
+  std::array<std::string, 2> array = {"test", "string"};
+  LOG_INFO(global_logger_a, "log an array {}", array);
+
+  std::pair<std::string, uint32_t> pair = {"data", 1};
+  LOG_INFO(global_logger_a, "log a pair {}", pair);
+
+#if defined(_WIN32)
+  std::array<std::wstring, 2> wide_array = {L"wide_test", L"wide_string"};
+  LOG_INFO(global_logger_a, "log wide array {}", wide_array);
+
+  std::pair<std::wstring, uint32_t> wide_pair = {L"wide_data", 1};
+  LOG_INFO(global_logger_a, "log a wide pair {}", wide_pair);
+#endif
+}

include/quill/backend/BackendWorker.h

@@ -6,6 +6,10 @@
 
 #pragma once
 
+#if defined(_WIN32)
+  #include "quill/backend/Utf8Conv.h"
+#endif
+
 #include "quill/backend/BackendOptions.h"
 #include "quill/backend/BackendUtilities.h"
 #include "quill/backend/BacktraceStorage.h"
@@ -129,6 +133,8 @@ class BackendWorker
    */
   QUILL_ATTRIBUTE_COLD void run(BackendOptions const& options)
   {
+    _ensure_linker_retains_symbols();
+
     std::thread worker(
       [this, &options]()
       {
@@ -234,6 +240,27 @@ class BackendWorker
   }
 
 private:
+  /**
+   * Calls some functions that we forward declare on the backend and tries to ensure the linker
+   * includes the necessary symbols
+   */
+  QUILL_ATTRIBUTE_COLD static void _ensure_linker_retains_symbols()
+  {
+    // Calls to ensure it is retained by the linker.
+    QUILL_MAYBE_UNUSED static auto thread_name = get_thread_name();
+    (void)thread_name;
+
+#if defined(_WIN32)
+    std::wstring const dummy = L"dummy";
+    QUILL_MAYBE_UNUSED static auto encode1 = detail::utf8_encode(dummy);
+    (void)encode1;
+
+    QUILL_MAYBE_UNUSED static auto encode2 =
+      detail::utf8_encode(reinterpret_cast<std::byte const*>(dummy.data()), dummy.size());
+    (void)encode2;
+#endif
+  }
+
   /**
    * Backend worker thread main function
    */
@@ -319,7 +346,6 @@ class BackendWorker
     // Cache this thread's id
     _worker_thread_id.store(get_thread_id());
 
-    // Call get_thread_name() to ensure it is retained by the linker.
     (void)get_thread_name();
 
     // Double check or modify some backend options before we start

include/quill/core/Utf8Conv.h → include/quill/backend/Utf8Conv.h

@@ -37,7 +37,7 @@ namespace detail
  *
  * @remarks If the input string is empty or the conversion fails, an empty string is returned.
  */
-inline std::string utf8_encode(std::byte const* data, size_t wide_str_len)
+QUILL_NODISCARD QUILL_EXPORT QUILL_ATTRIBUTE_USED inline std::string utf8_encode(std::byte const* data, size_t wide_str_len)
 {
   // Check if the input is empty
   if (wide_str_len == 0)
@@ -77,7 +77,7 @@ inline std::string utf8_encode(std::byte const* data, size_t wide_str_len)
   return ret_val;
 }
 
-inline std::string utf8_encode(std::wstring_view str)
+QUILL_NODISCARD QUILL_EXPORT QUILL_ATTRIBUTE_USED inline std::string utf8_encode(std::wstring_view str)
 {
   return utf8_encode(reinterpret_cast<std::byte const*>(str.data()), str.size());
 }

include/quill/core/Codec.h

@@ -26,6 +26,13 @@ QUILL_BEGIN_NAMESPACE
 
 namespace detail
 {
+
+#if defined(_WIN32)
+/** We forward declare these to avoid including Utf8Conv.h **/
+extern std::string utf8_encode(std::wstring_view str);
+extern std::string utf8_encode(std::byte const* data, size_t wide_str_len);
+#endif
+
 /**
  * C++14 implementation of C++20's remove_cvref
  */

include/quill/sinks/ConsoleSink.h

@@ -49,10 +49,6 @@ class MacroMetadata;
  */
 class ConsoleColours
 {
-private:
-  // define our own to avoid including windows.h in the header..
-  using WORD = unsigned short;
-
 public:
   enum class ColourMode
   {
@@ -521,7 +517,7 @@ class ConsoleSink : public StreamSink
 
 private:
 #if defined(_WIN32)
-  QUILL_NODISCARD ConsoleColours::WORD _set_foreground_colour(ConsoleColours::WORD attributes)
+  QUILL_NODISCARD WORD _set_foreground_colour(WORD attributes)
   {
     CONSOLE_SCREEN_BUFFER_INFO orig_buffer_info;
     auto const out_handle = reinterpret_cast<HANDLE>(_get_osfhandle(_fileno(_file)));

include/quill/std/Array.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/format.h"
 #include "quill/bundled/fmt/ranges.h"

include/quill/std/Deque.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/ForwardList.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/List.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/Map.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 #include "quill/std/Pair.h"
 
 #include "quill/bundled/fmt/ranges.h"

include/quill/std/Optional.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/std.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/Pair.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/Set.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/UnorderedMap.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 #include "quill/std/Pair.h"
 
 #include "quill/bundled/fmt/ranges.h"

include/quill/std/UnorderedSet.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/Vector.h

@@ -10,7 +10,6 @@
 #include "quill/core/Codec.h"
 #include "quill/core/DynamicFormatArgStore.h"
 #include "quill/core/InlinedVector.h"
-#include "quill/core/Utf8Conv.h"
 
 #include "quill/bundled/fmt/ranges.h"
 #include "quill/bundled/fmt/format.h"

include/quill/std/WideString.h

@@ -7,12 +7,10 @@
 #pragma once
 
 #if defined(_WIN32)
-
   #include "quill/core/Attributes.h"
   #include "quill/core/Codec.h"
   #include "quill/core/DynamicFormatArgStore.h"
   #include "quill/core/InlinedVector.h"
-  #include "quill/core/Utf8Conv.h"
 
   #include "quill/bundled/fmt/format.h"