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的正常模式不同。特别是，宽字符的文字可能会被拒绝或格式化。
• 模拟模式没有经过测试，因此可能出现意外的故障。

因此，使用模拟模式是不鼓励的，应该避免。在将来的版本库中，它的支持可能会被完全删除。