Boost C++ 库

……被誉为全球最受尊敬、设计最精良的 C++ 库项目之一。 Herb SutterAndrei Alexandrescu, C++ Coding Standards

Boost.Config - Boost C++ 函数库
Next

Boost.Config

Vesa Karvonen, John Maddock Beman Dawes

根据 Boost 软件许可证版本 1.0 发布。(参见随附文件 LICENSE_1_0.txt 或在 https://boost.ac.cn/LICENSE_1_0.txt 复制)


Boost 已为大多数常用编译器和平台预先配置好;您应该能够“按原样”使用 boost。由于编译器是独立于标准库配置的,即使您用第三方标准库(如 STLport)替换了编译器的标准库,默认配置也应该能正常工作。

不尝试重新配置而“按原样”使用 boost 是推荐的使用 boost 的方法。不过,您也可以运行 configure 脚本,并且提供了回归测试,允许您使用您的特定编译器设置来测试当前的 boost 配置。

Boost 库用户可以通过访问我们的 Github 并提交支持请求,来请求对其他编译器或平台的支持。

Boost 库实现通过以下方式访问配置宏:

#include <boost/config.hpp>

虽然 Boost 库用户不需要直接包含该文件,或使用那些配置宏,但这种用法是可以接受的。配置宏已经过文档说明,阐述了它们的目的、用法和限制,使得它们既可供 Boost 库代码使用,也可供用户代码使用。

Boost 的 信息宏辅助宏 是为 Boost 用户以及我们内部使用而设计的。但请注意,功能测试宏缺陷测试宏 是为 Boost 库内部使用而设计的,而非用户代码,因此它们可能随时更改(尽管不会进行无谓的更改)。由配置宏更改引起的 Boost 库问题可以通过 Boost 回归测试捕获,因此 Boost 库会更新以适应这些更改。相比之下,Boost 库用户代码可能会在宏更改时无预警地受到不利影响。了解用户代码中使用的宏的更改的最佳方法是关注 Boost 开发者列表上的讨论。

[Important] 重要提示

此 configure 脚本仅用于设置 Boost 头文件以与特定编译器配合使用。它对 Boost.Build 或库的构建方式没有影响。

如果您知道 boost 对您的特定设置配置不正确,并且您使用的是类 Unix 平台,那么您可能希望尝试运行 boost configure 脚本来改善情况。在 shell 命令提示符下,您需要 `cd` 进入 `/libs/config/` 目录,然后键入

sh ./configure

您将看到脚本在进行回归测试时检查的项目的列表。请注意,configure 脚本仅在编译器名称为 g++、c++ 或 CC 时才会真正自动检测您的编译器。如果您使用的是其他编译器,则需要设置一个或多个以下环境变量:

变量

描述

CXX

编译器的名称,例如 `c++`。

CXXFLAGS

要使用的编译器标志,例如 `-O2`。

LDFLAGS

要使用的链接器标志,例如 `-L/mypath`。

LIBS

要链接的任何库,例如 `-lpthread`。

例如,使用 HP aCC 运行 configure 脚本,您可能会使用类似如下的命令:

export CXX="aCC"
export CXXFLAGS="-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
   -DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"
export LDFLAGS="-DAportable"
export LIBS="-lpthread"
sh ./configure

无论您如何运行 configure 脚本,当它完成时,您将在 `/libs/config/` 目录中找到一个名为 `user.hpp` 的新头文件。请注意,configure 默认情况下不会将此头文件安装到您的 boost include 路径中。此头文件包含 configure 脚本生成的所有选项,外加一个包含默认版本的 `/boost/config/` 下)中用户可设置选项的头文件部分。您可以通过以下两种方式使用此头文件:

  • 选项 1:将头文件复制到 `/boost/config/` 中,以替换 boost 提供的默认 user.hpp。此选项只允许一种配置生成的设置;Boost 开发者应避免此选项,因为它存在意外将配置修改后的 `` 提交到 svn 存储库的风险(这不会受到欢迎!)。
  • 选项 2:为头文件指定一个更易记的名称,并将其放在方便的位置;然后,定义宏 `BOOST_USER_CONFIG` 指向它。例如,创建一个新的子目录 `/boost/config/user/`,并将头文件复制到那里;例如,命名为 `multithread-gcc-config.hpp`。然后,在编译时添加命令行选项:`-DBOOST_USER_CONFIG=""`,boost 将使用新的配置头文件。此选项允许您生成多个配置头文件,并将它们与 boost 源分开——这样源更新就不会干扰您的配置。

