boost.log v2學習（1）

boost.log官方文檔翻譯學習，如有問題，請告知！

文檔目錄

1. 動機
2. 如何閱讀文檔
3. 安裝和兼容性
   1. 支持的編譯器和平台
   2. 配置和構建庫
4. 定義
5. 設計概述
6. 教程
   1. 一般的logging
   2. 帶過濾器的一般的logging
   3. 設置日志槽
   4. 創建記錄器和寫入日志
   5. 向日志屬性添加更多信息
   6. 日志記錄格式
   7. 過濾器再探
   8. 寬字符logging
7. 詳細功能描述
   1. 核心功能
   2. 日志源
   3. 日志槽前端
   4. 日志槽后端
   5. Lambda expressions
   6. 屬性
   7. 實用工具
8. 擴展library
   1. 寫你自己的日志槽
   2. 寫你自己的日志源
   3. 編寫自己的屬性
   4. 擴展庫設置支持
9. 原理和常見問題解答
   1. 為什么將字符串作為范圍名稱？
   2. 為什么作用域屬性不覆蓋現有的屬性？
   3. 為什么日志記錄在多線程應用程序中弱排序？
   4. 為什么流處理器設置的屬性不參與過濾？
   5. 為什么不使用惰性流？
   6. 為什么不使用繼承，如log4j？為什么不boost.log4j？等.
   7. 日志是否支持過程的分支？
   8. 在進程初始化和終止時，boost.log支持日志記錄嗎？
   9. 為什么我的應用程序在使用文件日志槽時崩潰？
   10. 為什么我的應用程序沒有鏈接到Boost.log？庫的命名空間有什么問題？
   11. 為什么MSVC 2010鏈接到庫時提示lnk1123：轉換到COFF期間失敗：文件無效或損壞？
10. 參考
    1. Top level header
    2. 核心部件
    3. 屬性
    4. 表達式
    5. 日志源
    6. sinks（日志槽）
    7. 實用工具庫
    8. 其他庫支持層
11. 更新日志
12. 未來發行版中的待辦事項
13. 致謝

動機

  今天的應用程序增長迅速，變得復雜，難以測試和調試。大多數應用程序在遠程站點上運行，使得一旦發生異常情況，開發人員幾乎沒有機會監視他們的執行情況，並且找出失敗的原因。此外，如果應用程序行為嚴重依賴異步側事件，例如設備反饋或其他進程活動，即使是本地調試也可能會出現問題。

  這就是日志記錄可以幫助的地方。應用程序將其執行的所有基本信息存儲到日志中，當出現問題時，該信息可用於分析程序行為並作出必要的更正。日志還有其他非常有用的應用，例如收集統計信息和突出事件（即表明某些情況已經發生或應用程序正在遇到一些問題）。這些任務已被證明是非常重要的許多現實世界的工業應用。

  此庫旨在使應用程序開發人員的日志記錄更加容易。它提供了廣泛的外接工具以及擴展庫的公共接口。

  這個庫的的主要目標是：

• 簡單。一個小示例代碼片段應該足以獲得庫的感覺，並准備使用它的基本特性。
• 可擴展性。用戶應該能夠擴展庫的功能，以便將信息收集和存儲到日志中。
• 性能。庫應該盡可能少地影響用戶應用程序的性能。

如何閱讀文檔

  文檔面向新用戶和有經驗的庫用戶。但是，用戶應該熟悉常用的Boost組件，比如sharedptr、makeshared(參見Boost.smartptr)和函數(Boost.function)。文檔的某些部分將根據需要引用其他Boost庫。

  如果這是您對該庫的第一次體驗，建議閱讀設計概述部分，以便第一眼看到該庫的功能和體系結構。安裝和教程部分將幫助您開始對庫進行試驗。本教程概述了帶有示例代碼片段的庫特性。一些教程的步驟以兩種形式呈現:簡單和高級。簡單的表單通常描述完成任務的最常見和最簡單的方法，並且建議由新用戶來閱讀。高級表單通常提供了一種擴展的方式來做同樣的事情，但是有了深入的解釋和做一些額外定制的能力。對於更有經驗的用戶來說，這種形式可能很方便，如果簡單的方法不能滿足您的需要，那么通常應該閱讀。

  除了本教程，還有一個詳細的特性描述章節。本部分描述了由本教程提供的其他工具所提供的其他工具。本章最好以案例為基礎閱讀。

  最后，但重要的是，有一個引用，它提供了對庫組件的正式描述。
  為了使這個文檔中的代碼片段保持簡單，假定下面的名稱空間別名是:

namespace logging = boost::log;
namespace sinks = boost::log::sinks;
namespace src = boost::log::sources;
namespace expr = boost::log::expressions;
namespace attrs = boost::log::attributes;
namespace keywords = boost::log::keywords;

配置和構建庫

  該庫有一個單獨編譯的部分，應該按照入門指南中所描述的那樣進行構建。不過，有一件事值得注意。如果您的應用程序包含多個模塊(例如一個exe和一個或多個dll)，使用Boost，必須以shared object(動態鏈接庫)的形式。如果您有一個單獨的可執行文件或一個模塊，可以使用Boost日志，您可以將該庫構建為一個靜態庫。

  該庫支持許多配置宏:

BOOST_LOG_DYN_LINK：

如果在用戶代碼中定義，那么庫將假定二進制文件是作為一個動態加載的庫(“dll”或“so”)構建的。否則，假定庫是在靜態模式下構建的。這個宏必須為使用日志記錄的用戶應用程序的所有翻譯單元定義或不定義。這個宏可以幫助在支持它的平台上自動鏈接。

BOOST_ALL_DYN_LINK

Same as BOOST_LOG_DYN_LINK but also affects other Boost libraries the same way.

BOOST_USE_WINAPI_VERSION

影響庫和用戶代碼的編譯。這個宏是windows。為各種Boost庫選擇目標Windows版本，包括Boost.log。為特定的Windows版本編譯的代碼很可能不會在老版本的Windows版本上運行，但是由於使用了更新的操作系統特性，可能會提高性能。該宏將具有一個與 _WIN32_WINNT相同的整數值。

BOOST_LOG_NO_THREADS

如果定義了，禁用多線程支持。影響庫和用戶代碼的編譯。如果沒有檢測到線程支持，則會自動定義宏。

BOOST_LOG_WITHOUT_CHAR

如果定義了，將禁用對窄字符日志的支持。影響庫和用戶代碼的編譯。

BOOST_LOG_WITHOUT_WCHAR_T

如果定義了，將禁用對寬字符日志的支持。影響庫和用戶代碼的編譯。

BOOST_LOG_NO_QUERY_PERFORMANCE_COUNTER

這個宏只在Windows上有用。它影響了庫和用戶代碼的編譯。如果定義了，那么在定時器屬性中禁用對QueryPerformanceCounter API 的支持。這將導致顯著的不准確的時間讀數。這個宏的目的是為了解決可能出現的問題，包括在這里和這里描述的AMD的CPU。還有一些已知的芯片組硬件故障，可能會阻止該API正常工作

BOOST_LOG_USE_NATIVE_SYSLOG

只影響庫的編譯。如果出於某種原因，沒有自動檢測到原生的SysLog API，那么就定義這個宏來強制啟用它。

BOOST_LOG_WITHOUT_DEFAULT_FACTORIES

只影響庫的編譯。如果定義了，那么設置的解析器將在沒有任何缺省工廠的情況下構建，用於過濾器和格式化程序。用戶必須在解析任何過濾器或來自字符串的格式化程序之前，在庫中注冊所有屬性。這可以大大減少二進制文件的大小。

BOOST_LOG_WITHOUT_SETTINGS_PARSERS

影響庫的編譯。如果定義了，將構建與用於設置的解析器相關的所有設施。這可以大大減少二進制文件的大小。

BOOST_LOG_WITHOUT_DEBUG_OUTPUT

只影響庫的編譯。如果定義了，Windows上的調試器輸出的支持將不會被構建。

BOOST_LOG_WITHOUT_EVENT_LOG

只影響庫的編譯。如果定義了，將不會構建對Windows事件日志的支持。定義宏還會使消息編譯器工具集變得不必要

BOOST_LOG_WITHOUT_SYSLOG

只影響庫的編譯。如果定義了，將不會構建對syslog后端的支持。

BOOST_LOG_WITHOUT_IPC

只影響庫的編譯。如果定義了，將不會構建對進程間隊列的支持。

BOOST_LOG_NO_SHORTHAND_NAMES

只影響用戶代碼的編譯。如果定義了，一些不使用的簡短的宏名稱將不可用。