有一些配置选项代表用户选择,而不是编译器缺陷或特定于平台的选项。这些列在 `` 中,以及 configure 生成的 `user.hpp` 头文件的开头。您可以在命令行上定义这些选项,或通过编辑 `` 来定义它们,它们列在下表中:

描述

BOOST_USER_CONFIG

如果定义了此宏,它应指向用户配置文件名,该文件将在任何 boost 配置文件之前被包含。如果未定义,则默认为 ``。

BOOST_COMPILER_CONFIG

如果定义了此宏,它应指向要使用的编译器配置文件名。定义此宏会绕过编译器选择逻辑,并消除对包含该逻辑的头文件的依赖。例如,如果您使用的是 gcc,则可以将 BOOST_COMPILER_CONFIG 定义为 ``。

BOOST_STDLIB_CONFIG

如果定义了此宏,它应指向要使用的标准库配置文件名。定义此宏会绕过标准库选择逻辑,并消除对包含该逻辑的头文件的依赖。例如,如果您使用的是 STLport,则可以将 `BOOST_STDLIB_CONFIG` 定义为 ``。

BOOST_PLATFORM_CONFIG

如果定义了此宏,它应指向要使用的平台配置文件名。定义此宏会绕过平台选择逻辑,并消除对包含该逻辑的头文件的依赖。例如,如果您在 Linux 上编译,则可以将 `BOOST_PLATFORM_CONFIG` 定义为 ``。

BOOST_NO_COMPILER_CONFIG

如果定义了此宏,则不选择或包含编译器配置文件。当编译器完全符合标准,或当用户头文件(见 `BOOST_USER_CONFIG`)已添加了任何必要的选项(例如由 autoconf 生成的 configure 脚本)时,则定义此宏。

BOOST_NO_STDLIB_CONFIG

如果定义了此宏,则不选择或包含标准库配置文件。当标准库完全符合标准,或当用户头文件(见 `BOOST_USER_CONFIG`)已添加了任何必要的选项(例如由 autoconf 生成的 configure 脚本)时,则定义此宏。

BOOST_NO_PLATFORM_CONFIG

如果定义了此宏,则不选择或包含平台配置文件。当平台完全符合标准(且没有有用的额外功能)时,或当用户头文件(见 `BOOST_USER_CONFIG`)已添加了任何必要的选项(例如由 autoconf 生成的 configure 脚本)时,则定义此宏。

BOOST_NO_CONFIG

等同于定义 `BOOST_NO_COMPILER_CONFIG`、`BOOST_NO_STDLIB_CONFIG` 和 `BOOST_NO_PLATFORM_CONFIG`。

BOOST_STRICT_CONFIG

对于比已知最新版本更新的编译器版本,正常行为是假定它们具有与最新已知版本相同的缺陷。通过设置此定义,则假定比已知最新版本更新的编译器版本完全符合标准。这可能最适用于 boost 开发者或测试人员,以及那些希望使用 boost 来测试 beta 编译器版本的人。

BOOST_ASSERT_CONFIG

当设置此标志时,如果配置发现任何未知项,它将停止并显示 `#error` 而不是继续。Boost 回归测试人员应设置此定义,任何想要快速检查 boost 是否在其平台上受支持的人也应如此。

BOOST_DISABLE_THREADS

当定义此宏时,将禁用线程支持,即使编译器在其当前翻译模式下支持多线程。

BOOST_DISABLE_WIN32

当定义此宏时,将禁用 Win32 特定 API 的使用,即使这些 API 可用。除非设置了 `BOOST_HAS_PTHREADS`,否则它还会将 `BOOST_DISABLE_THREADS` 设置为有效。当配置系统检测到编译器处于“严格模式”时,可能会自动设置此选项。