BOOST_LOG_USE_COMPILER_TLS

只影響庫的編譯。這個宏支持對線程本地存儲的編譯器特性的支持。定義它可以提高性能。如果某些使用限制是可以接受的。請參見下面的評論。

BOOST_LOG_USE_STD_REGEX, BOOST_LOG_USE_BOOST_REGEX or BOOST_LOG_USE_BOOST_XPRESSIVE

只影響庫的編譯。通過定義其中一個宏，用戶可以指示Boost。使用std::regex，Boost。正則表達式或提高。在內部為字符串匹配過濾器從字符串和設置中解析。如果沒有定義這些宏，那么就可以提升。日志使用增加。默認情況下正則表達式。使用std::正則表達式或提高。Regex通常會生成較小的可執行文件，增強。Regex通常也是跑得最快的。使用Boost。xpreson可以消除對Boost的依賴。正則表達式編譯的二進制文件。注意，這些宏不會影響用戶創建的過濾表達式。

  您可以在bjam命令行中定義配置宏，就像這樣:

bjam --with-log variant=release define=BOOST_LOG_WITHOUT_EVENT_LOG define=BOOST_USE_WINAPI_VERSION=0x0600 stage

  但是在“boost/config/user.hpp”中定義配置宏可能更為方便,以便為庫和用戶的項目自動定義它們。如果沒有指定選項，那么庫將嘗試支持最全面的設置，包括對目標平台可用的所有字符類型和特性的支持。

  日志庫還使用了其他幾個需要構建的Boost庫。這些都是 Boost.Filesystem, Boost.System, Boost.DateTime, Boost.Thread and in some configurations Boost.Regex。在某些配置中，線程和在某些配置中。請參閱他們的文檔，了解關於構建過程的詳細說明。

  最后要加一點,該庫需要運行時類型信息(RTTI)，以支持庫編譯和用戶的代碼編譯。通常情況下，除了驗證RTTI支持在項目中沒有禁用之外，您不需要任何東西。

關於編譯器為TLS提供的特性的注釋

  許多被廣泛使用的編譯器支持用於管理線程本地存儲的內置特性，這在庫的幾個部分中使用。這個特性也包含在C++11標准中。一般來說，這些特性允許對存儲的訪問比任何代理實現都要高效得多。線程甚至是本地操作系統API。但是，這個特性有幾點需要注意:

• 一些操作系統不支持使用這些特性，以防在應用程序運行時動態加載的共享庫中定義了TLS。這些系統包括在Vista之前的Linux和Windows系統。Windows Vista和之后沒有這個問題。
• 從全局構造函數和破壞器中不能可靠地訪問TLS。至少在Windows上的MSVC 8.0是有這個問題的。

該庫提供了BOOST_LOG_USE_COMPILER_TLS配置宏，允許使用該特性，從而提高了庫的性能，從而提高了這些限制的成本:

• 應用程序可執行文件必須與Boost.log聯系起來。它不應該在運行時動態加載。
• 應用程序不能在全局構造函數或破壞器中使用日志記錄。

注意，BOOST_LOG_USE_COMPILER_TLS宏僅在Boost.log中控制使用TLS。但不在其他庫中使用。

關於本地wchart的注釋支持

  一些編譯器，其中最顯著的是MSVC，有一個選項可以禁用本地wchart類型，用一個標准整數類型的typedef來模擬它。從C++語言的角度來看，這種行為是不符合的，但是它可能有助於與一些難以更新的遺留代碼的兼容性。

在默認情況下，Boost(和Boost.log是其中的一部分)是建立在本地wchart的基礎上的。在撰寫本文時，用戶將不得不修改Boost.Build以啟用模擬模式。

以這種方式編譯boost.log，但是需要記住以下幾個警告:

• 編譯后的Boost.log二進制文件將導出與在構建時選擇的配置相對應的符號。
• 用戶的代碼將不得不使用與構建Boost時使用的相同的設置,否則鏈接錯誤將會出現。
• 由於在模擬模式下wchart與整數類型不可區分，因此庫的某些部分可能與本機wchart的正常模式不同。特別是，寬字符的文字可能會被拒絕或格式化。
• 模擬模式沒有經過測試，因此可能出現意外的故障。

因此，使用模擬模式是不鼓勵的，應該避免。在將來的版本庫中，它的支持可能會被完全刪除。