BOOST_DISABLE_ABI_HEADERS

阻止 boost 头文件包含任何通常用于控制结构打包和对齐的 prefix/suffix 头文件。

BOOST_ABI_PREFIX

一个前缀头文件,用于替换 boost.config 通常会选择的任何内容;任何替换项都应根据需要设置结构打包和对齐选项。

BOOST_ABI_SUFFIX

一个后缀头文件,用于替换 boost.config 通常会选择的任何内容;任何替换项都应撤销前缀头文件的影响。

BOOST_ALL_DYN_LINK

在 Microsoft Windows 上,强制所有具有独立源的库都作为 dll 而不是静态库进行链接(此宏用于启用 `__declspec(dllimport)` 修饰符,以便编译器知道在 dll 中查找哪些符号而不是在静态库中查找)。请注意,有些库只能静态链接(例如 Boost.Test),而有些库只能动态链接(例如 Boost.Thread),在这些情况下,此宏无效。

BOOST_WHATEVER_DYN_LINK

在 Microsoft Windows 上,强制库“whatever”作为 dll 而不是静态库进行链接:将宏名称中的 `WHATEVER` 部分替换为您想要动态链接的库的名称,例如使用 `BOOST_DATE_TIME_DYN_LINK` 或 `BOOST_REGEX_DYN_LINK` 等(此宏用于启用 `__declspec(dllimport)` 修饰符,以便编译器知道在 dll 中查找哪些符号而不是在静态库中查找)。请注意,有些库只能静态链接(例如 Boost.Test),而有些库只能动态链接(例如 Boost.Thread),在这些情况下,此宏不受支持。

BOOST_ALL_NO_LIB

告诉配置系统不要自动选择要链接的库。通常,如果编译器支持 `#pragma lib`,则通过包含该库的头文件之一,就可以自动选择并链接正确的库构建变体。此宏会关闭该功能。

BOOST_WHATEVER_NO_LIB

告诉配置系统不要自动选择要链接的库“whatever”,将宏名称中的 `WHATEVER` 替换为库的名称;例如 `BOOST_DATE_TIME_NO_LIB` 或 `BOOST_REGEX_NO_LIB`。通常,如果编译器支持 `#pragma lib`,则通过包含该库的头文件之一,就可以自动选择并链接正确的库构建变体。此宏会关闭该功能。

BOOST_LIB_DIAGNOSTIC

使自动链接代码输出诊断消息,指示选择的链接库的名称。

BOOST_LIB_BUILDID

如果您使用 `--buildid` 选项构建了 Boost,则将此宏设置为您传递给 bjam 的相同值。例如,如果您使用 `bjam address-model=64 --buildid=amd64` 构建,则用 `-DBOOST_LIB_BUILDID=amd64` 编译您的代码,以确保在链接时选择正确的库。

BOOST_LIB_TOOLSET

覆盖要链接的库名称的工具集部分;请注意,如果定义了此宏,则必须将其定义为带引号的字符串字面量,例如“abc”。

通过在编译器命令行上设置各种宏或通过编辑 ``,可以以多种方式优化 boost 配置设置。

Boost 的配置结构如下:首先包含用户配置(如果未定义 `BOOST_USER_CONFIG`,则默认为 ``)。这会设置任何用户定义的策略,并让用户配置有机会影响后续操作。

接下来包含编译器、标准库和平台配置文件。这些通过宏(`BOOST_COMPILER_CONFIG` 等,参见用户可设置宏)进行包含;如果相应宏未定义,则包含一个单独的头文件来检测当前使用的编译器/标准库/平台并进行设置。如果设置了相应的 `BOOST_NO_XXX` 宏(例如 `BOOST_NO_COMPILER_CONFIG` 来禁用包含任何编译器配置文件 - 参见用户可设置宏),则可以指示配置完全忽略这些头文件。

最后,boost 配置头文件包含 ``;此头文件包含任何样板配置代码 - 例如,当一个 boost 宏被设置时,意味着另一个宏也必须被设置。

以下用法示例代表了部分可能性:

假设我们正在使用 Visual C++ 6 和 STLport 4.0 来构建 boost。假设我们目前不打算更新我们的编译器或标准库。为了在更新 boost 时避免依赖关系中断,我们可能希望“固定”我们的配置头文件,这样我们只需要在 boost 代码本身发生变化时才需要重新构建项目,而不是因为 boost 配置已针对更新版本的 Visual C++ 或 STLport 进行了更新。我们将首先认识到正在使用的配置文件是:编译器使用 ``,标准库使用 ``,平台使用 ``。接下来,我们将创建自己的私有配置目录:`boost/config/mysetup/`,并将配置文件复制到其中。最后,打开 `` 并编辑以下定义:

#define BOOST_COMPILER_CONFIG "boost/config/mysetup/visualc.hpp"
#define BOOST_STDLIB_CONFIG "boost/config/mysetup/stlport.hpp"
#define BOOST_USER_CONFIG "boost/config/mysetup/win32.hpp"

现在,当您使用 boost 时,其配置头文件将直接指向我们的“固定”版本,并忽略默认版本。您现在将免受更新 boost 时配置更改的影响。此技术对于想要修改某些 boost 配置文件的用户也很有用;例如,如果您正在使用 boost 尚未支持的 beta 编译器版本。

假设您正在使用一个完全符合标准的编译器来使用 boost;您不关心旧版本编译器可能存在的 bug,因为您知道当前版本不需要设置任何配置宏。在这种情况下,您可以在命令行上或在 `` 中定义 `BOOST_NO_COMPILER_CONFIG`,从而完全跳过编译器配置文件(实际上,您会跳过两个头文件:一个用于检测编译器类型,另一个用于为它配置 boost)。这有两个后果:第一个是需要编译的代码量减少,第二个是您消除了对两个 boost 头文件的依赖。

如果您在类 Unix 平台上工作,则可以使用 configure 脚本根据您当前的编译器设置生成“固定”配置 - 参见使用 configure 脚本了解更多详情

boost 配置库在 `/boost/config/test/` 子目录下提供了一整套回归测试程序。

文件

描述

config_info.cpp

打印出您的编译器/标准库/平台设置的详细描述,以及您当前的 boost 配置。此程序提供的信息对于设置 boost 配置文件很有用。如果您报告 boost 对您的编译器/库/平台配置不正确,请在报告所需的更改时附带此程序的输出。

config_test.cpp

一个集成的测试程序,包含大多数单独的测试用例。这提供了一个快速检查,以查看 boost 是否已为您的编译器/库/平台正确配置。

limits_test.cpp

测试您的标准库的 `std::numeric_limits` 实现(如果定义了 `BOOST_NO_LIMITS`,则为其 Boost 提供的替代项)。此测试文件在大多数 numeric_limits 版本下都会失败,主要是由于某些编译器处理 NAN 和 infinity 的方式。

no_*pass.cpp

单个编译器缺陷测试文件。这些文件中的每一个都应该可以编译,如果其中一个不能编译,则需要定义相应的 `BOOST_NO_XXX` 宏 - 有关具体细节,请参见每个测试文件。

no_*fail.cpp

单个编译器缺陷测试文件。这些文件中的每一个都不应该可以编译,如果其中一个可以编译,则表示不应定义相应的 `BOOST_NO_XXX` 宏 - 有关具体细节,请参见每个测试文件。

has_*pass.cpp

单个功能测试文件。如果其中一个不能编译,则表示不应定义相应的 `BOOST_HAS_XXX` 宏 - 有关具体细节,请参见每个测试文件。

has_*fail.cpp

单个功能测试文件。如果其中一个可以编译,则表示可以安全地定义相应的 `BOOST_HAS_XXX` 宏 - 有关具体细节,请参见每个测试文件。

虽然您可以单独运行配置回归测试文件,但数量相当多,因此有两个快捷方式可以帮助您:

或者,您可以像这样运行 configure 脚本:

./configure --enable-test

在这种情况下,脚本将测试当前配置,而不是从头开始创建新的配置。

如果您正在为新平台/库/编译器报告这些测试结果,请包含完整的编译器输出日志、`config_info.cpp` 的输出以及 pass/fail 测试结果。


Next