From 898841e640e0c2aa3564cde46659fb479a65841c Mon Sep 17 00:00:00 2001 From: Matias Capeletto Date: Wed, 30 May 2007 04:49:28 +0000 Subject: [PATCH] quickbook config docs [SVN r37818] --- doc/Jamfile.v2 | 30 + doc/acknowledgements.qbk | 29 + doc/config.qbk | 57 + doc/configuring_boost.qbk | 434 +++ doc/guidelines.qbk | 189 ++ doc/html/HTML.manifest | 5 + doc/html/boost_config/acknowledgements.html | 54 + .../boost_config/boost_macro_reference.html | 2803 +++++++++++++++++ .../guidelines_for_boost_authors.html | 295 ++ doc/html/boost_config/rationale.html | 132 + doc/html/boostbook.css | 582 ++++ doc/html/images/callouts/1.png | Bin 0 -> 391 bytes doc/html/images/callouts/10.png | Bin 0 -> 485 bytes doc/html/images/callouts/11.png | Bin 0 -> 410 bytes doc/html/images/callouts/12.png | Bin 0 -> 488 bytes doc/html/images/callouts/13.png | Bin 0 -> 509 bytes doc/html/images/callouts/14.png | Bin 0 -> 499 bytes doc/html/images/callouts/15.png | Bin 0 -> 507 bytes doc/html/images/callouts/2.png | Bin 0 -> 446 bytes doc/html/images/callouts/3.png | Bin 0 -> 431 bytes doc/html/images/callouts/4.png | Bin 0 -> 441 bytes doc/html/images/callouts/5.png | Bin 0 -> 423 bytes doc/html/images/callouts/6.png | Bin 0 -> 431 bytes doc/html/images/callouts/7.png | Bin 0 -> 397 bytes doc/html/images/callouts/8.png | Bin 0 -> 434 bytes doc/html/images/callouts/9.png | Bin 0 -> 420 bytes doc/html/images/caution.png | Bin 0 -> 4286 bytes doc/html/images/home.png | Bin 0 -> 1105 bytes doc/html/images/important.png | Bin 0 -> 4666 bytes doc/html/images/next.png | Bin 0 -> 768 bytes doc/html/images/note.png | Bin 0 -> 4648 bytes doc/html/images/prev.png | Bin 0 -> 741 bytes doc/html/images/tip.png | Bin 0 -> 3902 bytes doc/html/images/up.png | Bin 0 -> 766 bytes doc/html/images/warning.png | Bin 0 -> 3927 bytes doc/html/index.html | 983 ++++++ doc/macro_reference.qbk | 827 +++++ doc/rationale.qbk | 82 + 38 files changed, 6502 insertions(+) create mode 100644 doc/Jamfile.v2 create mode 100644 doc/acknowledgements.qbk create mode 100644 doc/config.qbk create mode 100644 doc/configuring_boost.qbk create mode 100644 doc/guidelines.qbk create mode 100644 doc/html/HTML.manifest create mode 100644 doc/html/boost_config/acknowledgements.html create mode 100644 doc/html/boost_config/boost_macro_reference.html create mode 100644 doc/html/boost_config/guidelines_for_boost_authors.html create mode 100644 doc/html/boost_config/rationale.html create mode 100755 doc/html/boostbook.css create mode 100644 doc/html/images/callouts/1.png create mode 100644 doc/html/images/callouts/10.png create mode 100644 doc/html/images/callouts/11.png create mode 100644 doc/html/images/callouts/12.png create mode 100644 doc/html/images/callouts/13.png create mode 100644 doc/html/images/callouts/14.png create mode 100644 doc/html/images/callouts/15.png create mode 100644 doc/html/images/callouts/2.png create mode 100644 doc/html/images/callouts/3.png create mode 100644 doc/html/images/callouts/4.png create mode 100644 doc/html/images/callouts/5.png create mode 100644 doc/html/images/callouts/6.png create mode 100644 doc/html/images/callouts/7.png create mode 100644 doc/html/images/callouts/8.png create mode 100644 doc/html/images/callouts/9.png create mode 100755 doc/html/images/caution.png create mode 100755 doc/html/images/home.png create mode 100755 doc/html/images/important.png create mode 100755 doc/html/images/next.png create mode 100755 doc/html/images/note.png create mode 100755 doc/html/images/prev.png create mode 100755 doc/html/images/tip.png create mode 100755 doc/html/images/up.png create mode 100755 doc/html/images/warning.png create mode 100644 doc/html/index.html create mode 100644 doc/macro_reference.qbk create mode 100644 doc/rationale.qbk diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 00000000..47ed1950 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,30 @@ +# Boost.Config +# +# Copyright (c) 2001 Beman Dawes +# Copyright (c) 2001 Vesa Karvonen +# Copyright (c) 2001 John Maddock +# +# Distributed under the Boost Software License, Version 1.0. +# (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) + + +# Quickbook +# ----------------------------------------------------------------------------- + +import quickbook ; + +xml config + : + config.qbk + ; + +boostbook standalone + : + config + : + toc.max.depth=2 + toc.section.depth=2 + chunk.section.depth=1 + ; + diff --git a/doc/acknowledgements.qbk b/doc/acknowledgements.qbk new file mode 100644 index 00000000..904a468f --- /dev/null +++ b/doc/acknowledgements.qbk @@ -0,0 +1,29 @@ +[/ + Boost.Config + + Copyright (c) 2001 Beman Dawes + Copyright (c) 2001 Vesa Karvonen + Copyright (c) 2001 John Maddock + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + +[section Acknowledgements] + +Beman Dawes provided the original `config.hpp` and part of this document. + +Vesa Karvonen provided a description of the principles (see +[link config_rationale rationale]) and put together an early version of +the current configuration setup. + +John Maddock put together the configuration current code, the test +programs, the configuration script and the reference section of this +document. + +Numerous boost members, past and present, have contributed fixes to boost's +configuration. + +[endsect] + diff --git a/doc/config.qbk b/doc/config.qbk new file mode 100644 index 00000000..5276f195 --- /dev/null +++ b/doc/config.qbk @@ -0,0 +1,57 @@ +[library Boost.Config + [quickbook 1.4] + [authors [Beman Dawes, Vesa Karvonen, John Maddock] ] + [copyright 2001-2007 Beman Dawes, Vesa Karvonen, John Maddock] + [category broken compiler workarounds] + [id config] + [dirname config] + [purpose + Helps boost library developers adapt to compiler idiosyncrasies; not intended for library users. + ] + [source-mode c++] + [license +Distributed under the Boost Software License, Version 1.0. +(See accompanying file LICENSE_1_0.txt or copy at +[@http://www.boost.org/LICENSE_1_0.txt]) + ] +] + + +[/ Cited Boost resources ] + +[def __BOOST_REGRESSION_TEST_DRIVER__ [@../../../../more/regression.html boost regression test driver]] +[def __BOOST_CONFIG_HEADER__ [@../../../../boost/config.hpp ]] +[def __BOOST_CONFIG_USER_HEADER__ [@../../../../boost/config/user.hpp ]] +[def __BOOST_CONFIG_SUFFIX_HEADER__ [@../../../../boost/config/user.hpp ]] +[def __BOOST_CONFIG_DIR__ [']`/boost/config/`] + + +[/ Other web resources ] + +[def __STL_PORT__ [@http://stlport.sourceforge.net STLport]] +[def __BOOST_TRACKER__ [@http://sourceforge.net/tracker/?group_id=7586 Tracker]] +[def __CORE_LANGUAGE_DR337__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#337 Core Language DR337]] +[def __PRINCIPLES_AND_PATTERNS_ARTICLE__ [@http://www.objectmentor.com/resources/articles/ocp.pdf following article]] + + +[/ Icons ] + +[def __NOTE__ [$images/note.png]] +[def __ALERT__ [$images/caution.png]] +[def __DETAIL__ [$images/note.png]] +[def __TIP__ [$images/tip.png]] +[def __QUESTION_MARK__ [$images/question.png]] +[def __SPACE__ [$images/space.png]] +[def __GO_TO__ [$images/callouts/R.png]] + + +[/ Document files ] + + +[include configuring_boost.qbk] +[include macro_reference.qbk] +[include guidelines.qbk] +[include rationale.qbk] +[include acknowledgements.qbk] + + diff --git a/doc/configuring_boost.qbk b/doc/configuring_boost.qbk new file mode 100644 index 00000000..ad391748 --- /dev/null +++ b/doc/configuring_boost.qbk @@ -0,0 +1,434 @@ +[/ + Boost.Config + + Copyright (c) 2001 Beman Dawes + Copyright (c) 2001 Vesa Karvonen + Copyright (c) 2001 John Maddock + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + + +[section Configuring Boost for Your Platform] + + +[section Using the default boost configuration] + +Boost comes already configured for most common compilers and platforms; you +should be able to use boost "as is". Since the compiler is configured +separately from the standard library, the default configuration should work +even if you replace the compiler's standard library with a third-party +standard library (like __STL_PORT__). + +Using boost "as is" without trying to reconfigure is the recommended method +for using boost. You can, however, run the configure script if you want to, +and there are regression tests provided that allow you to test the current +boost configuration with your particular compiler setup. + +Boost library users can request support for additional compilers or platforms +by visiting our __BOOST_TRACKER__ and submitting a support request. + +[endsect] + +[section The header] + +Boost library implementations access configuration macros via + + #include ``__BOOST_CONFIG_HEADER__`` + +While Boost library users are not required to include that file directly, or +use those configuration macros, such use is acceptable. The configuration +macros are documented as to their purpose, usage, and limitations which makes +them usable by both Boost library and user code. + +Boost [link config_info_macros informational] or [link config_helpers helper] +macros are designed for use by Boost users as well as for our own internal use. +Note however, that the [link config_features feature test] and +[link config_defects defect test] macros were designed for internal use by +Boost libraries, not user code, so they can change at any time (though no +gratuitous changes are made to them). Boost library problems resulting from +changes to the configuration macros are caught by the Boost regression tests, +so the Boost libraries are updated to account for those changes. By contrast, +Boost library user code can be adversely affected by changes to the macros +without warning. The best way to keep abreast of changes to the macros used in +user code is to monitor the discussions on the Boost developers list. + +[endsect] + +[#config_config_script] + +[section Using the configure script] + +[note +This configure script only sets up the Boost headers for use with a particular +compiler. It has no effect on Boost.Build, or how the libraries are built. +] + +If you know that boost is incorrectly configured for your particular setup, and +you are on a UNIX like platform, then you may want to try and improve things by +running the boost configure script. From a shell command prompt you will need to +cd into [']`/libs/config/` and type: + +[: `sh ./configure` ] + +you will see a list of the items being checked as the script works its way +through the regression tests. Note that the configure script only really +auto-detects your compiler if it's called g++, c++ or CC. If you are using +some other compiler you will need to set one or more of the following +environment variables: + + +[table +[[Variable][Description ]] +[[CXX ][The name of the compiler, for example `c++`. ]] +[[CXXFLAGS][The compiler flags to use, for example `-O2`. ]] +[[LDFLAGS ][The linker flags to use, for example `-L/mypath`. ]] +[[LIBS ][Any libraries to link in, for example `-lpthread`.]] +] + +For example to run the configure script with HP aCC, you might use something +like: + + 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 + +However you run the configure script, when it finishes you will find a +new header -`user.hpp`- located in the [']`/libs/config/` +directory. [*Note that configure does not install this header into your +boost include path by default]. This header contains all the options +generated by the configure script, plus a header-section that contains +the user settable options from the default version of +__BOOST_CONFIG_USER_HEADER__ (located under __BOOST_CONFIG_DIR__). +There are two ways you can use this header: + +* [*Option 1:] copy the header into __BOOST_CONFIG_DIR__ so that it replaces +the default user.hpp provided by boost. This option allows only one +configure-generated setup; boost developers should avoid this option, +as it incurs the danger of accidentally committing a configure-modified +__BOOST_CONFIG_USER_HEADER__ to the cvs repository (something you will not +be thanked for!). + +* [*Option 2:] give the header a more memorable name, and place it somewhere +convenient; then, define the macro `BOOST_USER_CONFIG` to point to it. For +example create a new sub-directory __BOOST_CONFIG_DIR__ `user/`, and copy +the header there; for example as `multithread-gcc-config.hpp`. Then, when +compiling add the command line option: +`-DBOOST_USER_CONFIG=""`, and +boost will use the new configuration header. This option allows you to +generate more than one configuration header, and to keep them separate +from the boost source - so that updates to the source do not interfere +with your configuration. + +[endsect] + +[#config_user_settable] + +[section User settable options] + +There are some configuration-options that represent user choices, rather +than compiler defects or platform specific options. These are listed in +`` and at the start of a configure-generated `user.hpp` +header. You can define these on the command line, or by editing +``, they are listed in the following table: + + + +[table + +[[Macro ][Description ]] + +[[`BOOST_USER_CONFIG`][ +When defined, it should point to the name of the user configuration file +to include prior to any boost configuration files. When not defined, +defaults to [@../../../../boost/config/user.hpp ``]. +]] +[[`BOOST_COMPILER_CONFIG`][ +When defined, it should point to the name of the compiler configuration +file to use. Defining this cuts out the compiler selection logic, and +eliminates the dependency on the header containing that logic. For +example if you are using gcc, then you could define BOOST_COMPILER_CONFIG +to [@../../../../boost/config/compiler/gcc.hpp ``]. +]] +[[`BOOST_STDLIB_CONFIG`][ +When defined, it should point to the name of the standard library +configuration file to use. Defining this cuts out the standard library +selection logic, and eliminates the dependency on the header containing +that logic. For example if you are using STLport, then you could define +`BOOST_STDLIB_CONFIG` to +[@../../../../boost/config/stdlib/stlport.hpp ``]. +]] +[[`BOOST_PLATFORM_CONFIG`][ +When defined, it should point to the name of the platform configuration +file to use. Defining this cuts out the platform selection logic, and +eliminates the dependency on the header containing that logic. For example +if you are compiling on linux, then you could define `BOOST_PLATFORM_CONFIG` +to [@../../../../boost/config/platform/linux.hpp ``]. +]] +[[`BOOST_NO_COMPILER_CONFIG`][ +When defined, no compiler configuration file is selected or included, +define when the compiler is fully conformant with the standard, or where +the user header (see `BOOST_USER_CONFIG`), has had any options necessary +added to it, for example by an autoconf generated configure script. +]] +[[`BOOST_NO_STDLIB_CONFIG` ][ +When defined, no standard library configuration file is selected or included, +define when the standard library is fully conformant with the standard, or +where the user header (see `BOOST_USER_CONFIG`), has had any options necessary +added to it, for example by an autoconf generated configure script. +]] +[[`BOOST_NO_PLATFORM_CONFIG` ][ +When defined, no platform configuration file is selected or included, +define when the platform is fully conformant with the standard (and has +no useful extra features), or where the user header (see +`BOOST_USER_CONFIG`), has had any options necessary added to it, for example +by an autoconf generated configure script. +]] +[[`BOOST_NO_CONFIG` ][ +Equivalent to defining all of `BOOST_NO_COMPILER_CONFIG`, +`BOOST_NO_STDLIB_CONFIG` and `BOOST_NO_PLATFORM_CONFIG`. +]] +[[`BOOST_STRICT_CONFIG` ][ +The normal behavior for compiler versions that are newer than the last +known version, is to assume that they have all the same defects as the +last known version. By setting this define, then compiler versions that +are newer than the last known version are assumed to be fully conforming +with the standard. This is probably most useful for boost developers or +testers, and for those who want to use boost to test beta compiler versions. +]] +[[`BOOST_ASSERT_CONFIG` ][ +When this flag is set, if the config finds anything unknown, then it will +stop with a #error rather than continue. Boost regression testers should +set this define, as should anyone who wants to quickly check whether boost +is supported on their platform. +]] +[[`BOOST_DISABLE_THREADS` ][ +When defined, disables threading support, even if the compiler in its +current translation mode supports multiple threads. +]] +[[`BOOST_DISABLE_WIN32` ][ +When defined, disables the use of Win32 specific API's, even when these +are available. Also has the effect of setting `BOOST_DISABLE_THREADS` unless +`BOOST_HAS_PTHREADS` is set. This option may be set automatically by the +config system when it detects that the compiler is in "strict mode". +]] +[[`BOOST_DISABLE_ABI_HEADERS`][ +Stops boost headers from including any prefix/suffix headers that normally +control things like struct packing and alignment. +]] +[[`BOOST_ABI_PREFIX`][ +A prefix header to include in place of whatever boost.config would normally +select, any replacement should set up struct packing and alignment options +as required. +]] +[[`BOOST_ABI_SUFFIX` ][ +A suffix header to include in place of whatever boost.config would normally +select, any replacement should undo the effects of the prefix header. +]] +[[`BOOST_ALL_DYN_LINK`][ +Forces all libraries that have separate source, to be linked as dll's rather +than static libraries on Microsoft Windows (this macro is used to turn on +`__declspec(dllimport)` modifiers, so that the compiler knows which symbols +to look for in a dll rather than in a static library). +Note that there may be some libraries that can only be statically linked +(Boost.Test for example) and others which may only be dynamically linked +(Boost.Threads for example), in these cases this macro has no effect. +]] +[[`BOOST_`['WHATEVER]`_DYN_LINK`][ +Forces library "whatever" to be linked as a dll rather than a static library +on Microsoft Windows: replace the ['WHATEVER] part of the macro name with the +name of the library that you want to dynamically link to, for example use +`BOOST_DATE_TIME_DYN_LINK` or `BOOST_REGEX_DYN_LINK` etc (this macro is used +to turn on `__declspec(dllimport)` modifiers, so that the compiler knows +which symbols to look for in a dll rather than in a static library). +Note that there may be some libraries that can only be statically linked +(Boost.Test for example) and others which may only be dynamically linked +(Boost.Threads for example), in these cases this macro is unsupported. +]] +[[`BOOST_ALL_NO_LIB`][ +Tells the config system not to automatically select which libraries to link +against. +Normally if a compiler supports #pragma lib, then the correct library build +variant will be automatically selected and linked against, simply by the act +of including one of that library's headers. This macro turns that +feature off. +]] +[[`BOOST_`['WHATEVER]`_NO_LIB`][ +Tells the config system not to automatically select which library to link +against for library "whatever", replace ['WHATEVER] in the macro name with the +name of the library; for example `BOOST_DATE_TIME_NO_LIB` or `BOOST_REGEX_NO_LIB`. +Normally if a compiler supports `#pragma lib`, then the correct library build +variant will be automatically selected and linked against, simply by the +act of including one of that library's headers. This macro turns that +feature off. +]] +[[`BOOST_LIB_DIAGNOSTIC`][ +Causes the auto-linking code to output diagnostic messages indicating the +name of the library that is selected for linking. +]] +[[`BOOST_LIB_TOOLSET`][ +Overrides the name of the toolset part of the name of library being linked +to; note if defined this must be defined to a quoted string literal, for +example "abc". +]] +] + +[endsect] + +[section Advanced configuration usage] + +By setting various macros on the compiler command line or by editing +__BOOST_CONFIG_USER_HEADER__, the boost configuration setup can be optimised +in a variety of ways. + +Boost's configuration is structured so that the user-configuration is +included first (defaulting to __BOOST_CONFIG_USER_HEADER__ if `BOOST_USER_CONFIG` +is not defined). This sets up any user-defined policies, and gives the +user-configuration a chance to influence what happens next. + +Next the compiler, standard library, and platform configuration files are +included. These are included via macros (`BOOST_COMPILER_CONFIG` etc, +[link config_user_settable see user settable macros]), and if the corresponding +macro is undefined then a separate header that detects which compiler/standard +library/platform is in use is included in order to set these. The config +can be told to ignore these headers altogether if the corresponding +`BOOST_NO_XXX` macro is set (for example `BOOST_NO_COMPILER_CONFIG` to +disable including any compiler configuration file - +[link config_user_settable see user settable macros]). + +Finally the boost configuration header, includes __BOOST_CONFIG_SUFFIX_HEADER__; +this header contains any boiler plate configuration code - for example where one +boost macro being set implies that another must be set also. + +The following usage examples represent just a few of the possibilities: + +[section Example 1, creating our own frozen configuration] + +Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0. Lets +suppose also that we don't intend to update our compiler or standard library +any time soon. In order to avoid breaking dependencies when we update boost, +we may want to "freeze" our configuration headers, so that we only have to +rebuild our project if the boost code itself has changed, and not because the +boost config has been updated for more recent versions of Visual C++ or STLport. +We'll start by realising that the configuration files in use are: +[@../../../../boost/config/compiler/visualc.hpp ``] +for the compiler, +[@../../../../boost/config/stdlib/stlport.hpp ``] +for the standard library, and +[@../../../../boost/config/platform/win32.hpp ``] +for the platform. Next we'll create our own private configuration directory: +`boost/config/mysetup/`, and copy the configuration files into there. Finally, +open up __BOOST_CONFIG_USER_HEADER__ and edit the following defines: + + #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" + +Now when you use boost, its configuration header will go straight to our "frozen" +versions, and ignore the default versions, you will now be insulated from any +configuration changes when you update boost. This technique is also useful if +you want to modify some of the boost configuration files; for example if you are +working with a beta compiler release not yet supported by boost. + +[endsect] + +[section Example 2: skipping files that you don't need] + +Lets suppose that you're using boost with a compiler that is fully conformant with +the standard; you're not interested in the fact that older versions of your compiler +may have had bugs, because you know that your current version does not need any +configuration macros setting. In a case like this, you can define +`BOOST_NO_COMPILER_CONFIG` either on the command line, or in __BOOST_CONFIG_USER_HEADER__, +and miss out the compiler configuration header altogether (actually you miss out +two headers, one which works out what the compiler is, and one that configures +boost for it). This has two consequences: the first is that less code has to be c +ompiled, and the second that you have removed a dependency on two boost headers. + +[endsect] + +[section Example 3: using configure script to freeze the boost configuration] + +If you are working on a unix-like platform then you can use the configure script to +generate a "frozen" configuration based on your current compiler setup - +[link config_config_script see using the configure script for more details]. + +[endsect] + +[endsect] + +[section Testing the boost configuration] + +The boost configuration library provides a full set of regression test programs +under the __BOOST_CONFIG_DIR__ `test/` sub-directory: + + +[table +[[File][Description]] +[[`config_info.cpp`][ +Prints out a detailed description of your compiler/standard library/platform +setup, plus your current boost configuration. The information provided by this +program useful in setting up the boost configuration files. If you report that +boost is incorrectly configured for your compiler/library/platform then please +include the output from this program when reporting the changes required. +]] +[[`config_test.cpp`][ +A monolithic test program that includes most of the individual test cases. +This provides a quick check to see if boost is correctly configured for your +compiler/library/platform. +]] +[[`limits_test.cpp`][ +Tests your standard library's `std::numeric_limits` implementation (or its boost +provided replacement if `BOOST_NO_LIMITS` is defined). This test file fails with +most versions of numeric_limits, mainly due to the way that some compilers +treat NAN's and infinity. +]] +[[`no_*pass.cpp`][ +Individual compiler defect test files. Each of these should compile, if one +does not then the corresponding `BOOST_NO_XXX` macro needs to be defined - see +each test file for specific details. +]] +[[`no_*fail.cpp`][ +Individual compiler defect test files. Each of these should not compile, if +one does then the corresponding `BOOST_NO_XXX` macro is defined when it need +not be - see each test file for specific details. +]] +[[`has_*pass.cpp`][ +Individual feature test files. If one of these does not compile then the +corresponding `BOOST_HAS_XXX` macro is defined when it should not be - see +each test file for specific details. +]] +[[`has_*fail.cpp`][ +Individual feature test files. If one of these does compile then the +corresponding `BOOST_HAS_XXX` macro can be safely defined - see each test +file for specific details. +]] +] + +Although you can run the configuration regression tests as individual test +files, there are rather a lot of them, so there are a couple of shortcuts to +help you out: + +If you have built the __BOOST_REGRESSION_TEST_DRIVER__, then you can use this to +produce a nice html formatted report of the results using the supplied test file. + +Alternatively you can run the configure script like this: + +[: `./configure --enable-test`] + +in which case the script will test the current configuration rather than +creating a new one from scratch. + +If you are reporting the results of these tests for a new +platform/library/compiler then please include a log of the full compiler output, +the output from `config_info.cpp`, and the pass/fail test results. + + +[endsect] + +[endsect] + diff --git a/doc/guidelines.qbk b/doc/guidelines.qbk new file mode 100644 index 00000000..bd89209f --- /dev/null +++ b/doc/guidelines.qbk @@ -0,0 +1,189 @@ +[/ + Boost.Config + + Copyright (c) 2001 Beman Dawes + Copyright (c) 2001 Vesa Karvonen + Copyright (c) 2001 John Maddock + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + + + +[section Guidelines for Boost Authors] + +The __BOOST_CONFIG_HEADER__ header is used to pass configuration information +to other boost files, allowing them to cope with platform dependencies such +as arithmetic byte ordering, compiler pragmas, or compiler shortcomings. +Without such configuration information, many current compilers would not work +with the Boost libraries. + +Centralizing configuration information in this header reduces the number of +files that must be modified when porting libraries to new platforms, or when +compilers are updated. Ideally, no other files would have to be modified when +porting to a new platform. + +Configuration headers are controversial because some view them as condoning +broken compilers and encouraging non-standard subsets. Adding settings for +additional platforms and maintaining existing settings can also be a problem. +In other words, configuration headers are a necessary evil rather than a +desirable feature. The boost config.hpp policy is designed to minimize the +problems and maximize the benefits of a configuration header. + +Note that: + +* Boost library implementers are not required to "`#include `", +and are not required in any way to support compilers that do not comply +with the C++ Standard (ISO/IEC 14882). +* If a library implementer wishes to support some non-conforming compiler, +or to support some platform specific feature, "`#include `" +is the preferred way to obtain configuration information not available from +the standard headers such as ``, etc. +* If configuration information can be deduced from standard headers such as +``, use those standard headers rather than ``. +* Boost files that use macros defined in `` should have +sensible, standard conforming, default behavior if the macro is not defined. +This means that the starting point for porting `` to a new +platform is simply to define nothing at all specific to that platform. In +the rare case where there is no sensible default behavior, an #error message +should describe the problem. +* If a Boost library implementer wants something added to `config.hpp`, post +a request on the Boost mailing list. There is no guarantee such a request +will be honored; the intent is to limit the complexity of config.hpp. +* The intent is to support only compilers which appear on their way to +becoming C++ Standard compliant, and only recent releases of those compilers +at that. +* The intent is not to disable mainstream features now well-supported by the +majority of compilers, such as namespaces, exceptions, RTTI, or templates. + + +[section Adding New Defect Macros] + +When you need to add a new defect macro -either to fix a problem with an +existing library, or when adding a new library- distil the issue down to +a simple test case; often, at this point other (possibly better) workarounds +may become apparent. Secondly always post the test case code to the boost +mailing list and invite comments; remember that C++ is complex and that +sometimes what may appear a defect, may in fact turn out to be a problem +with the authors understanding of the standard. + +When you name the macro, follow the `BOOST_NO_`['SOMETHING] naming +convention, so that it's obvious that this is a macro reporting a defect. + +Finally, add the test program to the regression tests. You will need to +place the test case in a `.ipp` file with the following comments near the top: + + // MACRO: BOOST_NO_FOO + // TITLE: foo + // DESCRIPTION: If the compiler fails to support foo + +These comments are processed by the autoconf script, so make sure the format +follows the one given. The file should be named "`boost_no_foo.ipp`", where foo +is the defect description -try and keep the file name under the Mac 30 character +filename limit though. You will also need to provide a function prototype +"`int test()`" that is declared in a namespace with the same name as the macro, +but in all lower case, and which returns zero on success: + + namespace boost_no_foo { + + int test() + { + // test code goes here: + // + return 0; + } + + } + +Once the test code is in place in libs/config/test, updating the configuration +test system proceeds as: + +* cd into `libs/config/tools` and run `bjam --v2` : this generates the `.cpp` +file test cases from the `.ipp` file, updates the Jamfile, `config_test.cpp` and +`config_info.cpp`. +* cd into `libs/config/test` and run `bjam --v2 `['MACRONAME]` compiler-list` : where +['MACRONAME] is the name of the new macro, and `compiler-list` is the list of +compilers to test with. You should see the tests pass with those compilers +that don't have the defect, and fail with those that do. +* cd into `libs/config/test` and `run bjam --v2 config_info config_test compiler-list` : +`config_info` should build and run cleanly for all the compilers in `compiler-list` +while `config_test` should fail for those that have the defect, and pass for those +that do not. + +Then you should: + +* Define the defect macro in those config headers that require it. +* Document the macro in this documentation (please do not forget this step!!) +* Commit everything. +* Keep an eye on the regression tests for new failures in Boost.Config caused by +the addition. +* Start using the macro. + +[endsect] + +[section Adding New Feature Test Macros] + +When you need to add a macro that describes a feature that the standard does +not require, follow the convention for adding a new defect macro (above), but +call the macro `BOOST_HAS_FOO`, and name the test file "`boost_has_foo.ipp`". +Try not to add feature test macros unnecessarily, if there is a platform +specific macro that can already be used (for example `_WIN32`, `__BEOS__`, or +`__linux`) to identify the feature then use that. Try to keep the macro to a +feature group, or header name, rather than one specific API (for example +`BOOST_HAS_NL_TYPES_H` rather than `BOOST_HAS_CATOPEN`). If the macro +describes a POSIX feature group, then add boilerplate code to +__BOOST_CONFIG_SUFFIX_HEADER__ to auto-detect the feature where possible +(if you are wondering why we can't use POSIX feature test macro directly, +remember that many of these features can be added by third party libraries, +and are not therefore identified inside ``). + +[endsect] + +[section Modifying the Boost Configuration Headers] + +The aim of boost's configuration setup is that the configuration headers should +be relatively stable - a boost user should not have to recompile their code +just because the configuration for some compiler that they're not interested +in has changed. Separating the configuration into separate compiler/standard +library/platform sections provides for part of this stability, but boost +authors require some amount of restraint as well, in particular: + +__BOOST_CONFIG_HEADER__ should never change, don't alter this file. + +__BOOST_CONFIG_USER_HEADER__ is included by default, don't add extra code to +this file unless you have to. If you do, please remember to update +[@../../tools/configure.in libs/config/tools/configure.in] as well. + +__BOOST_CONFIG_SUFFIX_HEADER__ is always included so be careful about +modifying this file as it breaks dependencies for everyone. This file should +include only "boilerplate" configuration code, and generally should change +only when new macros are added. + +[@../../../../boost/config/select_compiler_config.hpp ], +[@../../../../boost/config/select_platform_config.hpp ] and +[@../../../../boost/config/select_stdlib_config.hpp ] +are included by default and should change only if support for a new +compiler/standard library/platform is added. + +The compiler/platform/standard library selection code is set up so that unknown +platforms are ignored and assumed to be fully standards compliant -this gives +unknown platforms a "sporting chance" of working "as is" even without running +the configure script. + +When adding or modifying the individual mini-configs, assume that future, as +yet unreleased versions of compilers, have all the defects of the current +version. Although this is perhaps unnecessarily pessimistic, it cuts down on +the maintenance of these files, and experience suggests that pessimism is +better placed than optimism here! + +[endsect] + +[endsect] + + + + + + diff --git a/doc/html/HTML.manifest b/doc/html/HTML.manifest new file mode 100644 index 00000000..632c78f1 --- /dev/null +++ b/doc/html/HTML.manifest @@ -0,0 +1,5 @@ +index.html +boost_config/boost_macro_reference.html +boost_config/guidelines_for_boost_authors.html +boost_config/rationale.html +boost_config/acknowledgements.html diff --git a/doc/html/boost_config/acknowledgements.html b/doc/html/boost_config/acknowledgements.html new file mode 100644 index 00000000..a6010603 --- /dev/null +++ b/doc/html/boost_config/acknowledgements.html @@ -0,0 +1,54 @@ + + + +Acknowledgements + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+
+

+ Beman Dawes provided the original config.hpp and + part of this document. +

+

+ Vesa Karvonen provided a description of the principles (see rationale) + and put together an early version of the current configuration setup. +

+

+ John Maddock put together the configuration current code, the test programs, + the configuration script and the reference section of this document. +

+

+ Numerous boost members, past and present, have contributed fixes to boost's + configuration. +

+
+ + + +
Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock
+
+
+PrevUpHome +
+ + diff --git a/doc/html/boost_config/boost_macro_reference.html b/doc/html/boost_config/boost_macro_reference.html new file mode 100644 index 00000000..bfffd27b --- /dev/null +++ b/doc/html/boost_config/boost_macro_reference.html @@ -0,0 +1,2803 @@ + + + +Boost Macro Reference + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Macros + that describe defects
+
Macros + that describe optional features
+
Macros + that describe C++0x features
+
Boost + Helper Macros
+
Boost + Informational Macros
+
Macros + for libraries with separate source code
+
+

+

+
+
+

+ The following macros all describe features that are required by the C++ standard, + if one of the following macros is defined, then it represents a defect in + the compiler's conformance with the standard. +

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Section +

+ 		+

+ Description +

+
+

+ BOOST_BCB_PARTIAL_SPECIALIZATION_BUG +

+ 		+

+ Compiler +

+ 		+

+ The compiler exibits certain partial specialisation bug - probably + Borland C++ Builder specific. +

+
+

+ BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL +

+ 		+

+ Compiler +

+ 		+

+ Argument dependent lookup fails if there is a using declaration for + the symbol being looked up in the current scope. For example, using + boost::get_pointer; prevents ADL from + finding overloads of get_pointer + in namespaces nested inside boost (but not elsewhere). Probably Borland + specific. +

+
+

+ BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP +

+ 		+

+ Compiler +

+ 		+

+ Compiler does not implement argument-dependent lookup (also named + Koenig lookup); see std::3.4.2 [basic.koenig.lookup] +

+
+

+ BOOST_NO_AUTO_PTR +

+ 		+

+ Standard library +

+ 		+

+ If the compiler / library supplies non-standard or broken std::auto_ptr. +

+
+

+ BOOST_NO_CTYPE_FUNCTIONS +

+ 		+

+ Platform +

+ 		+

+ The Platform does not provide functions for the character-classifying + operations <ctype.h> and <cctype>, + only macros. +

+
+

+ BOOST_NO_CV_SPECIALIZATIONS +

+ 		+

+ Compiler +

+ 		+

+ If template specialisations for cv-qualified types conflict with + a specialisation for a cv-unqualififed type. +

+
+

+ BOOST_NO_CV_VOID_SPECIALIZATIONS +

+ 		+

+ Compiler +

+ 		+

+ If template specialisations for cv-void types conflict with a specialisation + for void. +

+
+

+ BOOST_NO_CWCHAR +

+ 		+

+ Platform +

+ 		+

+ The Platform does not provide <wchar.h> + and <cwchar>. +

+
+

+ BOOST_NO_CWCTYPE +

+ 		+

+ Platform +

+ 		+

+ The Platform does not provide <wctype.h> + and <cwctype>. +

+
+

+ BOOST_NO_DEPENDENT_NESTED_DERIVATIONS +

+ 		+

+ Compiler +

+ 		+

+ The compiler fails to compile a nested class that has a dependent + base class: +

+
+template<typename T>
+struct foo : {
+   template<typename U>
+   struct bar : public U {};
+
+

+ }; +

+
+

+ BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS +

+ 		+

+ Compiler +

+ 		+

+ Template value parameters cannot have a dependent type, for example: + +

+
+template<class T, typename T::type value> 
+class X { ... };
+
+

+

+
+

+ BOOST_NO_EXCEPTION_STD_NAMESPACE +

+ 		+

+ Standard Library +

+ 		+

+ The standard library does not put some or all of the contents of + <exception> in namespace std. +

+
+

+ BOOST_NO_EXCEPTIONS +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not support exception handling (this setting is + typically required by many C++ compilers for embedded platforms). + Note that there is no requirement for boost libraries to honor this + configuration setting - indeed doing so may be impossible in some + cases. Those libraries that do honor this will typically abort if + a critical error occurs - you have been warned! +

+
+

+ BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS +

+ 		+

+ Compiler +

+ 		+

+ Can only use deduced template arguments when calling function template + instantiations. +

+
+

+ BOOST_NO_FUNCTION_TEMPLATE_ORDERING +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not perform function template ordering or its function + template ordering is incorrect. +

+
+// #1
+template<class T> void f(T);
+
+// #2
+template<class T,class U> void f(T(*)(U));
+
+void bar(int);
+
+f(&bar); // should choose #2.
+
+

+

+
+

+ BOOST_NO_INCLASS_MEMBER_INITIALIZATION +

+ 		+

+ Compiler +

+ 		+

+ Compiler violates std::9.4.2/4. +

+
+

+ BOOST_NO_INTRINSIC_WCHAR_T +

+ 		+

+ Compiler +

+ 		+

+ The C++ implementation does not provide wchar_t, + or it is really a synonym for another integral type. Use this symbol + to decide whether it is appropriate to explicitly specialize a template + on wchar_t if there + is already a specialization for other integer types. +

+
+

+ BOOST_NO_IS_ABSTRACT +

+ 		+

+ Compiler +

+ 		+

+ The C++ compiler does not support SFINAE with abstract types, this + is covered by Core + Language DR337, but is not part of the current standard. + Fortunately most compilers that support SFINAE also support this + DR. +

+
+

+ BOOST_NO_LIMITS +

+ 		+

+ Standard library +

+ 		+

+ The C++ implementation does not provide the <limits> + header. Never check for this symbol in library code; always include + <boost/limits.hpp>, which guarantees to provide + std::numeric_limits. +

+
+

+ BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS +

+ 		+

+ Standard library +

+ 		+

+ Constants such as numeric_limits<T>::is_signed + are not available for use at compile-time. +

+
+

+ BOOST_NO_LONG_LONG_NUMERIC_LIMITS +

+ 		+

+ Standard library +

+ 		+

+ There is no specialization for numeric_limits<long + long> + and numeric_limits<unsigned + long long>. <boost/limits.hpp> + will then add these specializations as a standard library "fix" + only if the compiler supports the long + long datatype. +

+
+

+ BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not support the specialization of individual member + functions of template classes. +

+
+

+ BOOST_NO_MEMBER_TEMPLATE_KEYWORD +

+ 		+

+ Compiler +

+ 		+

+ If the compiler supports member templates, but not the template keyword + when accessing member template classes. +

+
+

+ BOOST_NO_MEMBER_TEMPLATE_FRIENDS +

+ 		+

+ Compiler +

+ 		+

+ Member template friend syntax (template<class + P> + friend class + frd;) + described in the C++ Standard, 14.5.3, not supported. +

+
+

+ BOOST_NO_MEMBER_TEMPLATES +

+ 		+

+ Compiler +

+ 		+

+ Member template functions not fully supported. +

+
+

+ BOOST_NO_MS_INT64_NUMERIC_LIMITS +

+ 		+

+ Standard library +

+ 		+

+ There is no specialization for numeric_limits<__int64> and numeric_limits<unsigned + __int64>. + <boost/limits.hpp> will then add these specializations + as a standard library "fix", only if the compiler supports + the __int64 datatype. +

+
+

+ BOOST_NO_OPERATORS_IN_NAMESPACE +

+ 		+

+ Compiler +

+ 		+

+ Compiler requires inherited operator friend functions to be defined + at namespace scope, then using'ed to boost. Probably GCC specific. + See <boost/operators.hpp> + for example. +

+
+

+ BOOST_NO_POINTER_TO_MEMBER_CONST +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not correctly handle pointers to const member functions, + preventing use of these in overloaded function templates. See <boost/functional.hpp> + for example. +

+
+

+ BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS +

+ 		+

+ Compiler +

+ 		+

+ Pointers to members don't work when used as template parameters. +

+
+

+ BOOST_NO_PRIVATE_IN_AGGREGATE +

+ 		+

+ Compiler +

+ 		+

+ The compiler misreads 8.5.1, treating classes as non-aggregate if + they contain private or protected member functions. +

+
+

+ BOOST_NO_SFINAE +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not support the "Substitution Failure Is Not + An Error" meta-programming idiom. +

+
+

+ BOOST_NO_STD_ALLOCATOR +

+ 		+

+ Standard library +

+ 		+

+ The C++ standard library does not provide a standards conforming + std::allocator. +

+
+

+ BOOST_NO_STD_DISTANCE +

+ 		+

+ Standard library +

+ 		+

+ The platform does not have a conforming version of std::distance. +

+
+

+ BOOST_NO_STD_ITERATOR +

+ 		+

+ Standard library +

+ 		+

+ The C++ implementation fails to provide the std::iterator + class. +

+
+

+ BOOST_NO_STD_ITERATOR_TRAITS +

+ 		+

+ Standard library +

+ 		+

+ The compiler does not provide a standard compliant implementation + of std::iterator_traits. Note that the + compiler may still have a non-standard implementation. +

+
+

+ BOOST_NO_STD_LOCALE +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks std::locale. +

+
+

+ BOOST_NO_STD_MESSAGES +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks a conforming std::messages + facet. +

+
+

+ BOOST_NO_STD_MIN_MAX +

+ 		+

+ Standard library +

+ 		+

+ The C++ standard library does not provide the min() and max() template functions that should + be in <algorithm>. +

+
+

+ BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN +

+ 		+

+ Standard library +

+ 		+

+ Defined if the standard library's output iterators are not assignable. +

+
+

+ BOOST_NO_STD_USE_FACET +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks a conforming std::use_facet. +

+
+

+ BOOST_NO_STD_WSTREAMBUF +

+ 		+

+ Standard library +

+ 		+

+ The standard library's implementation of std::basic_streambuf<wchar_t> is either missing, incomplete, + or buggy. +

+
+

+ BOOST_NO_STD_WSTRING +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks std::wstring. +

+
+

+ BOOST_NO_STDC_NAMESPACE +

+ 		+

+ Compiler, Platform +

+ 		+

+ The contents of C++ standard headers for C library functions (the + <c...> headers) have not been placed + in namespace std. This test is difficult - some libraries "fake" + the std C functions by adding using declarations to import them into + namespace std, unfortunately they don't necessarily catch all of + them... +

+
+

+ BOOST_NO_STRINGSTREAM +

+ 		+

+ Standard library +

+ 		+

+ The C++ implementation does not provide the <sstream> + header. +

+
+

+ BOOST_NO_SWPRINTF +

+ 		+

+ Platform +

+ 		+

+ The platform does not have a conforming version of swprintf. +

+
+

+ BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION +

+ 		+

+ Compiler +

+ 		+

+ Class template partial specialization (14.5.4 [temp.class.spec]) + not supported. +

+
+

+ BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS +

+ 		+

+ Standard library +

+ 		+

+ The standard library does not provide templated iterator constructors + for its containers. +

+
+

+ BOOST_NO_TEMPLATE_TEMPLATES +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not support template template parameters. +

+
+

+ BOOST_NO_UNREACHABLE_RETURN_DETECTION +

+ 		+

+ Compiler +

+ 		+

+ If a return is unreachable, then no return statement should be required, + however some compilers insist on it, while other issue a bunch of + warnings if it is in fact present. +

+
+

+ BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE +

+ 		+

+ Compiler +

+ 		+

+ The compiler will not accept a using declaration that brings a function + from a typename used as a base class into a derived class if functions + of the same name are present in the derived class. +

+
+

+ BOOST_NO_USING_TEMPLATE +

+ 		+

+ Compiler +

+ 		+

+ The compiler will not accept a using declaration that imports a template + class or function from another namespace. Originally a Borland specific + problem with imports to/from the global namespace, extended to MSVC6 + which has a specific issue with importing template classes (but not + functions). +

+
+

+ BOOST_NO_VOID_RETURNS +

+ 		+

+ Compiler +

+ 		+

+ The compiler does not allow a void function to return the result + of calling another void function. +

+
+void f() {}
+void g() { return f(); }
+
+

+

+
+
+

+

+
+
+

+ The following macros describe features that are not required by the C++ standard. + The macro is only defined if the feature is present. +

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Section +

+ 		+

+ Description +

+
+

+ BOOST_HAS_BETHREADS +

+ 		+

+ Platform +

+ 		+

+ The platform supports BeOS style threads. +

+
+

+ BOOST_HAS_CLOCK_GETTIME +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API clock_gettime. +

+
+

+ BOOST_HAS_DECLSPEC +

+ 		+

+ Compiler +

+ 		+

+ The compiler uses __declspec(dllexport) and __declspec(dllimport) to export/import symbols from dll's. +

+
+

+ BOOST_HAS_DIRENT_H +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX header <dirent.h>. +

+
+

+ BOOST_HAS_EXPM1 +

+ 		+

+ Platform +

+ 		+

+ The platform has the functions expm1, + expm1f and expm1l in <math.h> +

+
+

+ BOOST_HAS_FTIME +

+ 		+

+ Platform +

+ 		+

+ The platform has the Win32 API GetSystemTimeAsFileTime. +

+
+

+ BOOST_HAS_GETTIMEOFDAY +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API gettimeofday. +

+
+

+ BOOST_HAS_HASH +

+ 		+

+ Standard library +

+ 		+

+ The C++ implementation provides the (SGI) hash_set and hash_map classes. + When defined, BOOST_HASH_SET_HEADER + and BOOST_HASH_LIST_HEADER + will contain the names of the header needed to access hash_set and + hash_map; BOOST_STD_EXTENSION_NAMESPACE + will provide the namespace in which the two class templates reside. +

+
+

+ BOOST_HAS_LOG1P +

+ 		+

+ Platform +

+ 		+

+ The platform has the functions log1p, + log1pf and log1pl in <math.h>. +

+
+

+ BOOST_HAS_MACRO_USE_FACET +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks a conforming std::use_facet, + but has a macro _USE(loc, Type) that does the job. This is primarily + for the Dinkumware std lib. +

+
+

+ BOOST_HAS_MS_INT64 +

+ 		+

+ Compiler +

+ 		+

+ The compiler supports the __int64 + data type. +

+
+

+ BOOST_HAS_NANOSLEEP +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API nanosleep. +

+
+

+ BOOST_HAS_NL_TYPES_H +

+ 		+

+ Platform +

+ 		+

+ The platform has an <nl_types.h>. +

+
+

+ BOOST_HAS_NRVO +

+ 		+

+ Compiler +

+ 		+

+ Indicated that the compiler supports the named return value optimization + (NRVO). Used to select the most efficient implementation for some + function. See <boost/operators.hpp> for example. +

+
+

+ BOOST_HAS_PARTIAL_STD_ALLOCATOR +

+ 		+

+ Standard Library +

+ 		+

+ The standard library has a partially conforming std::allocator + class, but without any of the member templates. +

+
+

+ BOOST_HAS_PTHREAD_DELAY_NP +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API pthread_delay_np. +

+
+

+ BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API pthread_mutexattr_settype. +

+
+

+ BOOST_HAS_PTHREAD_YIELD +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API pthread_yield. +

+
+

+ BOOST_HAS_PTHREADS +

+ 		+

+ Platform +

+ 		+

+ The platform support POSIX style threads. +

+
+

+ BOOST_HAS_SCHED_YIELD +

+ 		+

+ Platform +

+ 		+

+ The platform has the POSIX API sched_yield. +

+
+

+ BOOST_HAS_SGI_TYPE_TRAITS +

+ 		+

+ Compiler, Standard library +

+ 		+

+ The compiler has native support for SGI style type traits. +

+
+

+ BOOST_HAS_STDINT_H +

+ 		+

+ Platform +

+ 		+

+ The platform has a <stdint.h> +

+
+

+ BOOST_HAS_SLIST +

+ 		+

+ Standard library +

+ 		+

+ The C++ implementation provides the (SGI) slist class. When defined, + BOOST_SLIST_HEADER + will contain the name of the header needed to access slist and BOOST_STD_EXTENSION_NAMESPACE + will provide the namespace in which slist + resides. +

+
+

+ BOOST_HAS_STLP_USE_FACET +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks a conforming std::use_facet, + but has a workaround class-version that does the job. This is primarily + for the STLport std lib. +

+
+

+ BOOST_HAS_TR1_ARRAY +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <array>. +

+
+

+ BOOST_HAS_TR1_COMPLEX_OVERLOADS +

+ 		+

+ Standard library +

+ 		+

+ The library has a version of <complex> + that supports passing scalars to the complex number algorithms. +

+
+

+ BOOST_HAS_TR1_COMPLEX_INVERSE_TRIG +

+ 		+

+ Standard library +

+ 		+

+ The library has a version of <complex> + that includes the new inverse trig functions from TR1. +

+
+

+ BOOST_HAS_TR1_REFERENCE_WRAPPER +

+ 		+

+ Standard library +

+ 		+

+ The library has TR1 conforming reference wrappers in <functional>. +

+
+

+ BOOST_HAS_TR1_RESULT_OF +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming result_of template in <functional>. +

+
+

+ BOOST_HAS_TR1_MEM_FN +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming mem_fn function template in <functional>. +

+
+

+ BOOST_HAS_TR1_BIND +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming bind function template in <functional>. +

+
+

+ BOOST_HAS_TR1_FUNCTION +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming function class template in <functional>. +

+
+

+ BOOST_HAS_TR1_HASH +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming hash function template in <functional>. +

+
+

+ BOOST_HAS_TR1_SHARED_PTR +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming shared_ptr + class template in <memory>. +

+
+

+ BOOST_HAS_TR1_RANDOM +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <random>. +

+
+

+ BOOST_HAS_TR1_REGEX +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <regex>. +

+
+

+ BOOST_HAS_TR1_TUPLE +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <tuple>. +

+
+

+ BOOST_HAS_TR1_TYPE_TRAITS +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <type_traits>. +

+
+

+ BOOST_HAS_TR1_UTILITY +

+ 		+

+ Standard library +

+ 		+

+ The library has the TR1 additions to <utility> + (tuple interface to std::pair). +

+
+

+ BOOST_HAS_TR1_UNORDERED_MAP +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <unordered_map>. +

+
+

+ BOOST_HAS_TR1_UNORDERED_SET +

+ 		+

+ Standard library +

+ 		+

+ The library has a TR1 conforming version of <unordered_set>. +

+
+

+ BOOST_HAS_TR1 +

+ 		+

+ Standard library +

+ 		+

+ Implies all the other BOOST_HAS_TR1_* macros should be set. +

+
+

+ BOOST_HAS_THREADS +

+ 		+

+ Platform, Compiler +

+ 		+

+ Defined if the compiler, in its current translation mode, supports + multiple threads of execution. +

+
+

+ BOOST_HAS_TWO_ARG_USE_FACET +

+ 		+

+ Standard library +

+ 		+

+ The standard library lacks a conforming std::use_facet, but has a + two argument version that does the job. This is primarily for the + Rogue Wave std lib. +

+
+

+ BOOST_HAS_UNISTD_H +

+ 		+

+ Platform +

+ 		+

+ The Platform provides <unistd.h>. +

+
+

+ BOOST_HAS_WINTHREADS +

+ 		+

+ Platform +

+ 		+

+ The platform supports MS Windows style threads. +

+
+

+ BOOST_MSVC_STD_ITERATOR +

+ 		+

+ Standard library +

+ 		+

+ Microsoft's broken version of std::iterator + is being used. This implies that std::iterator + takes no more than two template parameters. +

+
+

+ BOOST_MSVC6_MEMBER_TEMPLATES +

+ 		+

+ Compiler +

+ 		+

+ Microsoft Visual C++ 6.0 has enough member template idiosyncrasies + (being polite) that BOOST_NO_MEMBER_TEMPLATES + is defined for this compiler. BOOST_MSVC6_MEMBER_TEMPLATES + is defined to allow compiler specific workarounds. This macro gets + defined automatically if BOOST_NO_MEMBER_TEMPLATES + is not defined - in other words this is treated as a strict subset + of the features required by the standard. +

+
+

+ BOOST_HAS_STDINT_H +

+ 		+

+ Platform +

+ 		+

+ There are no 1998 C++ Standard headers <stdint.h> + or <cstdint>, although the 1999 C Standard + does include <stdint.h>. If <stdint.h> + is present, <boost/stdint.h> can make good use of it, so a + flag is supplied (signalling presence; thus the default is not present, + conforming to the current C++ standard). +

+
+
+
+
+

+ The following macros describe features that are likely to be included in + the upcoming ISO C++ standard, C++0x. +

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Description +

+
+

+ BOOST_HAS_CONCEPTS +

+ 		+

+ The compiler supports concepts. Note: concepts have been proposed + for C++0x, but have not yet been approved for inclusion in the language. +

+
+

+ BOOST_HAS_LONG_LONG +

+ 		+

+ The compiler supports the long long data type. +

+
+

+ BOOST_HAS_RVALUE_REFS +

+ 		+

+ The compiler supports rvalue references. +

+
+

+ BOOST_HAS_STATIC_ASSERT +

+ 		+

+ The compiler supports static assertions. +

+
+

+ BOOST_HAS_VARIADIC_TMPL +

+ 		+

+ The compiler supports variadic templates. Note: variadic templates + have been proposed for C++0x, but have not yet been approved for + inclusion in the language. +

+
+
+

+

+
+
+

+ The following macros are either simple helpers, or macros that provide workarounds + for compiler/standard library defects. +

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Description +

+
+

+ BOOST_DEDUCED_TYPENAME +

+ 		+

+ Some compilers don't support the use of typename for dependent types + in deduced contexts. This macro expands to nothing on those compilers, + and typename elsewhere. For example, replace: template + <class + T> + void f(T, typename + T::type); + with: template <class T> void + f(T, BOOST_DEDUCED_TYPENAME T::type); +

+
+

+ BOOST_HASH_MAP_HEADER +

+ 		+

+ The header to include to get the SGI hash_map + class. This macro is only available if BOOST_HAS_HASH + is defined. +

+
+

+ BOOST_HASH_SET_HEADER +

+ 		+

+ The header to include to get the SGI hash_set + class. This macro is only available if BOOST_HAS_HASH + is defined. +

+
+

+ BOOST_SLIST_HEADER +

+ 		+

+ The header to include to get the SGI slist + class. This macro is only available if BOOST_HAS_SLIST + is defined. +

+
+

+ BOOST_STD_EXTENSION_NAMESPACE +

+ 		+

+ The namespace used for std library extensions (hashtable classes + etc). +

+
+

+ BOOST_STATIC_CONSTANT(Type, assignment) +

+ 		+

+ On compilers which don't allow in-class initialization of static + integral constant members, we must use enums as a workaround if we + want the constants to be available at compile-time. This macro gives + us a convenient way to declare such constants. For example instead + of: +

+
+struct foo{
+   static const int value = 2;
+};
+
+

+ use: +

+
+struct foo{
+   BOOST_STATIC_CONSTANT(int, value = 2);
+};
+
+

+

+
+

+ BOOST_UNREACHABLE_RETURN(result) +

+ 		+

+ Normally evaluates to nothing, but evaluates to return x; if the + compiler requires a return, even when it can never be reached. +

+
+

+ BOOST_EXPLICIT_TEMPLATE_TYPE(t) BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t,v) BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t) BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t,v) +

+ 		+

+ Some compilers silently "fold" different function template + instantiations if some of the template parameters don't appear in + the function parameter list. For instance: +

+
+#include <iostream>
+#include <ostream>
+#include <typeinfo>
+
+template <int n>
+void f() { std::cout << n << ' '; }
+
+template <typename T>
+void g() { std::cout << typeid(T).name() << ' '; }
+
+int main() {
+  f<1>();
+  f<2>();
+
+  g<int>();
+  g<double>();
+}
+
+

+ incorrectly outputs 2 2 double double on VC++ + 6. These macros, to be used in the function parameter list, fix the + problem without effects on the calling syntax. For instance, in the + case above write: +

+
+template <int n>
+void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }
+
+template <typename T>
+void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
+
+

+ Beware that they can declare (for affected compilers) a dummy defaulted + parameter, so they +

+

+ a) should be always invoked at the end of the parameter list +

+

+ b) can't be used if your function + template is multiply declared. +

+

+ Furthermore, in order to add any needed comma separator, an APPEND_* + version must be used when the macro invocation appears after a normal + parameter declaration or after the invocation of another macro of + this same group. +

+
+

+ BOOST_USE_FACET(Type, + loc) +

+ 		+

+ When the standard library does not have a comforming std::use_facet there are various workarounds + available, but they differ from library to library. This macro provides + a consistent way to access a locale's facets. For example, replace: + std::use_facet<Type>(loc); + with: BOOST_USE_FACET(Type, loc); Note do not add a std:: + prefix to the front of BOOST_USE_FACET. +

+
+

+ BOOST_HAS_FACET(Type, + loc) +

+ 		+

+ When the standard library does not have a comforming std::has_facet there are various workarounds + available, but they differ from library to library. This macro provides + a consistent way to check a locale's facets. For example, replace: + std::has_facet<Type>(loc); + with: BOOST_HAS_FACET(Type, loc); Note do not add a std:: + prefix to the front of BOOST_HAS_FACET. +

+
+

+ BOOST_NESTED_TEMPLATE +

+ 		+

+ Member templates are supported by some compilers even though they + can't use the A::template member<U> syntax, as a workaround replace: + typedef typename + A::template rebind<U> binder; with: typedef + typename A::BOOST_NESTED_TEMPLATE + rebind<U> + binder; +

+
+

+ BOOST_STRINGIZE(X) +

+ 		+

+ Converts the parameter X + to a string after macro replacement on X + has been performed. +

+
+

+ BOOST_JOIN(X,Y) +

+ 		+

+ This piece of macro magic joins the two arguments together, even + when one of the arguments is itself a macro (see 16.3.1 in C++ standard). + This is normally used to create a mangled name in combination with + a predefined macro such a __LINE__. +

+
+
+

+

+
+
+

+ The following macros describe boost features; these are, generally speaking + the only boost macros that should be tested in user code. +

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Header +

+ 		+

+ Description +

+
+

+ BOOST_VERSION +

+ 		+

+ <boost/version.hpp> +

+ 		+

+ Describes the boost version number in XXYYZZ format such that: (BOOST_VERSION + % 100) is the sub-minor version, ((BOOST_VERSION + / 100) % 1000) + is the minor version, and (BOOST_VERSION / + 100000) + is the major version. +

+
+

+ BOOST_NO_INT64_T +

+ 		+

+ <boost/cstdint.hpp> <boost/stdint.h> +

+ 		+

+ Defined if there are no 64-bit integral types: int64_t, + uint64_t etc. +

+
+

+ BOOST_NO_INTEGRAL_INT64_T +

+ 		+

+ <boost/cstdint.hpp> <boost/stdint.h> +

+ 		+

+ Defined if int64_t + as defined by <boost/cstdint.hpp> is not usable in integral constant + expressions. +

+
+

+ BOOST_MSVC +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined if the compiler is really Microsoft Visual C++, as opposed + to one of the many other compilers that also define _MSC_VER. +

+
+

+ BOOST_INTEL +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined if the compiler is an Intel compiler, takes the same value + as the compiler version macro. +

+
+

+ BOOST_WINDOWS +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined if the Windows platfrom API is available. +

+
+

+ BOOST_DINKUMWARE_STDLIB +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined if the dinkumware standard library is in use, takes the same + value as the Dinkumware library version macro _CPPLIB_VER + if defined, otherwise 1. +

+
+

+ BOOST_NO_WREGEX +

+ 		+

+ <boost/regex.hpp> +

+ 		+

+ Defined if the regex library does not support wide character regular + expressions. +

+
+

+ BOOST_COMPILER +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined as a string describing the name and version number of the + compiler in use. Mainly for debugging the configuration. +

+
+

+ BOOST_STDLIB +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined as a string describing the name and version number of the + standard library in use. Mainly for debugging the configuration. +

+
+

+ BOOST_PLATFORM +

+ 		+

+ <boost/config.hpp> +

+ 		+

+ Defined as a string describing the name of the platform. Mainly for + debugging the configuration. +

+
+
+
+
+
+
ABI + Fixing
+
Automatic + library selection
+
+

+ The following macros and helper headers are of use to authors whose libraries + include separate source code, and are intended to address two issues: fixing + the ABI of the compiled library, and selecting which compiled library to + link against based upon the compilers settings. +

+
+
+

+ When linking against a pre-compiled library it vital that the ABI used + by the compiler when building the library matches exactly + the ABI used by the code using the library. In this case ABI means things + like the struct packing arrangement used, the name mangling scheme used, + or the size of some types (enum types for example). This is separate from + things like threading support, or runtime library variations, which have + to be dealt with by build variants. To put this in perspective there is + one compiler (Borland's) that has so many compiler options that make subtle + changes to the ABI, that at least in theory there 3200 combinations, and + that's without considering runtime library variations. Fortunately these + variations can be managed by #pragma's + that tell the compiler what ABI to use for the types declared in your library. + In order to avoid sprinkling #pragma's + all over the boost headers, there are some prefix and suffix headers that + do the job. Typical usage is: +

+

+ my_library.hpp +

+
+#ifndef MY_INCLUDE_GUARD
+#define MY_INCLUDE_GUARD
+
+// all includes go here:
+#include <boost/config.hpp>
+#include <whatever>
+
+#include <boost/config/abi_prefix.hpp> // must be the last #include
+
+namespace boost {
+
+// your code goes here
+
+}
+
+#include <boost/config/abi_suffix.hpp> // pops abi_prefix.hpp pragmas
+
+#endif // include guard
+
+

+ my_library.cpp +

+
+...
+// nothing special need be done in the implementation file
+...
+
+

+ The user can disable this mechanism by defining BOOST_DISABLE_ABI_HEADERS, + or they can define BOOST_ABI_PREFIX + and/or BOOST_ABI_SUFFIX + to point to their own prefix/suffix headers if they so wish. +

+
+
+
+

+ It is essential that users link to a build of a library which was built + against the same runtime library that their application will be built against + -if this does not happen then the library will not be binary compatible + with their own code- and there is a high likelihood that their application + will experience runtime crashes. These kinds of problems can be extremely + time consuming and difficult to debug, and often lead to frustrated users + and authors alike (simply selecting the right library to link against is + not as easy as it seems when their are 6-8 of them to chose from, and some + users seem to be blissfully unaware that there even are different runtimes + available to them). +

+

+ To solve this issue, some compilers allow source code to contain #pragma's that instruct the linker + which library to link against, all the user need do is include the headers + they need, place the compiled libraries in their library search path, and + the compiler and linker do the rest. Boost.config supports this via the + header <boost/config/auto_link.hpp>, before including this header one or + more of the following macros need to be defined: +

+
+

+
+
BOOST_LIB_NAME
+
+ Required: An identifier containing the basename of the library, for example + 'boost_regex'. +
+
BOOST_DYN_LINK
+
+ Optional: when set link to dll rather than static library. +
+
BOOST_LIB_DIAGNOSTIC
+
+ Optional: when set the header will print out the name of the library + selected (useful for debugging). +
+
+
+

+ If the compiler supports this mechanism, then it will be told to link against + the appropriately named library, the actual algorithm used to mangle the + name of the library is documented inside <boost/config/auto_link.hpp> + and has to match that used to create the libraries via bjam 's install + rules. +

+

+ my_library.hpp +

+
+...
+//
+// Don't include auto-linking code if the user has disabled it by
+// defining BOOST_ALL_NO_LIB, or BOOST_MY_LIBRARY_NO_LIB, or if this 
+// is one of our own source files (signified by BOOST_MY_LIBRARY_SOURCE):
+//
+#if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_MY_LIBRARY_NO_LIB) && !defined(BOOST_MY_LIBRARY_SOURCE)
+#  define BOOST_LIB_NAME boost_my_library
+#  ifdef BOOST_MY_LIBRARY_DYN_LINK
+#     define BOOST_DYN_LINK
+#  endif
+#  include <boost/config/auto_link.hpp>
+#endif
+...
+
+

+ my_library.cpp +

+
+// define BOOST_MY_LIBRARY_SOURCE so that the header knows that the
+// library is being built (possibly exporting rather than importing code)
+//
+#define BOOST_MY_LIBRARY_SOURCE
+
+#include <boost/my_library/my_library.hpp>
+...
+
+
+
+
+ + + +
Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_config/guidelines_for_boost_authors.html b/doc/html/boost_config/guidelines_for_boost_authors.html new file mode 100644 index 00000000..7e0e28aa --- /dev/null +++ b/doc/html/boost_config/guidelines_for_boost_authors.html @@ -0,0 +1,295 @@ + + + +Guidelines for + Boost Authors + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Adding + New Defect Macros
+
Adding + New Feature Test Macros
+
Modifying + the Boost Configuration Headers
+
+

+ The <boost/config.hpp> + header is used to pass configuration information to other boost files, allowing + them to cope with platform dependencies such as arithmetic byte ordering, compiler + pragmas, or compiler shortcomings. Without such configuration information, + many current compilers would not work with the Boost libraries. +

+

+ Centralizing configuration information in this header reduces the number of + files that must be modified when porting libraries to new platforms, or when + compilers are updated. Ideally, no other files would have to be modified when + porting to a new platform. +

+

+ Configuration headers are controversial because some view them as condoning + broken compilers and encouraging non-standard subsets. Adding settings for + additional platforms and maintaining existing settings can also be a problem. + In other words, configuration headers are a necessary evil rather than a desirable + feature. The boost config.hpp policy is designed to minimize the problems and + maximize the benefits of a configuration header. +

+

+ Note that: +

+
    +
  • + Boost library implementers are not required to "#include + <boost/config.hpp>", + and are not required in any way to support compilers that do not comply with + the C++ Standard (ISO/IEC 14882). +
    • +
  • + If a library implementer wishes to support some non-conforming compiler, + or to support some platform specific feature, "#include + <boost/config.hpp>" + is the preferred way to obtain configuration information not available from + the standard headers such as <climits>, + etc. +
    • +
  • + If configuration information can be deduced from standard headers such as + <climits>, use those standard headers rather than + <boost/config.hpp>. +
    • +
  • + Boost files that use macros defined in <boost/config.hpp> + should have sensible, standard conforming, default behavior if the macro + is not defined. This means that the starting point for porting <boost/config.hpp> + to a new platform is simply to define nothing at all specific to that platform. + In the rare case where there is no sensible default behavior, an #error message + should describe the problem. +
    • +
  • + If a Boost library implementer wants something added to config.hpp, post + a request on the Boost mailing list. There is no guarantee such a request + will be honored; the intent is to limit the complexity of config.hpp. +
    • +
  • + The intent is to support only compilers which appear on their way to becoming + C++ Standard compliant, and only recent releases of those compilers at that. +
    • +
  • + The intent is not to disable mainstream features now well-supported by the + majority of compilers, such as namespaces, exceptions, RTTI, or templates. +
    • +
+
+
+

+ When you need to add a new defect macro -either to fix a problem with an + existing library, or when adding a new library- distil the issue down to + a simple test case; often, at this point other (possibly better) workarounds + may become apparent. Secondly always post the test case code to the boost + mailing list and invite comments; remember that C++ is complex and that sometimes + what may appear a defect, may in fact turn out to be a problem with the authors + understanding of the standard. +

+

+ When you name the macro, follow the BOOST_NO_SOMETHING + naming convention, so that it's obvious that this is a macro reporting a + defect. +

+

+ Finally, add the test program to the regression tests. You will need to place + the test case in a .ipp + file with the following comments near the top: +

+
+//  MACRO:         BOOST_NO_FOO
+//  TITLE:         foo
+//  DESCRIPTION:   If the compiler fails to support foo
+
+

+ These comments are processed by the autoconf script, so make sure the format + follows the one given. The file should be named "boost_no_foo.ipp", + where foo is the defect description -try and keep the file name under the + Mac 30 character filename limit though. You will also need to provide a function + prototype "int test()" that is declared in a namespace with + the same name as the macro, but in all lower case, and which returns zero + on success: +

+
+namespace boost_no_foo {
+
+int test()
+{
+    // test code goes here:
+    //
+    return 0;
+}
+
+}
+
+

+ Once the test code is in place in libs/config/test, updating the configuration + test system proceeds as: +

+
    +
  • + cd into libs/config/tools and run bjam + --v2 + : this generates the .cpp + file test cases from the .ipp file, updates the Jamfile, config_test.cpp and config_info.cpp. +
    • +
  • + cd into libs/config/test and run bjam + --v2 + MACRONAME compiler-list + : where MACRONAME is the name of the new macro, and + compiler-list is the list of compilers to test + with. You should see the tests pass with those compilers that don't have + the defect, and fail with those that do. +
    • +
  • + cd into libs/config/test and run + bjam --v2 config_info + config_test compiler-list + : config_info should build + and run cleanly for all the compilers in compiler-list + while config_test should + fail for those that have the defect, and pass for those that do not. +
    • +
+

+ Then you should: +

+
    +
  • + Define the defect macro in those config headers that require it. +
    • +
  • + Document the macro in this documentation (please do not forget this step!!) +
    • +
  • + Commit everything. +
    • +
  • + Keep an eye on the regression tests for new failures in Boost.Config caused + by the addition. +
    • +
  • + Start using the macro. +
    • +
+
+
+
+

+ When you need to add a macro that describes a feature that the standard does + not require, follow the convention for adding a new defect macro (above), + but call the macro BOOST_HAS_FOO, + and name the test file "boost_has_foo.ipp". + Try not to add feature test macros unnecessarily, if there is a platform + specific macro that can already be used (for example _WIN32, + __BEOS__, or __linux) to identify the feature then use + that. Try to keep the macro to a feature group, or header name, rather than + one specific API (for example BOOST_HAS_NL_TYPES_H + rather than BOOST_HAS_CATOPEN). + If the macro describes a POSIX feature group, then add boilerplate code to + <boost/config/suffix.hpp> + to auto-detect the feature where possible (if you are wondering why we can't + use POSIX feature test macro directly, remember that many of these features + can be added by third party libraries, and are not therefore identified inside + <unistd.h>). +

+
+
+
+

+ The aim of boost's configuration setup is that the configuration headers + should be relatively stable - a boost user should not have to recompile their + code just because the configuration for some compiler that they're not interested + in has changed. Separating the configuration into separate compiler/standard + library/platform sections provides for part of this stability, but boost + authors require some amount of restraint as well, in particular: +

+

+ <boost/config.hpp> + should never change, don't alter this file. +

+

+ <boost/config/user.hpp> + is included by default, don't add extra code to this file unless you have + to. If you do, please remember to update libs/config/tools/configure.in + as well. +

+

+ <boost/config/suffix.hpp> + is always included so be careful about modifying this file as it breaks dependencies + for everyone. This file should include only "boilerplate" configuration + code, and generally should change only when new macros are added. +

+

+ <boost/config/select_compiler_config.hpp>, + <boost/config/select_platform_config.hpp> + and <boost/config/select_stdlib_config.hpp> + are included by default and should change only if support for a new compiler/standard + library/platform is added. +

+

+ The compiler/platform/standard library selection code is set up so that unknown + platforms are ignored and assumed to be fully standards compliant -this gives + unknown platforms a "sporting chance" of working "as is" + even without running the configure script. +

+

+ When adding or modifying the individual mini-configs, assume that future, + as yet unreleased versions of compilers, have all the defects of the current + version. Although this is perhaps unnecessarily pessimistic, it cuts down + on the maintenance of these files, and experience suggests that pessimism + is better placed than optimism here! +

+
+
+ + + +
Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_config/rationale.html b/doc/html/boost_config/rationale.html new file mode 100644 index 00000000..887fc06d --- /dev/null +++ b/doc/html/boost_config/rationale.html @@ -0,0 +1,132 @@ + + + +Rationale + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
The problem
+
The solution
+
+

+ The problem with many traditional "textbook" implementations of configuration + headers (where all the configuration options are in a single "monolithic" + header) is that they violate certain fundamental software engineering principles + which would have the effect of making boost more fragile, more difficult to + maintain and more difficult to use safely. You can find a description of the + principles from the following + article. +

+
+
+

+ Consider a situation in which you are concurrently developing on multiple + platforms. Then consider adding a new platform or changing the platform definitions + of an existing platform. What happens? Everything, and this does literally + mean everything, recompiles. Isn't it quite absurd that adding a new platform, + which has absolutely nothing to do with previously existing platforms, means + that all code on all existing platforms needs to be recompiled? +

+

+ Effectively, there is an imposed physical dependency between platforms that + have nothing to do with each other. Essentially, the traditional solution + employed by configuration headers does not conform to the Open-Closed Principle: +

+
+

+

+

+ "A module should be open for extension but + closed for modification." +

+

+

+
+

+ Extending a traditional configuration header implies modifying existing code. +

+

+ Furthermore, consider the complexity and fragility of the platform detection + code. What if a simple change breaks the detection on some minor platform? + What if someone accidentally or on purpose (as a workaround for some other + problem) defines some platform dependent macros that are used by the detection + code? A traditional configuration header is one of the most volatile headers + of the entire library, and more stable elements of Boost would depend on + it. This violates the Stable Dependencies Principle: +

+
+

+

+

+ "Depend in the direction of stability." +

+

+

+
+

+ After even a minor change to a traditional configuration header on one minor + platform, almost everything on every platform should be tested if we follow + sound software engineering practice. +

+

+ Another important issue is that it is not always possible to submit changes + to <boost/config.hpp>. + Some boost users are currently working on platforms using tools and libraries + that are under strict Non-Disclosure Agreements. In this situation it is + impossible to submit changes to a traditional monolithic configuration header, + instead some method by which the user can insert their own configuration + code must be provided. +

+
+
+
+

+ The approach taken by boost's configuration headers is to separate configuration + into three orthogonal parts: the compiler, the standard library and the platform. + Each compiler/standard library/platform gets its own mini-configuration header, + so that changes to one compiler's configuration (for example) does not affect + other compilers. In addition there are measures that can be taken both to + omit the compiler/standard library/platform detection code (so that adding + support to a new platform does not break dependencies), or to freeze the + configuration completely; providing almost complete protection against dependency + changes. +

+
+
+ + + +
Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boostbook.css b/doc/html/boostbook.css new file mode 100755 index 00000000..e5d7bb50 --- /dev/null +++ b/doc/html/boostbook.css @@ -0,0 +1,582 @@ +/*============================================================================= + Copyright (c) 2004 Joel de Guzman + http://spirit.sourceforge.net/ + + Use, modification and distribution is subject to the Boost Software + License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================*/ + +/*============================================================================= + Body defaults +=============================================================================*/ + + body + { + margin: 1em; + font-family: sans-serif; + } + +/*============================================================================= + Paragraphs +=============================================================================*/ + + p + { + text-align: left; + font-size: 10pt; + line-height: 1.15; + } + +/*============================================================================= + Program listings +=============================================================================*/ + + /* Code on paragraphs */ + p tt.computeroutput + { + font-size: 10pt; + } + + pre.synopsis + { + font-size: 10pt; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + .programlisting, + .screen + { + font-size: 10pt; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + /* Program listings in tables don't get borders */ + td .programlisting, + td .screen + { + margin: 0pc 0pc 0pc 0pc; + padding: 0pc 0pc 0pc 0pc; + } + +/*============================================================================= + Headings +=============================================================================*/ + + h1, h2, h3, h4, h5, h6 + { + text-align: left; + margin: 1em 0em 0.5em 0em; + font-weight: bold; + } + + h1 { font: 140% } + h2 { font: bold 140% } + h3 { font: bold 130% } + h4 { font: bold 120% } + h5 { font: italic 110% } + h6 { font: italic 100% } + + /* Top page titles */ + title, + h1.title, + h2.title + h3.title, + h4.title, + h5.title, + h6.title, + .refentrytitle + { + font-weight: bold; + margin-bottom: 1pc; + } + + h1.title { font-size: 140% } + h2.title { font-size: 140% } + h3.title { font-size: 130% } + h4.title { font-size: 120% } + h5.title { font-size: 110% } + h6.title { font-size: 100% } + + .section h1 + { + margin: 0em 0em 0.5em 0em; + font-size: 140%; + } + + .section h2 { font-size: 140% } + .section h3 { font-size: 130% } + .section h4 { font-size: 120% } + .section h5 { font-size: 110% } + .section h6 { font-size: 100% } + + /* Code on titles */ + h1 tt.computeroutput { font-size: 140% } + h2 tt.computeroutput { font-size: 140% } + h3 tt.computeroutput { font-size: 130% } + h4 tt.computeroutput { font-size: 120% } + h5 tt.computeroutput { font-size: 110% } + h6 tt.computeroutput { font-size: 100% } + +/*============================================================================= + Author +=============================================================================*/ + + h3.author + { + font-size: 100% + } + +/*============================================================================= + Lists +=============================================================================*/ + + li + { + font-size: 10pt; + line-height: 1.3; + } + + /* Unordered lists */ + ul + { + text-align: left; + } + + /* Ordered lists */ + ol + { + text-align: left; + } + +/*============================================================================= + Links +=============================================================================*/ + + a + { + text-decoration: none; /* no underline */ + } + + a:hover + { + text-decoration: underline; + } + +/*============================================================================= + Spirit style navigation +=============================================================================*/ + + .spirit-nav + { + text-align: right; + } + + .spirit-nav a + { + color: white; + padding-left: 0.5em; + } + + .spirit-nav img + { + border-width: 0px; + } + +/*============================================================================= + Table of contents +=============================================================================*/ + + .toc + { + margin: 1pc 4% 0pc 4%; + padding: 0.1pc 1pc 0.1pc 1pc; + font-size: 10pt; + line-height: 1.15; + } + + .toc-main + { + text-align: center; + margin: 3pc 16% 3pc 16%; + padding: 3pc 1pc 3pc 1pc; + line-height: 0.1; + } + + .boost-toc + { + float: right; + padding: 0.5pc; + } + +/*============================================================================= + Tables +=============================================================================*/ + + .table-title, + div.table p.title + { + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; + } + + .informaltable table, + .table table + { + width: 92%; + margin-left: 4%; + margin-right: 4%; + } + + div.informaltable table, + div.table table + { + padding: 4px; + } + + /* Table Cells */ + div.informaltable table tr td, + div.table table tr td + { + padding: 0.5em; + text-align: left; + } + + div.informaltable table tr th, + div.table table tr th + { + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; + font-size: 120%; + } + +/*============================================================================= + Blurbs +=============================================================================*/ + + div.note, + div.tip, + div.important, + div.caution, + div.warning, + div.sidebar + { + font-size: 10pt; + line-height: 1.2; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + div.sidebar img + { + padding: 1pt; + } + + + +/*============================================================================= + Callouts +=============================================================================*/ + .line_callout_bug img + { + float: left; + position:relative; + left: 4px; + top: -12px; + clear: left; + margin-left:-22px; + } + + .callout_bug img + { + } + + + +/*============================================================================= + Variable Lists +=============================================================================*/ + + /* Make the terms in definition lists bold */ + div.variablelist dl dt, + span.term + { + font-weight: bold; + font-size: 10pt; + } + + div.variablelist table tbody tr td + { + text-align: left; + vertical-align: top; + padding: 0em 2em 0em 0em; + font-size: 10pt; + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + + /* Make the terms in definition lists bold */ + div.variablelist dl dt + { + margin-bottom: 0.2em; + } + + div.variablelist dl dd + { + margin: 0em 0em 0.5em 2em; + font-size: 10pt; + } + + div.variablelist table tbody tr td p + div.variablelist dl dd p + { + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + +/*============================================================================= + Misc +=============================================================================*/ + + /* Title of books and articles in bibliographies */ + span.title + { + font-style: italic; + } + + span.underline + { + text-decoration: underline; + } + + span.strikethrough + { + text-decoration: line-through; + } + + /* Copyright, Legal Notice */ + div div.legalnotice p + { + text-align: left + } + +/*============================================================================= + Colors +=============================================================================*/ + + @media screen + { + /* Links */ + a + { + color: #0C7445; + } + + a:visited + { + color: #663974; + } + + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, + h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, + h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited + { + text-decoration: none; /* no underline */ + color: #000000; + } + + /* Syntax Highlighting */ + .keyword { color: #0000AA; } + .identifier { color: #000000; } + .special { color: #707070; } + .preprocessor { color: #402080; } + .char { color: teal; } + .comment { color: #800000; } + .string { color: teal; } + .number { color: teal; } + .white_bkd { background-color: #E8FBE9; } + .dk_grey_bkd { background-color: #A0DAAC; } + + /* Copyright, Legal Notice */ + .copyright + { + color: #666666; + font-size: small; + } + + div div.legalnotice p + { + color: #666666; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + .programlisting, + .screen + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Blurbs */ + div.note, + div.tip, + div.important, + div.caution, + div.warning, + div.sidebar + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + /* Table of contents */ + .toc + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + /* Table of contents */ + .toc-main + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid #DCDCDC; + background-color: #FAFFFB; + } + + div.informaltable table tr th, + div.table table tr th + { + background-color: #E3F9E4; + border: 1px solid #DCDCDC; + } + + /* Misc */ + span.highlight + { + color: #00A000; + } + } + + @media print + { + /* Links */ + a + { + color: black; + } + + a:visited + { + color: black; + } + + .spirit-nav + { + display: none; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid gray; + background-color: #FAFFFB; + } + + .programlisting, + .screen + { + border: 1px solid gray; + background-color: #FAFFFB; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Table of contents */ + .toc + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + /* Table of contents */ + .toc-main + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + background-color: #FAFFFB; + } + + .informaltable table, + .table table + { + border: 1px solid #DCDCDC; + border-bottom: 3px solid #9D9D9D; + border-right: 3px solid #9D9D9D; + border-collapse: collapse; + background-color: #FAFFFB; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid #DCDCDC; + background-color: #FAFFFB; + } + + div.informaltable table tr th, + div.table table tr th + { + border: 1px solid #DCDCDC; + background-color: #FAFFFB; + } + + /* Misc */ + span.highlight + { + font-weight: bold; + } + } diff --git a/doc/html/images/callouts/1.png b/doc/html/images/callouts/1.png new file mode 100644 index 0000000000000000000000000000000000000000..6003ad3af44ecde89a963d5af6a4180217319dfb GIT binary patch literal 391 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`*F|>EaktF{gKeVcsDJ z0oVU;*6~a;Smx2ZrsEQ?ZxM&ygvBnFE?nmtg94rky>!~x8m)3j$<^(USQPg)>&zq; zMi;kRX=V2=&tIr>`d!)XyUpL@9=UmHetuZ+!_#HmOU>-J$pS3-bN!ardIyAF-G1#? z>&)f7E`k#|4sWoP;JM|(l6I_WZ`%~1y>agujE%b%?TB9+mb}(fsxyPFgQGMy*=%;A z(aZyu>`GQPiY$*T-1gu1pAwY3_N%b5cB#xoiRPn8jf*q{Trb|_a%sui&dtzin6_r? zu}%d~p(mAmOGTO#c2u;xJ(}Y^?ex>t7XL(?7U+1p1hOa|ab;w%c)sCoo@_(^WX<=s zr#89B91nl^w~jx#=XQ?S<*?OXYm`>JmO9g8;`^U+STt2<{M7jt yFTo&UT%Db3I{*CoWB+`guig6oxB?on>HF_suX>mE-_|+p)}_VbyG%XWRxDs!Bbdb`rSkCf z_opQpQ)e&z9?Q3;X^2drllMU70&71c8CwuJm{abIp zeHPuYNTZJ3@x#oHxOW1*hRe1@t$mhYkYRMp!NudU$f{L`HtEbcpPpkT-Q%WwW82?% zC04fVjt$l>J1E5m&cv;Mo-ym249h`b!OT;yI|^kU z7g#)~+Iz@=rzNo?Z+rL2lqSFB&0ni{FPmfwyfr;gD5K)Z38R1FYejhuGSfQP|hTIvQJ?m5M8zE|_KJ2Ny0Fm1o>%kU%6J0MhalaBNL z`|XP~Ht29?&a!*3EqAew_mM&!z3HdD7hn7l!t9~x=u!|XzH8m#&o*bC7c(?GuT1E< zIxY74U)KBI?en(Zj`8vg@_IC9@{~!dRw-$!in=2h%i uo%h^T#Pz@K#3`Fjeg5EaktF{gFX#;)5A z0&V{%irr-ME}D3(<3UjG?A^;f=DTxNc8JvRJ?~omN$9208L_ft0gE{24F|>2&Q_(X zyZRk}S@Y!IJLwtuX$cuSW9kad-E9>}+B4ar@B8JKU&IA}ZdvzvdHazWz|5Z1g ze)`Eh`){a=Ty&?>q6`CxFY1#$=XWS5S;+8pJeF8|am8VmFNNE0pWSjTLp3m4UCF?B z)v7}^cJ1H)wSBfZUSXp*CCGT~*L1 z!O^woK;8cKATG~IcM5iAPD}l8PyF`VZ_(}ou7b0cInG+vv8ev~-ZX{}_a4{SRWsNx zp57$DG;5jTyyy8w3^D7&C6fPqtf+bOwJP3cC`GVy&NA$7e!FZ3*ZX_(gMKMn{jgqg*t>n5-mVwdc+LxmI|e9UlrZu5 zQ({_ROHtjRNV$1z%lk=bT+YJ`-QVnLY|jT_oBf)`qRPnx(gN%Xx|4tEMdaVwoi3 z8lgAcLau*<4)^ratatOor+TqI{wNVS?clathJwW!uZ)j$%&5q+Ew{P&-MZ_q|3(_ifRH$!b{%@XfPPgvO) wR!x~yId8sr_tEzopr0G&e8k^lez literal 0 HcmV?d00001 diff --git a/doc/html/images/callouts/13.png b/doc/html/images/callouts/13.png new file mode 100644 index 0000000000000000000000000000000000000000..5b41e02a670f020ae62b7854482c4ba1980d73cf GIT binary patch literal 509 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`%IK)5S5QVovKN`}4B` zMA$w&XL9s;aOlF(1%)YvneO4jm-o(&U;MKD#e?Mq8+>b)^R3G((>5$`ILflv=tsMT zqri^uWh?XJrteF)Ir(#L@uYSZ#}5m2PWL-;h`yh)YSr?%_21hCg6ylJ<~^TZ68k@M z*0PUs0U}2m4Zrz%{ru!$;?!{|$E-JRd$xd+!qOu@YuZ+=+K?-K{IOu7#Gy?(C029K zJuHwgKK8+3O1mEi<8zsP?~|?OE?SqZ;@R}Hh*OcJN#Q`=cIVYsi%fl`jgRf~&@_Gf zwzE(sdH3B%ReKL@(z)}#{LAm!8Ou74CNVNBn8MT`ef;AL!#4E;rLlAT)H7zW#a>U8 zU^AP|o3>d}=J>$`0|rHwDM43C-@g0)`~9hChd_}fnOvtgEzsbyc%HHSwnVR+$0Qaf z4hDzV>nAp?Vf*l#Q@}~VH~7Z3-c_p%=AWOKD!ECAd8tU(q6Mq8jughk>rJ2Tw)o@M zm#pV3mrVI!!@p|Pp+XrSHQ@j+Lm56tj!LO-Hu>!LzuT|B{(4Tap5^mRI^HKOr#o>( zhECmcH*b>$SLC#%J&RUEtqrq3WKa^{tg=+3a-Mjg$X|1pImHv7|6G6l?EhE#0)GDv Vq@B#jVqjok@O1TaS?83{1OO3{4iFg+V~@k_l_W_wBcH zWmp*BaqNHHW9Xsz@VDKv%bG0$2|bO5Z6>~kGkrGPetRKrdu;6W&)@+-S^-5e@qWpx=%~ppu-*HbtcU?B((KtQse2TO*ZEl8Jswt zRO&J4%x73CvPq};vBd=w-op^F6<=oH98=hD0fB5^~^0#Ht9-5wBo~e$L z1lS(@e{k6MP=#(Q)65P&Df1-{87Bltt+Mf&((ZAvc!Ef@>!Js&9H9b5iNOkrjBYL6 zJ*_!sB>iV?h@ACiit<@=<+J)R*K4P%cxw9w^X5-kmdSp5TRo@ZmA&eVHGWMv{dC`S zuce2g9b}I0mp%UT(3$h)E?kO6N0T-NtiR6f#9?6EcU;-Tw>eSb#{2IdZ1@=hR$sjr zzyA8Z#}+%3XYST(VGvBTnww-G;h@R7RHW^&qTY1wDM1E2%vZCnP73-ad;I5-GeP_8 zE`G0F6Q(`qeEN%Bd`m@QuDc4b82Acr%ROx3%dny5{(I}bX7&S{bY%G0Jv1kte!3xU z{l(W`FJx^snCW9M|9s%ekN~~u3#V){n|<~=yTas?3Ovp)cJVPNC~di&>!GEaktF{gFH!7eFB zfwuoy?SYP89?67Uc^u>7$ueKD;_TuU8yCKP?%y^nk6}6Q`Xb ztf|`>GH3mp6jYb?>^RdSfr%@^R!^go|6uIuQi$NDW>upBo%&=x}fma9VINW5Ly|Qkmm3JvHr(Hb1rr&)I%k zqW}1XsO0Up4@Uid#O=~jwU>`!u0>yZkk=jF7J(OKyBQi3I1HqEAMAR!+FC^5{Aa5( zf1b8B8nUgv%H`5>GKER;h_=JWcU60(815ha{H$oF%dBM*eC_{b&TZl;l$m|{>8A+2 z>GpSd7ik$I?GB%onzMHA^lP*F zk0)=tnX|7g@rLFCKI7=6AyTdvVl+z`(%Z>FVdQ I&MBb@0M`i8D*ylh literal 0 HcmV?d00001 diff --git a/doc/html/images/callouts/3.png b/doc/html/images/callouts/3.png new file mode 100644 index 0000000000000000000000000000000000000000..3ff0a93931515bb97a045dfa61a8530d87e458fd GIT binary patch literal 431 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`$7M>EaktF{gFH*{(+p zB5wOOu6l7m)8 z=-oKUH}V^&iJyB|uo8LF()AHB5)-MfO`N3nt zvX}OXM~sd8*9*0GtV!A!kzpdmy4F;zn{|?kqeR<^5G@5I1_ong&q>Sg=9!B)JHv7pU)=hauMINB3;oaL&ye>}mU!H{id4Bxig=9%^>^=*s?64R8I`k2o? pd-p8Ef~{sjr?y8+Fx+F*x_2OD_kw447#J8BJYD@<);T3K0RY@Tw*mkF literal 0 HcmV?d00001 diff --git a/doc/html/images/callouts/4.png b/doc/html/images/callouts/4.png new file mode 100644 index 0000000000000000000000000000000000000000..6aa29fc0b48c17aa6ce5540e1af5c00510c33ff7 GIT binary patch literal 441 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`)qx>EaktF{gFH#x5mC zfwup%GG$o)=ergqP)_hu?Cbmc-FuV6=PTSkE z?z;W`K`XyJWKnY38^_LI-}iXo6rn{K^Ugm{NGsVLTQQIQc;ScrMIF~}*~{?xZ|}UC z)%voeOU2Vbu7Bb(%{5!g=daxAHc3V5z+>?E76HlSc>&q{{ zJgU5>EY^K=``x_dYqp*_vnNK+lE-=9auZ+6u0=XLho7HKd(8afJ98Qv1B>H_g?h*I z^7xt(_!*jJt_^x6<$Ce%iJd)$VVYl~OqdVEFZF#=7-s1t%fP_E;OXk;vd$@?2>|9n B#bp2h literal 0 HcmV?d00001 diff --git a/doc/html/images/callouts/5.png b/doc/html/images/callouts/5.png new file mode 100644 index 0000000000000000000000000000000000000000..36e785867ad9b06bb5da296fee61b67cd8159ded GIT binary patch literal 423 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`&U2>EaktF{gFn*{nkj zBCY4o9LZ47@QCRUnZAf+N!}-g*k62kUh<2$=N}3cU-wJsu7~Tf`D?j51GwEfg_G2_ zuV#t97&qf=>*tSit#h_USr*FJFU!>WaGpbPU+ne2DLtw;&jomW^|@TLId}ILd4;Y; z`kGI<1$&J<4oW?f4p9*ch$x|rP+;KqSwET0Ksa~vKtM(>J91HOJ>EhB>xN^tsw+8di7uv`rMqUeL zJtlGLsS$%o&3$<<&56<(YY$o;PcU%UfB(F1o@3V5sOFBi;${Vo2fOrSjvstkva9-x zil;zZBGUt9^BXy4GknxI4hvj-p!#HTV6S6ePsEk3N^VkheYYwwc>v z!48gj&!5^CXy3`&YF5dr$YOKedHr?gg#ir$OfFx%f9Fdu@F;mr4Z2vhci-*k?73P? f@97_A_`n?SY~RWh)zCHu1_lOCS3j3^P6EaktF{gFH{#8D;%7vjax1W#KXIAnv(J`n z&5VyM+63~m6_r{NIT!+`rAn_gmE-I&+!3QUA?T1q^ClfZ7RG!2%96cqg2wgyaq?lS zMX$X!U8LbO@45W6mvfv$L-`J@Z+FmS&DLGD$|-VMfY)E~efQs=*mUM;<-bcWOZM5Z zTz)B%D3P@Lt`d*4kJ{wr1(Q_jEaktF{gLJ{wyX( zf%f{%yMM5|1Qs>DxO#n#YtRpleGYL4%{eMNMC?4cR!{jhN$+gat*(bhBwQW8eR)?F zba$a+^0L_vzt^7O@l~6=`|-z${Iyee1O}bTzyIC7L&Goql*H!=r=P}oFAaJ)O@ZgI z{@Sm`#{5B@N=kt`V%+OqiyeDxcc)!#?*L7k5+eADVIg?*L>hpfK3x*)1hCVBt; z;|%wV8@Gym{wcFIjN7SWb%BU0N0Y+6yzR|3cK@fSPF7(wKKyx4{o#4fYt#Iv1TDJ# z*2#-AZQqV>`4S8w#?i?>7PHU(+hgr1l-*Nl-OBiY{af+c^=0Sh`7EaktF{kyy#=ct) z0&EZJryZ5xyvdOv(510`p{HDvlxC~E$|>iVgULHQ3PYvrom?h2P4(>+k=FEToVfLb z-1}ul4-dV}J2m&O{aGGazV^u2>+);2+U^P78~6Tv*4AI1E_e2NCZAD1|9M}poAQ6# z2UUCjU5lzOJ!f0qp`v6c!}s@T(aY_*-6p<)(^RJf%{ZH;pv2Hn%$FKjXEE0=dabFI zOUbTczTJ2ED(5xNoT$P%L(+vssY!q-Q6kB1zW$Oa(QCh^Kc6#2_JRrTx8JslG@1mM zBBvdU`kln8=_3m^%&og1Cq^RrH#tzmz{IfafeFfcH9y85}Sb4q9e0BP^KrT_o{ literal 0 HcmV?d00001 diff --git a/doc/html/images/callouts/9.png b/doc/html/images/callouts/9.png new file mode 100644 index 0000000000000000000000000000000000000000..abe636072b61306fbcd6157b95dfdf7e86a77e5d GIT binary patch literal 420 zcmeAS@N?(olHy`uVBq!ia0y~yU=UznVBqFpV_;w?d&FzWz`&U8>EaktF{gEcf7T%f znb!OIl8YM`EC?0g)MK6LySsR*bBW@-#a{$sD|jaA?Rq5|BVw*<(2>_Fw2;L_Ls+eT z*=m-pP5G8*zMrjje*N{AqvqEc&v$lO8~PeQnNu$u7&XUG^XcT&$oGAZue{@YWbseb zX;0Q#doE68rNi6aM(w}9J~guKY8ESl1YdhX&(saqqyj~D?!KF+)#9L-_*{J2Y1Ks< zObjyp?mceG5^anO3Q8tYyaIvx98EzeZXaKe_`Z|7b6wRX+{3FhZAn{V<2dEM9+du_kptYsE+ z{WKfa2W_~S^T2{nZ8E1=H*3uG*3`)V4^%t_SRAV?Wb9U5edYbrW%=bs0jAGCWzMDv z&-uLjLxRB%P3bLBx;@8}pH%jFEoHiFvT*CZ6}7y~440#x2c4?eefQp-XqD5OV!VD< d@-ZKf|NC_Jf+y*vd<+Z>44$rjF6*2UngH>Mv>N~b literal 0 HcmV?d00001 diff --git a/doc/html/images/caution.png b/doc/html/images/caution.png new file mode 100755 index 0000000000000000000000000000000000000000..3c3b859c2276a628a5b5c7dc50ac720abec0b612 GIT binary patch literal 4286 zcmeAS@N?(olHy`uVBq!ia0y~yV31>AV36WqV_;xdu<*?m1_lPk;vjb?X7l5|!3+$X z#hK2|0h!6k3=9>w-p))95XqD}e*fJ(8HpK^Z9L9?LaICpmg*B_Tv*di7#x})VxZWq zy`ibYBZx(iHKw4Hb5mEB2Ahi`BlE6i9i~&ec66;+ai^#5!>V_$?CwrqJ^O$A_WG}1 zg1?qjto{{#mEnY+%Erl;6Py_)?R;rtAI_fUks%>$&9;GobwvZ?6Xlzkn)m+cF**n& z>i?L&N1A!UhYJ7q_viobS1g*eQ-(odPJ^(;#mpSW<=hs1lg|iVQ*W6wb)M3SgMLiQ zKC_5xJP=THuYIhdc)afM-1usyKQgQ_d<=aezo&A#x5|8-x^j8TnZC!W%nG-4UxfcQ z`<{JdYm528p6AQlKku06dF#Rcx%IPDr>WIE2$cNj`LgQco&Ogt5B>erdoQB?F1x_u zPu01bAINTqV{DjGw|=E8Tf-*lhI9AcZ(Z@2p=2tP!rv)#51#%L=FBN>qQJnlfLU?@ zM@XaC1?FQ1WFi=?AMn^T@N+OMOi)f}wwSI3zb&ztZI9;Fzto-3z-thU5vcW{0luZ_^9gKFY<%gy}jQ*f;rak^pH-|$92Xmm?7Xh(H9X}KjJ$Mc| zZ&PmdV7=6^MbY*ILlOT&<x@g@dv416( zCA78SSCiV}rx$l+cyF<`Vv+4W=On&B`-1NazAvF)G^(Wj@--hcFqkD#+#{_fGP&X8 zL6Ky>=UBzt z9zXh2Ai6^=Mn8|mygB+<_v5P{r&Y+?ug)Og|s`DcV6$De1u;`%d`E72bX&4gl`l5Cg@F+n{;o& z$rRpAvX(t_{O-Busl_YWtL_(H-1)M5XLsR|vW}}ArCq%pdlx;>d?iwS%FWAcX;aa( zqIM(wKJn`U-=hBY66?o5>*~5Pt*z2xu{g=oHVU#X;#48l`>g&UnRbB zm3FmV2+8a-G0QbyJF#r4neXunrZ3-pVW|@QoBm6n)^U*DNs+O@Z<*vmv!dTGVdqNUwl`ZFf^RHq4To^%!%N z;=(S5aE6==&J3?yYNKo**CM6W|?N(y?!iX^A_Q){Mq-fHkSI7J}Sv7dH3Sb zuC!erceR(chc66|T=QsMR)py~_e-0vpT3fPb@r9?7u7GHzbt>b-zdPC!}vzNLBfZl z7p@qb+;H*3M!~Bm4r`oWar{MovTX9U!rqU6uRgh|x4L}IySTr%T&}C!deU){Ie6B} z?Jwmn+g(1N_AJe2v)N|LV$;tYpQAn(ip|~H7kXw_UgNfc4L1@C?>%Z>Ix}_GQ_0i& z*L+zcv^Hu@+VzZeopG0Uq@9X7YISMXy;=E(w{&i>%sRY1bX)J1+zqv9%d?Je%-%G6 z^8=hpm+;R5fB;iL-UWL3cdE!&bSF*0G?$x44La#5q+Vmjn z)vU)=CwbpKd%5j??w#0!bKl;3v+qITyNzcT-=F;C<@?CDKhJm{?|y#uF>iHsh5Uzk z5v%u2+r8~H`;Q&JWj<7H@+*#gwd;P3;l9^3*){WjOa6TNi}%OnKjuHT|Jcu6z@foe zA+thshTsix7fvqzEWRkNGA=#tXYCR#Iovx%wWOuwZ^^dta&u*KMaR6~^Y6j0mj#zU zG=12}J4hST~q|ncfGRO5er7ZJJ^L_Sv&4M+XqgA#QZ0E_ldUIF#YoBf2-#*HO@L4a{54S82fA_@fckb8Q z3*QFb{#~}>-HH2#doPzhKN;H++qpaMx#Y8{Pxs!H-LqRgUa>y?-xdCK_FKd{L_csH z`yTOja`y_p)!zK6eLn(=Aw)A!}>lzeb&^>n?fcxYjd^B=GEr`~C8U3F=d z|JA~)i%t1V-){Z1wK{t`Uol_5%tq@=Vao%;L%x5^_;Zo{>$bK43 z$&#@+XLaw6%I%OVUw*QDXZgS6{>gu7pPxMw`#Eh=*bdXhrSC$1tlVvH{rAq@W!J;* zpUcp<;`K|PQ}@yPh<thwOC)X?^)B6)=6x{;a{0*vFZ?{n84g{J(pqCD#i;Pj15Bn`2V^xTe|DM zEn{F{P^b!tC`l|W$;dAPwZK06>YVh^2`li^@i^0!AO@)k!$L4eg+1%vz{)F zAs)x4hDGPcx{JnTpWRnE|M%Z_kG*SsAH^7K6JDNo$to!Oa@#RI#a#IbKNuf|e`xr{ ztsttP!@6_5%}17|?Hc-;9SvGrm9}{&ZD05H#`8I~GhfcCy%gj$XI@@rX4CA>R^3UDk ze?(@c?fUWI@P65?@BZ4pF5fd>d`i^;tySUGS5_;vYk6E)GW+~GzS!Nf3BVf;bqnK-~F{Rmn-ZH z>U}jbPI#&1T@inFy0g)d;eL3X*3u|p;Zv)xPT^t_ElRi|&n+2n@RkC)HmJ+t7%B&Ewc;^tWy#?7(ncGBcrr_Fyk^XKfX zra#Z^et#-{&-ZzE&Zekb$qK62w`K>YY1CSg;%OhZHCtE|`|wBlz4>omcbnC0$HKHn zOAiGV*WD{i@@#16?}*}cI^KA8?b;VNew%wI+-6AMv1lE4-}A#BYT4Ie7Gg?z}{JGI@1p(Jc!X_Z%cGpe6+#BgvG*)?MdZ? zbg7;+^8~=A1iwYuSb!RZIy93<`4W-LqGp zIxG6Ta%m9bY}t$NuO9982`F1~w@vV{2=mD!ogxpjxD<^4mMpgAT~pcX(%g5ue6LlE z{;mGNsHudwD9|)1V8r<2a^3e30XW@(4f#p`Q55DjAUZ&amUG?$mssEf#{mEfw z_KP;CV^S#&Gg`rR&41SGwT|3>;;a|V&)9$Mfpmi89v3bv_IQW0Ti@(?yyr|{e46g+ zZ=wd~Dz(jalKVLFM1HSUH@ac=^znJmUO&N@UyQBGoD(I4$hDCzDoT4X#8TXW&ggQ6AkgF z|NXODw|@QOv$M@VURxWzWAo-_xp=XOER3(2yG~BdIKQ{!j+2C(Y|!P>pqF`T)puOj zW!-2}`{RC+Vd$BCG3UNUW>q`0<^{=~jSZYz;ZhQO3-+okmTH5-3D@)tTH{RV`-l10?l}34HS$sRGa)|4GoFv~Ae~m?Im(#ai(hz_1 z*Ii;;-;WY6hZA?Eva>Jv!4z=k;-sI_1?->MKYZJ2o|yJZlM=jS!txY4mpriZ8UiNco? z$9}|b+kH)$xtT5X;<=LRJ?Hse`6(rozGIZInc%G)BasurH;!Nbe}t`JpYXIf)mqP+8gEHX>XNhwExol zb+5nK@Avt3v!0q*t*VaGu2nF|IZ}A+n)kx9uWREr_Z{*GPu@K3&AC8%W20O3MJqCP my?XOulB2mf<2BO{(rMq>1 z7#LWXJzX3_D&~Ybz{S|QJTtnsltMyEt#Tl;v|NO;v9`l_))3dflS?I6H zS$jb(b8Yh49f>lyi&H+{FUwhqPozXyMAgO$PLw+`X@4OhhomGBmA=~_D1Q| z?(N^;kt-&UeO&ro!23z_CpvBXaP{id|0zp@PKp*eZJl6q)iCX`F;BBgsd=1hc4&a) zEyh_>uAVrSc;ahrP7&MLKNGHInTDUx&k)}w9vO34`!qEvb~Xy+uOKSNk6( zv>&s)yq>k+I;w5?&Zpg<%4gdDwqZYaQLJjmv+%jmwG|syM_%oVReo^o_PjjaM7Ish z%6k_b6+O8rr!cN%apG0A(wB=$YHNA-OxUBqxl-n{cURlZO&2dNS(0$Q<181K_wme! z!n{)kHWuM&S&UCb0aq0ZIGZW?u^!O<=L>-K(iWQ#!f&awIi~NtKn%sIO zysE`fPPtq4blT$3bj|?BBjQ%~?%&@&tBlv`vO)QZg=^(J6gAz#^&9)vzubFYGj(I{ z;}Tc-#3qy78U}A?EOcP#Q?apAnRvqG0f$UuEMI?tTUTx!%L4g}&z+lIz6|B7-m>kl z{@$C2P*-MY*kqgm~B%yI-s@dRDYk{?7W}Z?E5f|EK8s&W{ye*gx9diU zmOq8Ze{aYYzx3*^*y;8PBROw5)u6)m!yljToz+(LCcgfPjEu~jdGi)&tO}DlG?61f zZ+dF}*L%$?Zu8zQQ(T-`e_qx@ab<+kG!NC7_pvkDdvlNQojL3_|N8W^X@MeFn~tSu zvBuQxHhFhLMQQ74&b`&*29bNJ^)%*s9-q81#p>n93c2kQB5Z4agc-50<}GzhKbyAM zVQbXc`g6_Fw<;Ij$@`nI{ijW}qe`<%(8my~r=Ndorri2`P*7^B91lyN$XSIB$Mn-r zi|%i4dS;i`H0!41%9~HV{eEz!P;I84k|ayhf^~e)44$hl-W|W#tU>y=*Uqq|H?%~! z?7#ig{GS=TcFIjTcIC6 zg}t5zefbcecUez&&H3|QF5Z`Pn-4xMYkgo))FX0^>uAu&N1ql&t-W{W&L8ec{U2rK Uy!q45z`(%Z>FVdQ&MBb@04`<@YXATM literal 0 HcmV?d00001 diff --git a/doc/html/images/important.png b/doc/html/images/important.png new file mode 100755 index 0000000000000000000000000000000000000000..54b4846b49cb77d09578e03fddef8173e5b2cde6 GIT binary patch literal 4666 zcmeAS@N?(olHy`uVBq!ia0y~yV2}f04mJh`25Wk44otVv!`vx;GaF%2` zI|pPYCo?cq+iGS4^JFAuNVf4f%QU%gGJBl!RACQnlr-uwP+|2s@rY}U zg3=@rM;Au%nAoN@i)u_i-MQ;$eZ}u^fBR7X z_U)_cLwOtCR4A!yikdMfbWT6^y>w$bTYHPq#>EWW0S#PB8oXH4O>dq)e^Z`g^Cj+o zs_)$xw-oJJ{`>v;|HlP(dfMnQ2>6}&cxOdO--OF8GN*kXt-EqO+`?ElGNM_w)#o|4 ze!z)?+A=?Tg~KhLNx%Pd>+$>73Qvp}3YN@R?_;s+(8TzeRavc;8~>;RLJ@J^KWEz9Q-zk&No&OQ$yjCZ}fkDK9-N-?3 z1(WXr?w$t84J_LZaPDBvf57i_!0iCzMg`6fj%p_ucRSc=u&6#zSi!V)0i#J{SOHr} z)8_|9JJ|9XcPFseurV31#x+%b;L~vwXlXqmz&ojNibAOeyHV4P38qh2DxLNPaES07 zb+FNpJ=Iv|+!~-6!g|%w_k#Wf%NIr^%u-EqPQn*-zL1s<_R1!E%BRqtmtJ%vj*IjhsssQys*%fwIY_G6n z$$e$@bvwPd^nzH1d5M7)+uY7`?$Z}bUwr#w^$Wo-BEMwWniCTuB#e8s)mVi4PaYFV z6eM50-!MX5nP&PH_F8enhxTP>W-2 z%j%ZGL()nUS2&rd{}OoIVcjWurp`3r$_(TcprB@sj6n4|R{}9{is9CsH=C z-JB-l<){2!*?i*q3G*l2@4k5C%aJ=rb|hIJS#{LvNZZl4zz-s&U9zdls@*|;mfky^ zX9^$h&hD`8aPP<$UoU2_Zl|_S!Ev&|ln>K9CTUE{n6^XF(D`VP=?cFPJ=6ZGo~l+W zPv?wPChSt}+h$*L*zGlYQSu9&UDCGm;ynJ(wDXuheTkQpH=9@9#5L3QC}<`q@bI=t zD^CnOV{up_wPs4tgiVvXCf(A$s%5IPRYO-jS6fy!R^hIitlNC0{FAILw zspAzEea+o0_*=)D(3_T)yXGvFabM@~uIG+&Wkg)`y>Pqee>46x{Ap@h)YR>?$!X~! z(N;^>wnb}`_9V?r>VLFG$oFKFrr%1Rmy0fOFH^bPH}k}rgl~q=r#_t;JN5F^*HhT1 zP7jIDV$|BHm8<0+!nrEvYQ|Ngt8rH=O;t_xx5{i4+v@(RqI6r;nqP`v>%O}3PIH@Z zOs?0jS8|%k>E5YFvl4r=CzaFsU1li!Z z7IP0k_om$~}onwhgAcSQEyl$d=k?zmo3yt(`A+q2&r*ysN{c<74K*+)G`_yj1*38@zw6SZ$s?9TmT)%vGv z-+p1cmv@hS&-^vXYrP}C&*ndtKG%Qi`Qmuz`!e_I>}TCq+n=_-{NJ~KNB{LRn=oHu zu42|~Ol~`#PTcBwRlr?@s#4Sr#?BGZ-;G{y(PDEZ+ZKx zzCE(R*0E*t?zrBVy5V)%I>)@scen34?%w@b3=%!mVBW7 zvA-5O%D>(_wKtw?2dgDT3yWW4NER(x3VVpYg$ot1w=M59fEa^vrY zDaUW#p7zn;`-cyLx0Tm!<=Wc1Rlfh2Y;C~vpzDF_1LNy>igg~}_}q4&?cd`!k9~VL z^|toT_y6F>;rDCan{1=(tgLDIdU=h}m!i}BTj%cjz4`I^*tNUXmge?sJ9PO$$*-5< z`&<4SRULcm^FH$1&1>;j>(^#3-zr|>ARBG{%sSbcHC8d!`T3pmU(2G)w*O!D{dVW) zQ_olHd&FtHQ~dJet4{oxT{{Xie_p!tbjIn)duLb4$8+v0+JAm|{)bh^ufD!MXMOC; z?XUM&+Hh9}C-zu=y!Ipa{h?j0%imABr>iTr zXL@D*C+6SI|Bo-|zwAA8{)YKlcG

{yqAbT4R}68To`sNnBuO!wFUwJ%u91iQFAA z4(LLEUpNJL3u zX-P(Y5vU3F*;nVJk4{*DpN_{_PhHKE>He{kMlDyaCmsSIEHu}FAdKwmT?!g zEtmT}E$sc(!yD&F=&(m`6P9LT)S4<1T63EHAEW%w=$hp#9w}=s4^k0$qx9g$!D+(# zA4T|QFP-|$(%QJz@~*M=T4tZn_ut<6eBb;1PVxD-f}wwH8_X?hQl=Mm%-(UjW0s=N zrO?SHtS9wUEW`ZSl%y2>dR9$gd1&py4$MMs|kK4HvId)u+3dzd06JY z`5nGb_9<`L_O=KXy^pP^IK z$G5qfAz}|I8Qm84f8#HZT2|cl?s5XRM;Qm>;?G?%Pg3hX%1O*L=FM`u z?LT)4Ui~X!dnsbb@pFgl#;P>-j~C}(@MMdcyR*+gXIHJxm-P;7Go{b1nEoN|rYpB5 z$ES{+t0jaN-|sFgxifvm?UD`Re?p$Ub~yMs(?CGFzrgSKl2^HpfBaCEnYqg6?CleW zgIDODQF~e3|6U@KB|U^|PwbM7O3j}x=Eyxbc{%;Zr+2nBpMO}g1@b)SJ8L4Q_Tl#Z zJ&i{rXM5W_HzUA;W`3rhJ3+#&f-h2?;(PY>;tHR&*?WKZ1u zWgHXz)YV^S@lHM{8+Jm^a>|EFZzla_b7>*58XevB503Rp7rp$X>T@mqp{Vv9KLNw7 zaa9^mKiNvXeze6(sJNoDC zZ@Fc!O?jqESyY#aCT{HMu;XiE<5bl5;<;}Wb)5TI%jR>e-2ZZ(vXi=|yzjBKFK-m=k9EyZ zu=TC(|FU7{@I;VeDXLCP`@nzMVw<0M5t{h!#nx?H;C;#vU z@ZNspJ?E;is@RDMk0z{PiLIT?%X#SqYu{{rm5z3mkQyJon}32PmK-@H7}ObjIY?3Q zN!Q^r`9w?A%bkLaoEozi-fy2A^t@z_^?d&D`{xwjITc>C&DpxmBlgus{l7e7!jX0_ zBKnNlCZ{Z1Z)N{FdGk%T?RM+8`At@FJer>^SaK(#*@t)1M8&gH&Pi^|i|SQ(itXLi za_f+mM2b?r*JpEGPj6K_OFT7r-up};9>M)C~-pj+K zTH8)uE_~!+=JO~(l8?znFnEfTfAXu`i}EW@uiW@y)}7N1bIrHOoP3gX@YGWV_O~9d zzloWD_L5z<`B-lElfJYW(z4Hr(<5SUr|4U}`;_^~@&gkWqf?mIlU>p||IJpW+*L1N zGMZF8t%qar>+jVwX2_iI+0h#HV-iQvThA$LIArVc=PgxOsO=J}MW~NwwW-wP1^n~NzFeEDHtYDByN`O>o=W|-KIHQ= z;=2Bi9Tj0W+m+Q+%uV=q+n)UJdq$+Cl+KHtpS`7i)OiNI@7ZECIcP@3$u(-*rl$qm zzIH5rtzVb@ze?fxf3h{YKXb1z6?+*yHPyP+ae3$Z?cbi3%a>hP!GEIFWWB7g?X4nv?^4Sc-f+YJw^Bt`U4EyM zc;c1Ht3`r!t}pT({chMw`7rPAeVJG+zvJ^8n``%~gnM0`a`{cRX1Qul7B8uOu6O9A zdz4mosx7+i7b=%#$&*t!fH&zoht7We=<;H5(cdtx3Ep^)E#M3M1e&^lG zSzT9EE;x1O>Kz4%y}RO-SKIcVYd5mqts{LqeB;%c#;dK&oNqD@%~SEve0}#4%La?W z6PKU-UGvC9bhV3|OyP-dD(9bfJQQ3k>!t5k@cW<0yL~%U^OA!aNN$A zV>65MA6{&BE}4Jt2!D9r%JY%dqElmBW%oxG?i5jyz5MiHXGVmQrt*8fYmIh^IP!zw=8 z{`}M}qA&l4Reaj~)32QPS*2_1E|fRxlnPq6ZeBYfaMSLuzdLhm_zORGyVl%}nlAtU z$@GfvcgsKAnrWQ(|4)bZH{VC=7n^tPDc4@=`|bPpj~^cH|N8Oze~~ZmA3nNNYzC)wmA!f6#(`(${H8DMr%&2{`r5^9%Y`>S|B&eP&u!kDt;;1p zZ#t*H=G3iQ`~`)%zMd*pQL+cE|H)mgQ+@RR>!oSSR+j9Jee>SDwEFwfoZOFdYOY+0 zTd%FQHR*BY%8*GfZ(8c;o0e?cs8Ia*^NKJnuihW~-~0V%wBwUGdMNm~9|HpegQu&X J%Q~loCIHo{?ri`7 literal 0 HcmV?d00001 diff --git a/doc/html/images/next.png b/doc/html/images/next.png new file mode 100755 index 0000000000000000000000000000000000000000..f3a1221df31c3c2ba4e3a72edad38c13703767b9 GIT binary patch literal 768 zcmeAS@N?(olHy`uVBq!ia0y~yU=Rjj4kiW$hQCG&XEQJ`a29w(7Bet#3xP1>rMq>1 z7#Nr~dAc};RLp6eeB1w40K>80^1pI=K031Q+}6PA-o zut+zF-j;Gw?uf*D*{((14$Hcux3in6E_!$R{mVIjisa6HXWSoM6uZ0c{E^r9Ur$om zdhZ^4hON-~BYZ2GeK$N>`J?GiOJzY(!s6V|uRrr03%sLkr*1#v(teTeT^zk4U9DU7 zv%f8b6P+XKjO)LDUiZ<0p*o>#X6mOi#R1wP z8(l6)T21PWa1OIO8vZ)ea}qY-^=ZrWvbZQ6m)_kQvcrVw=bvte)59DYyUFcC9E$Tt4>&6 z+W%-jd;GDDoIH;dN(0uWOyTmnDE=b*gwcE+xwelYeE}Q`Hm&Y3XPNlB+x+oXzleq5 z0w#UgMVr)jUI2-(`lA6OUY& zu=Q|M1xs0v^{>u8Av+EoyuB{di7k}!tvm{Q)|ESyVT{*EHLXF20N@PNRO*vTc;nVG>kH2j-tEeVx#8P4@BjRN>Ropm;oHA%y^x5t(%-w` ajXhtHa_t{xfsG6d3=E#GelF{r5}E)mona0D literal 0 HcmV?d00001 diff --git a/doc/html/images/note.png b/doc/html/images/note.png new file mode 100755 index 0000000000000000000000000000000000000000..c3bebc7ea6aae0fd9b713ef8ab3cefc31751a03a GIT binary patch literal 4648 zcmeAS@N?(olHy`uVBq!ia0y~yV2}f04mJh`25Wk44otVv!`vx;GaF%2` zI|pPYCo?cq+iGS4^JFAuNVf4f%QU%gGJBl!RACQnlr-uwP+|2s@rY}U zg3=@rM;Au%nAoN@i)u_i-MQ;$eZ}u^fBR7X z_U)_cLwOtCR4A!yikdMfbWT6^y>w$bTYHPq#>EWW0S#PB8oXH4O>dq)e^Z`g^Cj+o zs_)$xw-oJJ{`>v;|HlP(dfMnQ2>6}&cxOdO--OF8GN*kXt-EqO+`?ElGNM_w)#o|4 ze!z)?+A=?Tg~KhLNx%Pd>+$>73Qvp}3YN@R?_;s+(8TzeRavc;8~>;RLJ@J^KWEz9Q-zk&No&OQ$yjCZ}fkDK9-N-?3 z1(WXr?w$t84J_LZaPDBvf57i_!0iCzMg`6fj%p_ucRSc=u&6#zSi!V)0i#J{SOHr} z)8_|9JJ|9XcPFseurV31#x+%b;L~vwXlXqmz&ojNibAOeyHV4P38qh2DxLNPaES07 zb+FNpJ=Iv|+!~-6!g|%w_k#Wf%NIr^%u-EqPQn*-zL1s<_R1!E%BRqtmtJ%vj*IjhsssQys*%fwIY_G6n z$$e$@bvwPd^nzH1d5M7)+uY7`?$Z}bUwr#w^$Wo-BEMwWniCTuB#e8s)mVi4PaYFV z6eM50-!MX5nP&PH_F8enhxTP>W-2 z%j%ZGL()nUS2&rd{}OoIVcjWurp`3r$_(TcprB@sj6n4|R{}9{is9CsH=C z-JB-l<){2!*?i*q3G*l2@4k5C%aJ=rb|hIJS#{LvNZZl4zz-s&U9zdls@*|;mfky^ zX9^$h&hD`8aPP<$UoU2_Zl|_S!Ev&|ln>K9CTUE{n6^XF(D`VP=?cFPJ=6ZGo~l+W zPv?wPChSt}+h$*L*zGlYQSu9&UDCGm;ynJ(wDXuheTkQpH=9@9#5L3QC}<`q@bI=t zD^CnOV{up_wPs4tgiVvXCf(A$s%5IPRYO-jS6fy!R^hIitlNC0{FAILw zspAzEea+o0_*=)D(3_T)yXGvFabM@~uIG+&Wkg)`y>Pqee>46x{Ap@h)YR>?$!X~! z(N;^>wnb}`_9V?r>VLFG$oFKFrr%1Rmy0fOFH^bPH}k}rgl~q=r#_t;JN5F^*HhT1 zP7jIDV$|BHm8<0+!nrEvYQ|Ngt8rH=O;t_xx5{i4+v@(RqI6r;nqP`v>%O}3PIH@Z zOs?0jS8|%k>E5YFvl4r=CzaFsU1li!Z z7IP0k_om$~}onwhgAcSQEyl$d=k?zmo3yt(`A+q2&r*ysN{c<74K*+)G`_yj1*38@zw6SZ$s?9TmT)%vGv z-+p1cmv@hS&-^vXYrP}C&*ndtKG%Qi`Qmuz`!e_I>}TCq+n=_-{NJ~KNB{LRn=oHu zu42|~Ol~`#PTcBwRlr?@s#4Sr#?BGZ-;G{y(PDEZ+ZKx zzCE(R*0E*t?zrBVy5V)%I>)@scen34?%w@b3=%!mVBW7 zvA-5O%D>(_wKtw?2dgDT3yWW4NER(x3VVpYg$ot1w=M59fEa^vrY zDaUW#p7zn;`-cyLx0Tm!<=Wc1Rlfh2Y;C~vpzDF_1LNy>igg~}_}q4&?cd`!k9~VL z^|toT_y6F>;rDCan{1=(tgLDIdU=h}m!i}BTj%cjz4`I^*tNUXmge?sJ9PO$$*-5< z`&<4SRULcm^FH$1&1>;j>(^#3-zr|>ARBG{%sSbcHC8d!`T3pmU(2G)w*O!D{dVW) zQ_olHd&FtHQ~dJet4{oxT{{Xie_p!tbjIn)duLb4$8+v0+JAm|{)bh^ufD!MXMOC; z?XUM&+Hh9}C-zu=y!Ipa{h?j0%imABr>iTr zXL@D*C+6SI|Bo-|zwAA8{)YKlcG

{yqAbT4R}68To`sNnBuO!wFUwJ%u91iQFAA z4(LLEUpNJL3u zX-P(Y5vU3F*;nVJk4{*DpN_{_PhHKE>He{kMlDyaF}_zIEHu}FAdMkmpLw2 zYkK_L8%MqA$3IQTi0XRsqCv%Z!<-|HB1bwN=C=tw@%|T5=VHgkF@eS7(Si9%tc5Jz z6Pb>0(LJ@urE9s%yMwmR-tBoeGj^>^%93Ya3aWOkx>p?bR_4iV)_xxiq$DKI?ns`b zc{A6&;#!}fh=a%1#LUF}dyN z%!Y@ii`5Ua{J+V+LHyQ?)!~I@r`VbeHyk;ke06nf-iyla0UIclG86^Uu%YE6ncQKmTLKol~*T z|6V!`>@NlTN_yd zl@gDbJmN@JP0#jPXQpsHP4W5iDN8E5KE|FZUHPU|xUyn`)Ls2+IhGPyk@qDpv`KN_ zlyt2&>iM|-t)0wy_q)P1pN$Sq4m%aIA;GYy+ko?Z=CSm@{zd0b*u5}$A+SZjB-ZNJ z+<=4USj3;@R_tqT-(9=M@O|=02R`PlmySNT`7q$^+?0seO;;37ZTP6%TDGqO0XHgH6P6o2B}4);WjzbySwLl^zoK^4L^<`}wDu zpN_k0{@W(`Y3|3)``XVk(q1H|CGDR3u;y@+FU!1gp)J*ht5T(&ZRTm)C{yaJdDXi^ z;%}inlP3FCB_6h2E~^f4o)?Q;GmY2iRzdSi;g*RlE6aQ`4{msoZpBde!bM54%9-8F zpDD~d^ShGH+0Y{wH+(tF;(q4-QcXRs;4Lpgtpk#irP2;>owqq8&GVDi_sb%lb0++@ zS!!}U^58~2J-f_T1^Kf->n(mM5Sx4X;;fG3rB#lrB8nw7`B|!tc4bb9(YV!d+Ge#( zQRp12TLCi56#}H9f*Fj9R&$l|Yi`%;%~bEu3DUcAx@U)vNX#9zBVAV&7gtP*;MOwM zH1SjSRl2O{eW|nK>#ZvpPSU0smow71ywWcD?!Nizc*kN3{kdM(v(8FCefRn00#ldF ztxVI`91Dz+*s8W*S;LmZL(y|Cux(R#vdrz~TO5h%RxMHCcEJvAS<4D9e*d|P zyZ!j%y6gtk^OLH2Zzeoi@O0Jl2R6pGQY<%Y-aP#6+doHSQKy@-9KYW>~>pJZbaq0#d>pAX|4<8H@}^=@Y#ys;J!tPM|nS0 z&$%x=X?=;t(L%4j2C4UPtr~vdzmI` zZxwy~V7IW%t(T9kEwwyz!TN2jh2Y5vD?c7B<3E2hGiUO4_cdgW_$DJ#uX1QdCgu~xuY_Zk$?NHAHRQb-P+wQjz-zVqxwMV(Z)I0;nQV*ts!Xxc`-k4Yf0xvF-hTHbm(7k3cUAhY zR5lY=oM60s*;8@zuqCU4e*U;uymG_(pHKP2Q`SE85;}gU<4nS>lY7th)%;s>)=R|e z$SKj*jRJx*SKs<{@$0fR8)bi9{u}#p8~dk=TPt^daEr})qqSzDE7#NYUp}c@EoTl} zyH~vS>&d^ef1aH)a}wLjzfM0nci}2IyVno?rLniGmnej9(3+*OLuc`4Q|a)q*RPK4 zWV6~UF#k_={I9!;dGYaK_VxLq+1jSpGIDQRY3>XDawsihop@Sp>E}<2>{345K411> zx3z!a&$Dg2N(<%8&t2Jgy?4WD=OwlszVD;8tt0ZL6z+Pbn8dl~_gBStwsyyOy1%Zk z+tBp=eq7jcvDF&C^?3Vs+x=bpYlg7!#+P$fM8w|u7WeJr)5+8RJUwXlZqv(4PfJ>5 z_HK-sd~~MKDb>Be ztk+A*m43F0Rtj4eWuwvhgDFjR{X{Aex82ms+k$zbJcbn|CXM(P3H;g*_}pu`y!7&{3yWw)}hZ& zX<0zhixnGwoVgYgIp^z5&tGp2)|xD{4dLi~{p@S4$-jJO`1tMO_}k&NpNnc#Nc uqerwuqg^+zYt_2{^P6@3mfoXZ;{*5dChuIwP|v`?z~JfX=d#Wzp$P!oJ@O|2 literal 0 HcmV?d00001 diff --git a/doc/html/images/prev.png b/doc/html/images/prev.png new file mode 100755 index 0000000000000000000000000000000000000000..f7f036150f816cbbd5abb1adc8b0b3a23cb18884 GIT binary patch literal 741 zcmeAS@N?(olHy`uVBq!ia0y~yU=Rjj4kiW$hQCG&XEQJ`a29w(7Bet#3xP1>rMq>1 z7#NtQd%8G=RLtp}eB1w4fK0=0`CmCb9}jX&i{|bS;8JZU(rk@m$+@m&*6<)z@HwyJ zLBqu}Z%$LK7D(P>EYqc@HB&Dyz50OU9-qHYtF3<)O)B0e|K<5fMusbOSCWJ`ZtmV( z?SA2M)XNP=j_wrOvh>T^FG0c#0e7^lB950N-a2-pjIV5-IU~dL@adCpdRAZ9_a#*` z{!B7Y*d48=`p-K!8CJ{-`^oZt`k$BQGc!ZI>O5v;Tz+xp#l7o$FFkbJ8MH1$`?&h? z3$bs%KYO=q^?g$dQ;Uyh&b<`7lXvi~plwP^$w$2x-&VbjzrJ&- z%)R#hz0%$L``hog-LyIVEOOle*YHJ`HeK;h5pH~StMYA(2iLU;rjt4iGTY`Tzhs?t zcH{r%+0PXi4xBq^rYPVtMZw*JcWt9)#Ods_fyMc&rk@J>qV#vdg&2;gzgv=)ojH?z z%qU^v?~<GESXNgP1H(Vx*XJ);U?7_^S|hIc3Yfca{P?#O1blEjvK!&?6Z15 zm7&ag_qPdqXTLv|G{f&oChJ<&M8i(Ct^R9yGfElf&buW2yNB)62aj6y`~FQE7aUr? zfhU^BnN6p0>&;vLu7+#LPu0G9>f_6gkB`Rx-Q$%Syn%b0ip~#CYoGmB{M1&%dzJIVTo@P_7(8A5T-G@yGywp< C*k44otVv!`vx;GaF%2` zI|pPYCo?cq+iGS4^JFAuNVf4f%QU%gGJBl!RACQnlr-uwP+|2s@rY}U zg3=@rM;Au%nAoN@i)u_i-MQ;$eZ}u^fBR7X z_U)_cLwOtCR4A!yikdMfbWT6^y>w$bTYHPq#>EWW0S#PB8oXH4O>dq)e^Z`g^Cj+o zs_)$xw-oJJ{`>v;|HlP(dfMnQ2>6}&cxOdO--OF8GN*kXt-EqO+`?ElGNM_w)#o|4 ze!z)?+A=?Tg~KhLNx%Pd>+$>73Qvp}3YN@R?_;s+(8TzeRavc;8~>;RLJ@J^KWEz9Q-zk&No&OQ$yjCZ}fkDK9-N-?3 z1(WXr?w$t84J_LZaPDBvf57i_!0iCzMg`6fj%p_ucRSc=u&6#zSi!V)0i#J{SOHr} z)8_|9JJ|9XcPFseurV31#x+%b;L~vwXlXqmz&ojNibAOeyHV4P38qh2DxLNPaES07 zb+FNpJ=Iv|+!~-6!g|%w_k#Wf%NIr^%u-EqPQn*-zL1s<_R1!E%BRqtmtJ%vj*IjhsssQys*%fwIY_G6n z$$e$@bvwPd^nzH1d5M7)+uY7`?$Z}bUwr#w^$Wo-BEMwWniCTuB#e8s)mVi4PaYFV z6eM50-!MX5nP&PH_F8enhxTP>W-2 z%j%ZGL()nUS2&rd{}OoIVcjWurp`3r$_(TcprB@sj6n4|R{}9{is9CsH=C z-JB-l<){2!*?i*q3G*l2@4k5C%aJ=rb|hIJS#{LvNZZl4zz-s&U9zdls@*|;mfky^ zX9^$h&hD`8aPP<$UoU2_Zl|_S!Ev&|ln>K9CTUE{n6^XF(D`VP=?cFPJ=6ZGo~l+W zPv?wPChSt}+h$*L*zGlYQSu9&UDCGm;ynJ(wDXuheTkQpH=9@9#5L3QC}<`q@bI=t zD^CnOV{up_wPs4tgiVvXCf(A$s%5IPRYO-jS6fy!R^hIitlNC0{FAILw zspAzEea+o0_*=)D(3_T)yXGvFabM@~uIG+&Wkg)`y>Pqee>46x{Ap@h)YR>?$!X~! z(N;^>wnb}`_9V?r>VLFG$oFKFrr%1Rmy0fOFH^bPH}k}rgl~q=r#_t;JN5F^*HhT1 zP7jIDV$|BHm8<0+!nrEvYQ|Ngt8rH=O;t_xx5{i4+v@(RqI6r;nqP`v>%O}3PIH@Z zOs?0jS8|%k>E5YFvl4r=CzaFsU1li!Z z7IP0k_om$~}onwhgAcSQEyl$d=k?zmo3yt(`A+q2&r*ysN{c<74K*+)G`_yj1*38@zw6SZ$s?9TmT)%vGv z-+p1cmv@hS&-^vXYrP}C&*ndtKG%Qi`Qmuz`!e_I>}TCq+n=_-{NJ~KNB{LRn=oHu zu42|~Ol~`#PTcBwRlr?@s#4Sr#?BGZ-;G{y(PDEZ+ZKx zzCE(R*0E*t?zrBVy5V)%I>)@scen34?%w@b3=%!mVBW7 zvA-5O%D>(_wKtw?2dgDT3yWW4NER(x3VVpYg$ot1w=M59fEa^vrY zDaUW#p7zn;`-cyLx0Tm!<=Wc1Rlfh2Y;C~vpzDF_1LNy>igg~}_}q4&?cd`!k9~VL z^|toT_y6F>;rDCan{1=(tgLDIdU=h}m!i}BTj%cjz4`I^*tNUXmge?sJ9PO$$*-5< z`&<4SRULcm^FH$1&1>;j>(^#3-zr|>ARBG{%sSbcHC8d!`T3pmU(2G)w*O!D{dVW) zQ_olHd&FtHQ~dJet4{oxT{{Xie_p!tbjIn)duLb4$8+v0+JAm|{)bh^ufD!MXMOC; z?XUM&+Hh9}C-zu=y!Ipa{h?j0%imABr>iTr zXL@D*C+6SI|Bo-|zwAA8{)YKlcG

{yqAbT4R}68To`sNnBuO!wFUwJ%u91iQFAA z4(LLEUpNJL3u zX-P(Y5vU3F*;nVJk4{*DpN_{_PhHKE>He{kMlDyu=;qqIEHu}-x?O3FC8lI z@7bKMw>D1R!FRS*W!bCVdkle&uAzz{itqTRI!v8V@rd^yOGo{|{SQPr6<00dit609 zN-N{?GS8_k$1>*}>CNAL@3cYn#?76v$7>&`Y_8t3J3Z~(neS&Mvo?NKZZLP5!qFX2 z!(aFNV}60jiI2HCmZEtTVyPu;$t!JqrY3f=30ZA$_pfGo|Eevp)E+mJT(-%pVo3j$0unviQ}N zli%JP=w-<`WYE5Vd*8+^-*aikOQ!Y-UHR8%_27_Pfu^$CocRVf_Bl`dl-{P6VPeX3 zdfSY}0>`Zv2CUtioA~jY&Hs=U7bCWH%sj-?Kabs@N1shDS`hW&j#KLDrb`); z*_*MV@y&Z@9p6{`k%f#6h)a9e>9NfD2%e|NUFHal^ z2~pUppm|Rym;$X*ZmG6Y_gA*>mP`Vtnd2ybn1#} zY!8Dca)k#iRBaHxEG!`_=X%V4@x2v?%Ccf(xZL99zCTb|<;y6 zvhQ<^P52S^_3=lXcCt)8e{e!HZyvfeSxD`x#=gIQq|fXN5s_J8D}7J> z_&)VBTXOQGMHO0&FQ0fc*<8Q)Y~G{k)!_w?kCk?|rv1=6=G*)Dr;>l=;c}b?KB1mm`l{Oo-0<@#t3Vny_mRDop)6m(G&W zeUPAc{`$IqUPqmm7k>QfJ;%uSkfqcb!G!p8s^{;2G!|T0#(HYTVT;fj?-pxSyA><; zJ$P`(viH)h*od=SLC>B%SSYq{)AOHi4N7HOtcg;K>V49^U>kskX)! zB5jwS?>&DpUGBHDqCoSV3}xl5M>(Vy#+3y94Y=!gZNX99e|7~9(to=jebyHLx-Q1{ zS?qhI!z;@;rS>pSbZ!hS;GEqTyEbe6&vo}5=WLl`9yBEto(`(>tF_CQWW{D{`JPaYN|_K{dUgtfF0uEzhM}t6EQH psb#a8d#Lo`e!guT|C9f)E5E#+x?G@Khk=2C!PC{xWt~$(696HeggpQN literal 0 HcmV?d00001 diff --git a/doc/html/images/up.png b/doc/html/images/up.png new file mode 100755 index 0000000000000000000000000000000000000000..ef434074cab1625251ba558c14e5bf47c5add70b GIT binary patch literal 766 zcmeAS@N?(olHy`uVBq!ia0y~yU=Rjj4kiW$hQCG&XEQJ`a29w(7Bet#3xP1>rMq>1 z7#Nr~c)B=-RLp6;bl3k@f(YA(e{|{j<+dCaBWI8i{UJGmx+J6bk>#`QET?BKe36&H*(nnSBa;ApSy0(ER7Nl zYjK~DdPMD3MyK4#Cy_?w)4JauzrJMaoGHfVq|e*WcV=C=Vc&MWXGed2*wbhhAslAX z7UinF)0wTSaiWO7tC8C-rFCD@tmMPc4`y z%U|lDdFu7GtxYm~?Q8wGlMTW1?_|wC`1<}Q_HE2> z^iIDmzSz7XK*VES&i%h3)A;-OuW+R<)KS~csg`gxduo+mZiGRCh}r2gmkfVB{P?~2 br+99$L2LK4shb%X7#KWV{an^LB{Ts5mN;Xz literal 0 HcmV?d00001 diff --git a/doc/html/images/warning.png b/doc/html/images/warning.png new file mode 100755 index 0000000000000000000000000000000000000000..51a30f751179811a3367891c0e54b1dea7afd3ac GIT binary patch literal 3927 zcmeAS@N?(olHy`uVBq!ia0y~yV2}f04mJh`25Wk44otVv!`vx;GaF%2` zI|pPYCo?cq+iGS4^JFAuNVf4f%QU%gGJBl!RACQnlr-uwP+|2s@rY}U zg3=@rM;Au%nAoN@i)u_i-MQ;$eZ}u^fBR7X z_U)_cLwOtCR4A!yikdMfbWT6^y>w$bTYHPq#>EWW0S#PB8oXH4O>dq)e^Z`g^Cj+o zs_)$xw-oJJ{`>v;|HlP(dfMnQ2>6}&cxOdO--OF8GN*kXt-EqO+`?ElGNM_w)#o|4 ze!z)?+A=?Tg~KhLNx%Pd>+$>73Qvp}3YN@R?_;s+(8TzeRavc;8~>;RLJ@J^KWEz9Q-zk&No&OQ$yjCZ}fkDK9-N-?3 z1(WXr?w$t84J_LZaPDBvf57i_!0iCzMg`6fj%p_ucRSc=u&6#zSi!V)0i#J{SOHr} z)8_|9JJ|9XcPFseurV31#x+%b;L~vwXlXqmz&ojNibAOeyHV4P38qh2DxLNPaES07 zb+FNpJ=Iv|+!~-6!g|%w_k#Wf%NIr^%u-EqPQn*-zL1s<_R1!E%BRqtmtJ%vj*IjhsssQys*%fwIY_G6n z$$e$@bvwPd^nzH1d5M7)+uY7`?$Z}bUwr#w^$Wo-BEMwWniCTuB#e8s)mVi4PaYFV z6eM50-!MX5nP&PH_F8enhxTP>W-2 z%j%ZGL()nUS2&rd{}OoIVcjWurp`3r$_(TcprB@sj6n4|R{}9{is9CsH=C z-JB-l<){2!*?i*q3G*l2@4k5C%aJ=rb|hIJS#{LvNZZl4zz-s&U9zdls@*|;mfky^ zX9^$h&hD`8aPP<$UoU2_Zl|_S!Ev&|ln>K9CTUE{n6^XF(D`VP=?cFPJ=6ZGo~l+W zPv?wPChSt}+h$*L*zGlYQSu9&UDCGm;ynJ(wDXuheTkQpH=9@9#5L3QC}<`q@bI=t zD^CnOV{up_wPs4tgiVvXCf(A$s%5IPRYO-jS6fy!R^hIitlNC0{FAILw zspAzEea+o0_*=)D(3_T)yXGvFabM@~uIG+&Wkg)`y>Pqee>46x{Ap@h)YR>?$!X~! z(N;^>wnb}`_9V?r>VLFG$oFKFrr%1Rmy0fOFH^bPH}k}rgl~q=r#_t;JN5F^*HhT1 zP7jIDV$|BHm8<0+!nrEvYQ|Ngt8rH=O;t_xx5{i4+v@(RqI6r;nqP`v>%O}3PIH@Z zOs?0jS8|%k>E5YFvl4r=CzaFsU1li!Z z7IP0k_om$~}onwhgAcSQEyl$d=k?zmo3yt(`A+q2&r*ysN{c<74K*+)G`_yj1*38@zw6SZ$s?9TmT)%vGv z-+p1cmv@hS&-^vXYrP}C&*ndtKG%Qi`Qmuz`!e_I>}TCq+n=_-{NJ~KNB{LRn=oHu zu42|~Ol~`#PTcBwRlr?@s#4Sr#?BGZ-;G{y(PDEZ+ZKx zzCE(R*0E*t?zrBVy5V)%I>)@scen34?%w@b3=%!mVBW7 zvA-5O%D>(_wKtw?2dgDT3yWW4NER(x3VVpYg$ot1w=M59fEa^vrY zDaUW#p7zn;`-cyLx0Tm!<=Wc1Rlfh2Y;C~vpzDF_1LNy>igg~}_}q4&?cd`!k9~VL z^|toT_y6F>;rDCan{1=(tgLDIdU=h}m!i}BTj%cjz4`I^*tNUXmge?sJ9PO$$*-5< z`&<4SRULcm^FH$1&1>;j>(^#3-zr|>ARBG{%sSbcHC8d!`T3pmU(2G)w*O!D{dVW) zQ_olHd&FtHQ~dJet4{oxT{{Xie_p!tbjIn)duLb4$8+v0+JAm|{)bh^ufD!MXMOC; z?XUM&+Hh9}C-zu=y!Ipa{h?j0%imABr>iTr zXL@D*C+6SI|Bo-|zwAA8{)YKlcG

{yqAbT4R}68To`sNnBuO!wFUwJ%u91iQFAA z4(LLEUpNJL3u zX-P(Y5vU3F*;nVJk4{*DpN_{_PhHKE>He{kMlDyu%>#tIEHu}-y0sCFYPMw z@7%jv(zkb?JNjkOl2@v}mnUsuU3iF@Kg7f1ODlU^g_F~xUi-uG4e|&0HH3n^SBYKf zT43he;I=TcxL^4A$zR*pI802`JK7IY&rz3~7 zdGfgB86VtL>SbQJ*d&f+4u8X+P_HE!(N>pIZM|D>O%}R(?%8Kg)9@Y6-xc>>7cmlF z@T%Uh&|KncWk;>kR?aPJ?H-3N3N73#npwqg;=+W9tp(TKKT*G58fGQo_FS`XK~}x; zy7P{f?#2TgP@zQBToLwwn9SmAkvz_MiQ(q+;G>apO{vS8Kalt;UWo z_u527^Y6EME}kS5vP#v*=gjJzJB|G2y*V~jo4H`qUxUxnx6YX;-L{1Lzif=IgQ;Ln zk8&5U#Jk8(r)JF7e)RCL>6&$6hL$^fT7N2Sou06(xkHKh;WOL4?@|NhCuOy+*vB!y zjrY6K;@k9nn8~W2h+KQE`cs}PSI0d3o5^TReJK5i@){XV~v_=ku0~3Ikx?4 zh~2?+c-2Pj)+G{t=PofU3S4H^@;GAG8kbj7qTP2H^enJBy45(!fAQI z>HnUI9QtLn>z_YPj zt9G}{px4$SF`iL}ezEOomG&r~-#6`Y&AC)6Ms%Xs?o-wbg!Kt6${PGj? zAc>2OEm|8cxh}bzSMk|Cv$jy?z4y=V2SF3BnAeGmhN?tc9NT0f1C?=i za$@h<&7U4~ZOX-maxc$CPEp)3Z{m@K245$=-1;+aQq)KDcL6)j_kB&;@_L1C@4=Vy zO`Z-5cOJ;_T(#};XC2YxCo$%3ZPkUDOZc~WatNgSc0cfSbwS^kgV8$=UWs=)C3)lJ ztYgIqF9l7ne0wybY2lQ&H@uoMRnJORJ>Ixrv8)ltnum_zwZA@cmVT`1HwxYJzS?P0 zz?+qN+fP=l(#n5n_VxFzGy4ySE)JaMTKX}4hdYB^XH z)80}%XMe9sQeyclx9=;nBj)|%+q7X}Z&{V^+aHT&NKCikQocSRN#4J2t-NRW;|+sTQSQJ0kN;+$zDxJQ84oit1_lNO MPgg&ebxsLQ0L+(v)Bpeg literal 0 HcmV?d00001 diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 00000000..ed7418ae --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,983 @@ + + + +Chapter 1. Boost.Config + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+

+
Next
+
+
+

+Chapter 1. Boost.Config

+

+Vesa Karvonen, John Maddock Beman Dawes +

+

Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock

+
+

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+

Table of Contents

+
+
Configuring + Boost for Your Platform
+
+
Using + the default boost configuration
+
The + <boost/config.hpp> header
+
Using + the configure script
+
User + settable options
+
Advanced + configuration usage
+
Testing + the boost configuration
+
+
Boost Macro Reference
+
+
Macros + that describe defects
+
Macros + that describe optional features
+
Macros + that describe C++0x features
+
Boost + Helper Macros
+
Boost + Informational Macros
+
Macros + for libraries with separate source code
+
+
Guidelines for + Boost Authors
+
+
Adding + New Defect Macros
+
Adding + New Feature Test Macros
+
Modifying + the Boost Configuration Headers
+
+
Rationale
+
+
The problem
+
The solution
+
+
Acknowledgements
+
+
+
+
+
+
Using + the default boost configuration
+
The + <boost/config.hpp> header
+
Using + the configure script
+
User + settable options
+
Advanced + configuration usage
+
Testing + the boost configuration
+
+
+
+

+ Boost comes already configured for most common compilers and platforms; you + should be able to use boost "as is". Since the compiler is configured + separately from the standard library, the default configuration should work + even if you replace the compiler's standard library with a third-party standard + library (like STLport). +

+

+ Using boost "as is" without trying to reconfigure is the recommended + method for using boost. You can, however, run the configure script if you + want to, and there are regression tests provided that allow you to test the + current boost configuration with your particular compiler setup. +

+

+ Boost library users can request support for additional compilers or platforms + by visiting our Tracker + and submitting a support request. +

+
+
+
+

+ Boost library implementations access configuration macros via +

+
+#include <boost/config.hpp>
+
+

+ While Boost library users are not required to include that file directly, + or use those configuration macros, such use is acceptable. The configuration + macros are documented as to their purpose, usage, and limitations which makes + them usable by both Boost library and user code. +

+

+ Boost informational or helper + macros are designed for use by Boost users as well as for our own internal + use. Note however, that the feature test + and defect test macros were designed + for internal use by Boost libraries, not user code, so they can change at + any time (though no gratuitous changes are made to them). Boost library problems + resulting from changes to the configuration macros are caught by the Boost + regression tests, so the Boost libraries are updated to account for those + changes. By contrast, Boost library user code can be adversely affected by + changes to the macros without warning. The best way to keep abreast of changes + to the macros used in user code is to monitor the discussions on the Boost + developers list. +

+
+

+

+
+
+
+ + + + + +
[Note]Note
+

+

+

+ This configure script only sets up the Boost headers for use with a particular + compiler. It has no effect on Boost.Build, or how the libraries are built. +

+

+

+
+

+ If you know that boost is incorrectly configured for your particular setup, + and you are on a UNIX like platform, then you may want to try and improve + things by running the boost configure script. From a shell command prompt + you will need to cd into <boost-root>/libs/config/ + and type: +

+
+

+

+

+ sh ./configure +

+

+

+
+

+ you will see a list of the items being checked as the script works its way + through the regression tests. Note that the configure script only really + auto-detects your compiler if it's called g++, c++ or CC. If you are using + some other compiler you will need to set one or more of the following environment + variables: +

+
++++ + + + + + + + + + + + + + + + + + + + + + + +
+

+ Variable +

+ 		+

+ Description +

+
+

+ CXX +

+ 		+

+ The name of the compiler, for example c++. +

+
+

+ CXXFLAGS +

+ 		+

+ The compiler flags to use, for example -O2. +

+
+

+ LDFLAGS +

+ 		+

+ The linker flags to use, for example -L/mypath. +

+
+

+ LIBS +

+ 		+

+ Any libraries to link in, for example -lpthread. +

+
+

+ For example to run the configure script with HP aCC, you might use something + like: +

+
+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
+
+

+ However you run the configure script, when it finishes you will find a new + header -user.hpp- located in the <boost-root>/libs/config/ + directory. Note that configure does not install this + header into your boost include path by default. This header contains + all the options generated by the configure script, plus a header-section + that contains the user settable options from the default version of <boost/config/user.hpp> + (located under <boost-root>/boost/config/). + There are two ways you can use this header: +

+
    +
  • +Option 1: copy the header into <boost-root>/boost/config/ so that it replaces the default user.hpp + provided by boost. This option allows only one configure-generated setup; + boost developers should avoid this option, as it incurs the danger of accidentally + committing a configure-modified <boost/config/user.hpp> + to the cvs repository (something you will not be thanked for!). +
    • +
  • +Option 2: give the header a more memorable + name, and place it somewhere convenient; then, define the macro BOOST_USER_CONFIG to point to it. For + example create a new sub-directory <boost-root>/boost/config/user/, and copy the header there; for example + as multithread-gcc-config.hpp. Then, when compiling add the command + line option: -DBOOST_USER_CONFIG="<boost/config/user/multithread-gcc-config.hpp>", + and boost will use the new configuration header. This option allows you + to generate more than one configuration header, and to keep them separate + from the boost source - so that updates to the source do not interfere + with your configuration. +
    • +
+
+

+

+
+
+

+ There are some configuration-options that represent user choices, rather + than compiler defects or platform specific options. These are listed in + <boost/config/user.hpp> + and at the start of a configure-generated user.hpp header. + You can define these on the command line, or by editing <boost/config/user.hpp>, they are listed in the following table: +

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Macro +

+ 		+

+ Description +

+
+

+ BOOST_USER_CONFIG +

+ 		+

+ When defined, it should point to the name of the user configuration + file to include prior to any boost configuration files. When not + defined, defaults to <boost/config/user.hpp>. +

+
+

+ BOOST_COMPILER_CONFIG +

+ 		+

+ When defined, it should point to the name of the compiler configuration + file to use. Defining this cuts out the compiler selection logic, + and eliminates the dependency on the header containing that logic. + For example if you are using gcc, then you could define BOOST_COMPILER_CONFIG + to <boost/config/compiler/gcc.hpp>. +

+
+

+ BOOST_STDLIB_CONFIG +

+ 		+

+ When defined, it should point to the name of the standard library + configuration file to use. Defining this cuts out the standard library + selection logic, and eliminates the dependency on the header containing + that logic. For example if you are using STLport, then you could + define BOOST_STDLIB_CONFIG + to <boost/config/stdlib/stlport.hpp>. +

+
+

+ BOOST_PLATFORM_CONFIG +

+ 		+

+ When defined, it should point to the name of the platform configuration + file to use. Defining this cuts out the platform selection logic, + and eliminates the dependency on the header containing that logic. + For example if you are compiling on linux, then you could define + BOOST_PLATFORM_CONFIG + to <boost/config/platform/linux.hpp>. +

+
+

+ BOOST_NO_COMPILER_CONFIG +

+ 		+

+ When defined, no compiler configuration file is selected or included, + define when the compiler is fully conformant with the standard, or + where the user header (see BOOST_USER_CONFIG), + has had any options necessary added to it, for example by an autoconf + generated configure script. +

+
+

+ BOOST_NO_STDLIB_CONFIG +

+ 		+

+ When defined, no standard library configuration file is selected + or included, define when the standard library is fully conformant + with the standard, or where the user header (see BOOST_USER_CONFIG), + has had any options necessary added to it, for example by an autoconf + generated configure script. +

+
+

+ BOOST_NO_PLATFORM_CONFIG +

+ 		+

+ When defined, no platform configuration file is selected or included, + define when the platform is fully conformant with the standard (and + has no useful extra features), or where the user header (see BOOST_USER_CONFIG), has had any + options necessary added to it, for example by an autoconf generated + configure script. +

+
+

+ BOOST_NO_CONFIG +

+ 		+

+ Equivalent to defining all of BOOST_NO_COMPILER_CONFIG, + BOOST_NO_STDLIB_CONFIG + and BOOST_NO_PLATFORM_CONFIG. +

+
+

+ BOOST_STRICT_CONFIG +

+ 		+

+ The normal behavior for compiler versions that are newer than the + last known version, is to assume that they have all the same defects + as the last known version. By setting this define, then compiler + versions that are newer than the last known version are assumed to + be fully conforming with the standard. This is probably most useful + for boost developers or testers, and for those who want to use boost + to test beta compiler versions. +

+
+

+ BOOST_ASSERT_CONFIG +

+ 		+

+ When this flag is set, if the config finds anything unknown, then + it will stop with a #error rather than continue. Boost regression + testers should set this define, as should anyone who wants to quickly + check whether boost is supported on their platform. +

+
+

+ BOOST_DISABLE_THREADS +

+ 		+

+ When defined, disables threading support, even if the compiler in + its current translation mode supports multiple threads. +

+
+

+ BOOST_DISABLE_WIN32 +

+ 		+

+ When defined, disables the use of Win32 specific API's, even when + these are available. Also has the effect of setting BOOST_DISABLE_THREADS unless BOOST_HAS_PTHREADS is set. This + option may be set automatically by the config system when it detects + that the compiler is in "strict mode". +

+
+

+ BOOST_DISABLE_ABI_HEADERS +

+ 		+

+ Stops boost headers from including any prefix/suffix headers that + normally control things like struct packing and alignment. +

+
+

+ BOOST_ABI_PREFIX +

+ 		+

+ A prefix header to include in place of whatever boost.config would + normally select, any replacement should set up struct packing and + alignment options as required. +

+
+

+ BOOST_ABI_SUFFIX +

+ 		+

+ A suffix header to include in place of whatever boost.config would + normally select, any replacement should undo the effects of the prefix + header. +

+
+

+ BOOST_ALL_DYN_LINK +

+ 		+

+ Forces all libraries that have separate source, to be linked as dll's + rather than static libraries on Microsoft Windows (this macro is + used to turn on __declspec(dllimport) modifiers, so that the compiler + knows which symbols to look for in a dll rather than in a static + library). Note that there may be some libraries that can only be + statically linked (Boost.Test for example) and others which may only + be dynamically linked (Boost.Threads for example), in these cases + this macro has no effect. +

+
+

+ BOOST_WHATEVER_DYN_LINK +

+ 		+

+ Forces library "whatever" to be linked as a dll rather + than a static library on Microsoft Windows: replace the WHATEVER + part of the macro name with the name of the library that you want + to dynamically link to, for example use BOOST_DATE_TIME_DYN_LINK + or BOOST_REGEX_DYN_LINK + etc (this macro is used to turn on __declspec(dllimport) modifiers, so that the compiler + knows which symbols to look for in a dll rather than in a static + library). Note that there may be some libraries that can only be + statically linked (Boost.Test for example) and others which may only + be dynamically linked (Boost.Threads for example), in these cases + this macro is unsupported. +

+
+

+ BOOST_ALL_NO_LIB +

+ 		+

+ Tells the config system not to automatically select which libraries + to link against. Normally if a compiler supports #pragma lib, then + the correct library build variant will be automatically selected + and linked against, simply by the act of including one of that library's + headers. This macro turns that feature off. +

+
+

+ BOOST_WHATEVER_NO_LIB +

+ 		+

+ Tells the config system not to automatically select which library + to link against for library "whatever", replace WHATEVER + in the macro name with the name of the library; for example BOOST_DATE_TIME_NO_LIB or BOOST_REGEX_NO_LIB. Normally if + a compiler supports #pragma + lib, then the correct library + build variant will be automatically selected and linked against, + simply by the act of including one of that library's headers. This + macro turns that feature off. +

+
+

+ BOOST_LIB_DIAGNOSTIC +

+ 		+

+ Causes the auto-linking code to output diagnostic messages indicating + the name of the library that is selected for linking. +

+
+

+ BOOST_LIB_TOOLSET +

+ 		+

+ Overrides the name of the toolset part of the name of library being + linked to; note if defined this must be defined to a quoted string + literal, for example "abc". +

+
+
+
+
+
+
Example + 1, creating our own frozen configuration
+
Example + 2: skipping files that you don't need
+
Example + 3: using configure script to freeze the boost configuration
+
+

+ By setting various macros on the compiler command line or by editing <boost/config/user.hpp>, + the boost configuration setup can be optimised in a variety of ways. +

+

+ Boost's configuration is structured so that the user-configuration is included + first (defaulting to <boost/config/user.hpp> + if BOOST_USER_CONFIG is not + defined). This sets up any user-defined policies, and gives the user-configuration + a chance to influence what happens next. +

+

+ Next the compiler, standard library, and platform configuration files are + included. These are included via macros (BOOST_COMPILER_CONFIG + etc, see user settable macros), + and if the corresponding macro is undefined then a separate header that detects + which compiler/standard library/platform is in use is included in order to + set these. The config can be told to ignore these headers altogether if the + corresponding BOOST_NO_XXX + macro is set (for example BOOST_NO_COMPILER_CONFIG + to disable including any compiler configuration file - see + user settable macros). +

+

+ Finally the boost configuration header, includes <boost/config/suffix.hpp>; + this header contains any boiler plate configuration code - for example where + one boost macro being set implies that another must be set also. +

+

+ The following usage examples represent just a few of the possibilities: +

+
+
+

+ Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0. + Lets suppose also that we don't intend to update our compiler or standard + library any time soon. In order to avoid breaking dependencies when we + update boost, we may want to "freeze" our configuration headers, + so that we only have to rebuild our project if the boost code itself has + changed, and not because the boost config has been updated for more recent + versions of Visual C++ or STLport. We'll start by realising that the configuration + files in use are: <boost/config/compiler/visualc.hpp> for the compiler, <boost/config/stdlib/stlport.hpp> for the standard library, and + <boost/config/platform/win32.hpp> for the platform. Next we'll + create our own private configuration directory: boost/config/mysetup/, and copy the configuration files into + there. Finally, open up <boost/config/user.hpp> + and edit the following defines: +

+
+#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"
+
+

+ Now when you use boost, its configuration header will go straight to our + "frozen" versions, and ignore the default versions, you will + now be insulated from any configuration changes when you update boost. + This technique is also useful if you want to modify some of the boost configuration + files; for example if you are working with a beta compiler release not + yet supported by boost. +

+
+
+
+

+ Lets suppose that you're using boost with a compiler that is fully conformant + with the standard; you're not interested in the fact that older versions + of your compiler may have had bugs, because you know that your current + version does not need any configuration macros setting. In a case like + this, you can define BOOST_NO_COMPILER_CONFIG + either on the command line, or in <boost/config/user.hpp>, + and miss out the compiler configuration header altogether (actually you + miss out two headers, one which works out what the compiler is, and one + that configures boost for it). This has two consequences: the first is + that less code has to be c ompiled, and the second that you have removed + a dependency on two boost headers. +

+
+
+
+

+ If you are working on a unix-like platform then you can use the configure + script to generate a "frozen" configuration based on your current + compiler setup - see using the configure + script for more details. +

+
+
+
+
+

+ The boost configuration library provides a full set of regression test programs + under the <boost-root>/boost/config/ + test/ + sub-directory: +

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ File +

+ 		+

+ Description +

+
+

+ config_info.cpp +

+ 		+

+ Prints out a detailed description of your compiler/standard library/platform + setup, plus your current boost configuration. The information provided + by this program useful in setting up the boost configuration files. + If you report that boost is incorrectly configured for your compiler/library/platform + then please include the output from this program when reporting the + changes required. +

+
+

+ config_test.cpp +

+ 		+

+ A monolithic test program that includes most of the individual test + cases. This provides a quick check to see if boost is correctly configured + for your compiler/library/platform. +

+
+

+ limits_test.cpp +

+ 		+

+ Tests your standard library's std::numeric_limits + implementation (or its boost provided replacement if BOOST_NO_LIMITS is defined). This + test file fails with most versions of numeric_limits, mainly due + to the way that some compilers treat NAN's and infinity. +

+
+

+ no_*pass.cpp +

+ 		+

+ Individual compiler defect test files. Each of these should compile, + if one does not then the corresponding BOOST_NO_XXX + macro needs to be defined - see each test file for specific details. +

+
+

+ no_*fail.cpp +

+ 		+

+ Individual compiler defect test files. Each of these should not compile, + if one does then the corresponding BOOST_NO_XXX + macro is defined when it need not be - see each test file for specific + details. +

+
+

+ has_*pass.cpp +

+ 		+

+ Individual feature test files. If one of these does not compile then + the corresponding BOOST_HAS_XXX + macro is defined when it should not be - see each test file for specific + details. +

+
+

+ has_*fail.cpp +

+ 		+

+ Individual feature test files. If one of these does compile then + the corresponding BOOST_HAS_XXX + macro can be safely defined - see each test file for specific details. +

+
+

+ Although you can run the configuration regression tests as individual test + files, there are rather a lot of them, so there are a couple of shortcuts + to help you out: +

+

+ If you have built the boost + regression test driver, then you can use this to produce a nice html + formatted report of the results using the supplied test file. +

+

+ Alternatively you can run the configure script like this: +

+
+

+

+

+ ./configure + --enable-test +

+

+

+
+

+ in which case the script will test the current configuration rather than + creating a new one from scratch. +

+

+ If you are reporting the results of these tests for a new platform/library/compiler + then please include a log of the full compiler output, the output from config_info.cpp, and the pass/fail test results. +

+
+
+

+

+
+ + + +

Last revised: May 30, 2007 at 04:42:31 GMT

+
+
Next
+ + diff --git a/doc/macro_reference.qbk b/doc/macro_reference.qbk new file mode 100644 index 00000000..6cf90de4 --- /dev/null +++ b/doc/macro_reference.qbk @@ -0,0 +1,827 @@ +[/ + Boost.Config + + Copyright (c) 2001 Beman Dawes + Copyright (c) 2001 Vesa Karvonen + Copyright (c) 2001 John Maddock + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + + + +[section Boost Macro Reference] + +[#config_defects] + +[section Macros that describe defects] + +The following macros all describe features that are required by the C++ standard, +if one of the following macros is defined, then it represents a defect in the +compiler's conformance with the standard. + + +[table +[[Macro ][Section ][ Description ]] + + +[[`BOOST_BCB_PARTIAL_SPECIALIZATION_BUG`][Compiler][ +The compiler exibits certain partial specialisation bug - probably Borland +C++ Builder specific. +]] +[[`BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL`][Compiler][ +Argument dependent lookup fails if there is a using declaration for the +symbol being looked up in the current scope. For example, using +`boost::get_pointer`; prevents ADL from finding overloads of `get_pointer` +in namespaces nested inside boost (but not elsewhere). Probably +Borland specific. +]] +[[`BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP`][Compiler][ +Compiler does not implement argument-dependent lookup (also named +Koenig lookup); see std::3.4.2 \[basic.koenig.lookup\] +]] +[[`BOOST_NO_AUTO_PTR`][Standard library][ +If the compiler / library supplies non-standard or broken `std::auto_ptr`. +]] +[[`BOOST_NO_CTYPE_FUNCTIONS`][Platform][ +The Platform does not provide functions for the character-classifying +operations `` and ``, only macros. +]] +[[`BOOST_NO_CV_SPECIALIZATIONS`][Compiler][ +If template specialisations for cv-qualified types conflict with a +specialisation for a cv-unqualififed type. +]] +[[`BOOST_NO_CV_VOID_SPECIALIZATIONS`][Compiler][ +If template specialisations for cv-void types conflict with a specialisation +for void. +]] +[[`BOOST_NO_CWCHAR`][Platform][ +The Platform does not provide `` and ``. +]] +[[`BOOST_NO_CWCTYPE`][Platform][ +The Platform does not provide `` and ``. +]] +[[`BOOST_NO_DEPENDENT_NESTED_DERIVATIONS`][Compiler][ +The compiler fails to compile a nested class that has a dependent base class: +`` +template +struct foo : { + template + struct bar : public U {}; +`` +}; +]] +[[`BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS`][Compiler][ +Template value parameters cannot have a dependent type, for example: +`` +template +class X { ... }; +`` +]] +[[`BOOST_NO_EXCEPTION_STD_NAMESPACE`][Standard Library][ +The standard library does not put some or all of the contents of +`` in namespace std. +]] +[[`BOOST_NO_EXCEPTIONS`][Compiler][ +The compiler does not support exception handling (this setting is typically +required by many C++ compilers for embedded platforms). Note that there is +no requirement for boost libraries to honor this configuration setting - +indeed doing so may be impossible in some cases. Those libraries that do +honor this will typically abort if a critical error occurs - you have been +warned! +]] +[[`BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS`][Compiler][ +Can only use deduced template arguments when calling function template +instantiations. +]] +[[`BOOST_NO_FUNCTION_TEMPLATE_ORDERING`][Compiler][ +The compiler does not perform function template ordering or its function +template ordering is incorrect. +`` +// #1 +template void f(T); + +// #2 +template void f(T(*)(U)); + +void bar(int); + +f(&bar); // should choose #2. +`` +]] +[[`BOOST_NO_INCLASS_MEMBER_INITIALIZATION`][Compiler][ +Compiler violates std::9.4.2/4. +]] +[[`BOOST_NO_INTRINSIC_WCHAR_T`][Compiler][ +The C++ implementation does not provide `wchar_t`, or it is really a synonym +for another integral type. Use this symbol to decide whether it is appropriate +to explicitly specialize a template on `wchar_t` if there is already a +specialization for other integer types. +]] +[[`BOOST_NO_IS_ABSTRACT`][Compiler][ +The C++ compiler does not support SFINAE with abstract types, this is covered +by __CORE_LANGUAGE_DR337__, but is not part of the current standard. Fortunately +most compilers that support SFINAE also support this DR. +]] +[[`BOOST_NO_LIMITS`][Standard library][ +The C++ implementation does not provide the `` header. Never check for +this symbol in library code; always include ``, which +guarantees to provide `std::numeric_limits`. +]] +[[`BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS`][Standard library][ +Constants such as `numeric_limits::is_signed` are not available for use +at compile-time. +]] +[[`BOOST_NO_LONG_LONG_NUMERIC_LIMITS`][Standard library][ +There is no specialization for `numeric_limits` and +`numeric_limits`. `` will then add these +specializations as a standard library "fix" only if the compiler supports the +`long long` datatype. +]] +[[`BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS`][Compiler][ +The compiler does not support the specialization of individual member +functions of template classes. +]] +[[`BOOST_NO_MEMBER_TEMPLATE_KEYWORD`][Compiler][ +If the compiler supports member templates, but not the template keyword +when accessing member template classes. +]] +[[`BOOST_NO_MEMBER_TEMPLATE_FRIENDS`][Compiler][ +Member template friend syntax (`template friend class frd;`) +described in the C++ Standard, 14.5.3, not supported. +]] +[[`BOOST_NO_MEMBER_TEMPLATES`][Compiler][ +Member template functions not fully supported. +]] +[[`BOOST_NO_MS_INT64_NUMERIC_LIMITS`][Standard library][ +There is no specialization for `numeric_limits<__int64>` and +`numeric_limits`. `` will then add these +specializations as a standard library "fix", only if the compiler supports +the `__int64` datatype. +]] +[[`BOOST_NO_OPERATORS_IN_NAMESPACE`][Compiler][ +Compiler requires inherited operator friend functions to be defined at +namespace scope, then using'ed to boost. Probably GCC specific. See +[@../../../../boost/operators.hpp ``] for example. +]] +[[`BOOST_NO_POINTER_TO_MEMBER_CONST`][Compiler][ +The compiler does not correctly handle pointers to const member functions, +preventing use of these in overloaded function templates. See +[@../../../../boost/functional.hpp ``] for example. +]] +[[`BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS`][Compiler][ +Pointers to members don't work when used as template parameters. +]] +[[`BOOST_NO_PRIVATE_IN_AGGREGATE`][Compiler][ +The compiler misreads 8.5.1, treating classes as non-aggregate if they +contain private or protected member functions. +]] +[[`BOOST_NO_SFINAE`][Compiler][ +The compiler does not support the "Substitution Failure Is Not An Error" +meta-programming idiom. +]] +[[`BOOST_NO_STD_ALLOCATOR`][Standard library][ +The C++ standard library does not provide a standards conforming +`std::allocator`. +]] +[[`BOOST_NO_STD_DISTANCE`][Standard library][ +The platform does not have a conforming version of `std::distance`. +]] +[[`BOOST_NO_STD_ITERATOR`][Standard library][ +The C++ implementation fails to provide the `std::iterator` class. +]] +[[`BOOST_NO_STD_ITERATOR_TRAITS`][Standard library][ +The compiler does not provide a standard compliant implementation of +`std::iterator_traits`. Note that the compiler may still have a +non-standard implementation. +]] +[[`BOOST_NO_STD_LOCALE`][Standard library][ +The standard library lacks `std::locale`. +]] +[[`BOOST_NO_STD_MESSAGES`][Standard library][ +The standard library lacks a conforming `std::messages` facet. +]] +[[`BOOST_NO_STD_MIN_MAX`][Standard library][ +The C++ standard library does not provide the `min()` and `max()` template +functions that should be in ``. +]] +[[`BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN`][Standard library][ +Defined if the standard library's output iterators are not assignable. +]] +[[`BOOST_NO_STD_USE_FACET`][Standard library][ +The standard library lacks a conforming `std::use_facet`. +]] +[[`BOOST_NO_STD_WSTREAMBUF`][Standard library][ +The standard library's implementation of `std::basic_streambuf` +is either missing, incomplete, or buggy. +]] +[[`BOOST_NO_STD_WSTRING`][Standard library][ +The standard library lacks `std::wstring`. +]] +[[`BOOST_NO_STDC_NAMESPACE`][Compiler, Platform][ +The contents of C++ standard headers for C library functions +(the `` headers) have not been placed in namespace std. This test is +difficult - some libraries "fake" the std C functions by adding using +declarations to import them into namespace std, unfortunately they don't +necessarily catch all of them... +]] +[[`BOOST_NO_STRINGSTREAM`][Standard library][ +The C++ implementation does not provide the `` header. +]] +[[`BOOST_NO_SWPRINTF`][Platform][ +The platform does not have a conforming version of `swprintf`. +]] +[[`BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION`][Compiler][ +Class template partial specialization (14.5.4 \[temp.class.spec\]) not +supported. +]] +[[`BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS`][Standard library][ +The standard library does not provide templated iterator constructors +for its containers. +]] +[[`BOOST_NO_TEMPLATE_TEMPLATES`][Compiler][ +The compiler does not support template template parameters. +]] +[[`BOOST_NO_UNREACHABLE_RETURN_DETECTION`][Compiler][ +If a return is unreachable, then no return statement should be required, +however some compilers insist on it, while other issue a bunch of warnings +if it is in fact present. +]] +[[`BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE`][Compiler][ +The compiler will not accept a using declaration that brings a function +from a typename used as a base class into a derived class if functions of +the same name are present in the derived class. +]] +[[`BOOST_NO_USING_TEMPLATE`][Compiler][ +The compiler will not accept a using declaration that imports a template +class or function from another namespace. Originally a Borland specific +problem with imports to/from the global namespace, extended to MSVC6 +which has a specific issue with importing template classes (but not +functions). +]] +[[`BOOST_NO_VOID_RETURNS`][Compiler][ +The compiler does not allow a void function to return the result of calling +another void function. +`` +void f() {} +void g() { return f(); } +`` +]] +] + +[endsect] + +[#config_features] + +[section Macros that describe optional features] + +The following macros describe features that are not required by the C++ +standard. The macro is only defined if the feature is present. + + +[table +[[Macro ][Section ][Description ]] + +[[`BOOST_HAS_BETHREADS`][Platform][ +The platform supports BeOS style threads. +]] +[[`BOOST_HAS_CLOCK_GETTIME`][Platform][ +The platform has the POSIX API `clock_gettime`. +]] +[[`BOOST_HAS_DECLSPEC`][Compiler][ +The compiler uses `__declspec(dllexport)` and `__declspec(dllimport)` to +export/import symbols from dll's. +]] +[[`BOOST_HAS_DIRENT_H`][Platform][ +The platform has the POSIX header ``. +]] +[[`BOOST_HAS_EXPM1`][Platform][ +The platform has the functions `expm1`, `expm1f` and `expm1l` in `` +]] +[[`BOOST_HAS_FTIME`][Platform][ +The platform has the Win32 API `GetSystemTimeAsFileTime`. +]] +[[`BOOST_HAS_GETTIMEOFDAY`][Platform][ +The platform has the POSIX API `gettimeofday`. +]] +[[`BOOST_HAS_HASH`][Standard library][ +The C++ implementation provides the (SGI) hash_set and hash_map classes. +When defined, `BOOST_HASH_SET_HEADER` and `BOOST_HASH_LIST_HEADER` will contain +the names of the header needed to access hash_set and hash_map; +`BOOST_STD_EXTENSION_NAMESPACE` will provide the namespace in which the two +class templates reside. +]] +[[`BOOST_HAS_LOG1P`][Platform][ +The platform has the functions `log1p`, `log1pf` and `log1pl` in ``. +]] +[[`BOOST_HAS_MACRO_USE_FACET`][Standard library][ +The standard library lacks a conforming `std::use_facet`, but has a macro +`_USE(loc, Type)` that does the job. This is primarily for the Dinkumware +std lib. +]] +[[`BOOST_HAS_MS_INT64`][Compiler][ +The compiler supports the `__int64` data type. +]] +[[`BOOST_HAS_NANOSLEEP`][Platform][ +The platform has the POSIX API nanosleep. +]] +[[`BOOST_HAS_NL_TYPES_H`][Platform][ +The platform has an ``. +]] +[[`BOOST_HAS_NRVO`][Compiler][ +Indicated that the compiler supports the named return value optimization +(NRVO). Used to select the most efficient implementation for some function. +See [@../../../../boost/operators.hpp ``] for example. +]] +[[`BOOST_HAS_PARTIAL_STD_ALLOCATOR`][Standard Library][ +The standard library has a partially conforming `std::allocator` class, but +without any of the member templates. +]] +[[`BOOST_HAS_PTHREAD_DELAY_NP`][Platform][ +The platform has the POSIX API `pthread_delay_np`. +]] +[[`BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE`][Platform][ +The platform has the POSIX API `pthread_mutexattr_settype`. +]] +[[`BOOST_HAS_PTHREAD_YIELD`][Platform][ +The platform has the POSIX API `pthread_yield`. +]] +[[`BOOST_HAS_PTHREADS`][Platform][ +The platform support POSIX style threads. +]] +[[`BOOST_HAS_SCHED_YIELD`][Platform][ +The platform has the POSIX API `sched_yield`. +]] +[[`BOOST_HAS_SGI_TYPE_TRAITS`][Compiler, Standard library][ +The compiler has native support for SGI style type traits. +]] +[[`BOOST_HAS_STDINT_H`][Platform][ +The platform has a `` +]] +[[`BOOST_HAS_SLIST`][Standard library][ +The C++ implementation provides the (SGI) slist class. When defined, +`BOOST_SLIST_HEADER` will contain the name of the header needed to access +`slist` and `BOOST_STD_EXTENSION_NAMESPACE` will provide the namespace in +which `slist` resides. +]] +[[`BOOST_HAS_STLP_USE_FACET`][Standard library][ +The standard library lacks a conforming `std::use_facet`, but has a workaround +class-version that does the job. This is primarily for the STLport std lib. +]] +[[`BOOST_HAS_TR1_ARRAY`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_COMPLEX_OVERLOADS`][Standard library][ +The library has a version of `` that supports passing scalars to the +complex number algorithms. +]] +[[`BOOST_HAS_TR1_COMPLEX_INVERSE_TRIG`][Standard library][ +The library has a version of `` that includes the new inverse trig +functions from TR1. +]] +[[`BOOST_HAS_TR1_REFERENCE_WRAPPER`][Standard library][ +The library has TR1 conforming reference wrappers in ``. +]] +[[`BOOST_HAS_TR1_RESULT_OF`][Standard library][ +The library has a TR1 conforming result_of template in ``. +]] +[[`BOOST_HAS_TR1_MEM_FN`][Standard library][ +The library has a TR1 conforming mem_fn function template in ``. +]] +[[`BOOST_HAS_TR1_BIND`][Standard library][ +The library has a TR1 conforming bind function template in ``. +]] +[[`BOOST_HAS_TR1_FUNCTION`][Standard library][ +The library has a TR1 conforming function class template in ``. +]] +[[`BOOST_HAS_TR1_HASH`][Standard library][ +The library has a TR1 conforming hash function template in ``. +]] +[[`BOOST_HAS_TR1_SHARED_PTR`][Standard library][ +The library has a TR1 conforming `shared_ptr` class template in ``. +]] +[[`BOOST_HAS_TR1_RANDOM`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_REGEX`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_TUPLE`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_TYPE_TRAITS`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_UTILITY`][Standard library][ +The library has the TR1 additions to `` (tuple interface to `std::pair`). +]] +[[`BOOST_HAS_TR1_UNORDERED_MAP`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1_UNORDERED_SET`][Standard library][ +The library has a TR1 conforming version of ``. +]] +[[`BOOST_HAS_TR1`][Standard library][ +Implies all the other `BOOST_HAS_TR1_*` macros should be set. +]] +[[`BOOST_HAS_THREADS`][Platform, Compiler][ +Defined if the compiler, in its current translation mode, supports multiple +threads of execution. +]] +[[`BOOST_HAS_TWO_ARG_USE_FACET`][Standard library][ +The standard library lacks a conforming std::use_facet, but has a two +argument version that does the job. This is primarily for the Rogue Wave +std lib. +]] +[[`BOOST_HAS_UNISTD_H`][Platform][ +The Platform provides ``. +]] +[[`BOOST_HAS_WINTHREADS`][Platform][ +The platform supports MS Windows style threads. +]] +[[`BOOST_MSVC_STD_ITERATOR`][Standard library][ +Microsoft's broken version of `std::iterator` is being used. This implies that +`std::iterator` takes no more than two template parameters. +]] +[[`BOOST_MSVC6_MEMBER_TEMPLATES`][Compiler][ +Microsoft Visual C++ 6.0 has enough member template idiosyncrasies +(being polite) that `BOOST_NO_MEMBER_TEMPLATES` is defined for this compiler. +`BOOST_MSVC6_MEMBER_TEMPLATES` is defined to allow compiler specific workarounds. +This macro gets defined automatically if `BOOST_NO_MEMBER_TEMPLATES` is not +defined - in other words this is treated as a strict subset of the features +required by the standard. +]] +[[`BOOST_HAS_STDINT_H`][Platform][ +There are no 1998 C++ Standard headers `` or ``, although the +1999 C Standard does include ``. If `` is present, +`` can make good use of it, so a flag is supplied (signalling +presence; thus the default is not present, conforming to the current C++ +standard). +]] +] + +[endsect] + +[section Macros that describe C++0x features] + +The following macros describe features that are likely to be included in the +upcoming ISO C++ standard, C++0x. + + +[table +[[Macro ][Description ]] + +[[`BOOST_HAS_CONCEPTS`][ +The compiler supports concepts. Note: concepts have been proposed for C++0x, +but have not yet been approved for inclusion in the language. +]] +[[`BOOST_HAS_LONG_LONG`][ +The compiler supports the long long data type. +]] +[[`BOOST_HAS_RVALUE_REFS`][ +The compiler supports rvalue references. +]] +[[`BOOST_HAS_STATIC_ASSERT`][ +The compiler supports static assertions. +]] +[[`BOOST_HAS_VARIADIC_TMPL`][ +The compiler supports variadic templates. Note: variadic templates have been +proposed for C++0x, but have not yet been approved for inclusion in the +language. +]] +] + + +[endsect] + +[#config_helpers] + +[section Boost Helper Macros] + +The following macros are either simple helpers, or macros that provide +workarounds for compiler/standard library defects. + + +[table +[[Macro ][Description ]] + +[[`BOOST_DEDUCED_TYPENAME`][ +Some compilers don't support the use of typename for dependent types in deduced +contexts. This macro expands to nothing on those compilers, and typename +elsewhere. For example, replace: +`template void f(T, typename T::type);` +with: +`template void f(T, BOOST_DEDUCED_TYPENAME T::type);` +]] +[[`BOOST_HASH_MAP_HEADER`][ +The header to include to get the SGI `hash_map` class. This macro is only +available if `BOOST_HAS_HASH` is defined. +]] +[[`BOOST_HASH_SET_HEADER`][ +The header to include to get the SGI `hash_set` class. This macro is only +available if `BOOST_HAS_HASH` is defined. +]] +[[`BOOST_SLIST_HEADER`][ +The header to include to get the SGI `slist` class. This macro is only +available if `BOOST_HAS_SLIST` is defined. +]] +[[`BOOST_STD_EXTENSION_NAMESPACE`][ +The namespace used for std library extensions (hashtable classes etc). +]] +[[`BOOST_STATIC_CONSTANT(Type, assignment)`][ +On compilers which don't allow in-class initialization of static integral +constant members, we must use enums as a workaround if we want the constants +to be available at compile-time. This macro gives us a convenient way to +declare such constants. +For example instead of: +`` +struct foo{ + static const int value = 2; +}; +`` +use: +`` +struct foo{ + BOOST_STATIC_CONSTANT(int, value = 2); +}; +`` +]] +[[`BOOST_UNREACHABLE_RETURN(result)`][ +Normally evaluates to nothing, but evaluates to return x; if the compiler +requires a return, even when it can never be reached. +]] +[[`BOOST_EXPLICIT_TEMPLATE_TYPE(t)` + `BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t,v)` + `BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)` + `BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t,v)`][ +Some compilers silently "fold" different function template instantiations if +some of the template parameters don't appear in the function parameter list. +For instance: +`` + #include + #include + #include + + template + void f() { std::cout << n << ' '; } + + template + void g() { std::cout << typeid(T).name() << ' '; } + + int main() { + f<1>(); + f<2>(); + + g(); + g(); + } +`` +incorrectly outputs [^2 2 double double] on VC++ 6. These macros, to be used +in the function parameter list, fix the problem without effects on the calling +syntax. For instance, in the case above write: +`` + template + void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... } + + template + void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... } +`` +Beware that they can declare (for affected compilers) a dummy defaulted +parameter, so they + +[*a)] should be always invoked [*at the end] of the parameter list + +[*b)] can't be used if your function template is multiply declared. + +Furthermore, in order to add any needed comma separator, an `APPEND_*` version +must be used when the macro invocation appears after a normal parameter +declaration or after the invocation of another macro of this same group. +]] +[[`BOOST_USE_FACET(Type, loc)`][ +When the standard library does not have a comforming `std::use_facet` there +are various workarounds available, but they differ from library to library. +This macro provides a consistent way to access a locale's facets. For example, +replace: +`std::use_facet(loc);` +with: +`BOOST_USE_FACET(Type, loc);` +Note do not add a `std::` prefix to the front of `BOOST_USE_FACET`. +]] +[[`BOOST_HAS_FACET(Type, loc)`][ +When the standard library does not have a comforming `std::has_facet` there +are various workarounds available, but they differ from library to library. +This macro provides a consistent way to check a locale's facets. For example, +replace: +`std::has_facet(loc);` +with: +`BOOST_HAS_FACET(Type, loc);` +Note do not add a `std::` prefix to the front of `BOOST_HAS_FACET`. +]] +[[`BOOST_NESTED_TEMPLATE`][ +Member templates are supported by some compilers even though they can't use +the `A::template member` syntax, as a workaround replace: +`typedef typename A::template rebind binder;` +with: +`typedef typename A::BOOST_NESTED_TEMPLATE rebind binder;` +]] +[[`BOOST_STRINGIZE(X)`][ +Converts the parameter `X` to a string after macro replacement on `X` has +been performed. +]] +[[`BOOST_JOIN(X,Y)`][ +This piece of macro magic joins the two arguments together, even when one of +the arguments is itself a macro (see 16.3.1 in C++ standard). This is normally +used to create a mangled name in combination with a predefined macro such a +\_\_LINE__. +]] +] + +[endsect] + +[#config_info_macros] + +[section Boost Informational Macros] + +The following macros describe boost features; these are, generally speaking +the only boost macros that should be tested in user code. + +[table + +[[Macro ][Header ][Description ]] + +[[`BOOST_VERSION`][``][ +Describes the boost version number in XXYYZZ format such that: +`(BOOST_VERSION % 100)` is the sub-minor version, `((BOOST_VERSION / 100) % 1000)` +is the minor version, and `(BOOST_VERSION / 100000)` is the major version. +]] +[[`BOOST_NO_INT64_T`][`` ``][ +Defined if there are no 64-bit integral types: `int64_t`, `uint64_t` etc. +]] +[[`BOOST_NO_INTEGRAL_INT64_T`][`` ``][ +Defined if `int64_t` as defined by `` is not usable in +integral constant expressions. +]] +[[`BOOST_MSVC`][``][ +Defined if the compiler is really Microsoft Visual C++, as opposed to one +of the many other compilers that also define `_MSC_VER`. +]] +[[`BOOST_INTEL`][``][ +Defined if the compiler is an Intel compiler, takes the same value as the +compiler version macro. +]] +[[`BOOST_WINDOWS`][``][ +Defined if the Windows platfrom API is available. +]] +[[`BOOST_DINKUMWARE_STDLIB`][``][ +Defined if the dinkumware standard library is in use, takes the same value +as the Dinkumware library version macro `_CPPLIB_VER` if defined, otherwise 1. +]] +[[`BOOST_NO_WREGEX`][``][ +Defined if the regex library does not support wide character regular +expressions. +]] +[[`BOOST_COMPILER`][``][ +Defined as a string describing the name and version number of the compiler +in use. Mainly for debugging the configuration. +]] +[[`BOOST_STDLIB`][``][ +Defined as a string describing the name and version number of the standard +library in use. Mainly for debugging the configuration. +]] +[[`BOOST_PLATFORM`][``][ +Defined as a string describing the name of the platform. Mainly for debugging +the configuration. +]] +] + +[endsect] + +[section Macros for libraries with separate source code] + +The following macros and helper headers are of use to authors whose libraries +include separate source code, and are intended to address two issues: fixing +the ABI of the compiled library, and selecting which compiled library to link +against based upon the compilers settings. + +[section ABI Fixing] + +When linking against a pre-compiled library it vital that the ABI used by the +compiler when building the library ['matches exactly] the ABI used by the code +using the library. In this case ABI means things like the struct packing +arrangement used, the name mangling scheme used, or the size of some types +(enum types for example). This is separate from things like threading support, +or runtime library variations, which have to be dealt with by build variants. +To put this in perspective there is one compiler (Borland's) that has so many +compiler options that make subtle changes to the ABI, that at least in theory +there 3200 combinations, and that's without considering runtime library +variations. Fortunately these variations can be managed by `#pragma`'s that +tell the compiler what ABI to use for the types declared in your library. +In order to avoid sprinkling `#pragma`'s all over the boost headers, there are +some prefix and suffix headers that do the job. Typical usage is: + +[*my_library.hpp] + + #ifndef MY_INCLUDE_GUARD + #define MY_INCLUDE_GUARD + + // all includes go here: + ``[^[*#include ]]`` + #include + + ``[^[*#include ]]`` // must be the last #include + + namespace boost { + + // your code goes here + + } + + ``[^[*#include ]]`` // pops abi_prefix.hpp pragmas + + #endif // include guard + +[*my_library.cpp] + + ... + // nothing special need be done in the implementation file + ... + +The user can disable this mechanism by defining `BOOST_DISABLE_ABI_HEADERS`, or +they can define `BOOST_ABI_PREFIX` and/or `BOOST_ABI_SUFFIX` to point to their +own prefix/suffix headers if they so wish. + +[endsect] + +[section Automatic library selection] + +It is essential that users link to a build of a library which was built against +the same runtime library that their application will be built against -if this +does not happen then the library will not be binary compatible with their own +code- and there is a high likelihood that their application will experience +runtime crashes. These kinds of problems can be extremely time consuming and +difficult to debug, and often lead to frustrated users and authors alike (simply +selecting the right library to link against is not as easy as it seems when +their are 6-8 of them to chose from, and some users seem to be blissfully +unaware that there even are different runtimes available to them). + +To solve this issue, some compilers allow source code to contain `#pragma`'s that +instruct the linker which library to link against, all the user need do is +include the headers they need, place the compiled libraries in their library +search path, and the compiler and linker do the rest. Boost.config supports +this via the header ``, before including this header +one or more of the following macros need to be defined: + +[variablelist +[[`BOOST_LIB_NAME`][ +Required: An identifier containing the basename of the library, for +example 'boost_regex'. +]] +[[`BOOST_DYN_LINK`][ +Optional: when set link to dll rather than static library. +]] +[[`BOOST_LIB_DIAGNOSTIC`][ +Optional: when set the header will print out the name of the library selected +(useful for debugging). +]] +] + +If the compiler supports this mechanism, then it will be told to link against +the appropriately named library, the actual algorithm used to mangle the name +of the library is documented inside `` and has to +match that used to create the libraries via bjam 's install rules. + + +[*my_library.hpp] + + ... + // + // Don't include auto-linking code if the user has disabled it by + // defining BOOST_ALL_NO_LIB, or BOOST_MY_LIBRARY_NO_LIB, or if this + // is one of our own source files (signified by BOOST_MY_LIBRARY_SOURCE): + // + #if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_MY_LIBRARY_NO_LIB) && !defined(BOOST_MY_LIBRARY_SOURCE) + # define BOOST_LIB_NAME boost_my_library + # ifdef BOOST_MY_LIBRARY_DYN_LINK + # define BOOST_DYN_LINK + # endif + # include + #endif + ... + +[*my_library.cpp] + + // define BOOST_MY_LIBRARY_SOURCE so that the header knows that the + // library is being built (possibly exporting rather than importing code) + // + #define BOOST_MY_LIBRARY_SOURCE + + #include + ... + +[endsect] + +[endsect] + +[endsect] diff --git a/doc/rationale.qbk b/doc/rationale.qbk new file mode 100644 index 00000000..7ca27a47 --- /dev/null +++ b/doc/rationale.qbk @@ -0,0 +1,82 @@ +[/ + Boost.Config + + Copyright (c) 2001 Beman Dawes + Copyright (c) 2001 Vesa Karvonen + Copyright (c) 2001 John Maddock + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + +[#config_rationale] + +[section Rationale] + +The problem with many traditional "textbook" implementations of configuration +headers (where all the configuration options are in a single "monolithic" +header) is that they violate certain fundamental software engineering +principles which would have the effect of making boost more fragile, more +difficult to maintain and more difficult to use safely. You can find a +description of the principles from the __PRINCIPLES_AND_PATTERNS_ARTICLE__. + +[section The problem] + +Consider a situation in which you are concurrently developing on multiple +platforms. Then consider adding a new platform or changing the platform +definitions of an existing platform. What happens? Everything, and this does +literally mean everything, recompiles. Isn't it quite absurd that adding a +new platform, which has absolutely nothing to do with previously existing +platforms, means that all code on all existing platforms needs to be +recompiled? + +Effectively, there is an imposed physical dependency between platforms that +have nothing to do with each other. Essentially, the traditional solution +employed by configuration headers does not conform to the Open-Closed +Principle: + +[: [*"A module should be open for extension but closed for modification."]] + +Extending a traditional configuration header implies modifying existing code. + +Furthermore, consider the complexity and fragility of the platform detection +code. What if a simple change breaks the detection on some minor platform? +What if someone accidentally or on purpose (as a workaround for some other +problem) defines some platform dependent macros that are used by the +detection code? A traditional configuration header is one of the most +volatile headers of the entire library, and more stable elements of +Boost would depend on it. This violates the Stable Dependencies Principle: + +[: [*"Depend in the direction of stability."]] + +After even a minor change to a traditional configuration header on one minor +platform, almost everything on every platform should be tested if we follow +sound software engineering practice. + +Another important issue is that it is not always possible to submit changes +to ``. Some boost users are currently working on platforms +using tools and libraries that are under strict Non-Disclosure Agreements. +In this situation it is impossible to submit changes to a traditional +monolithic configuration header, instead some method by which the user +can insert their own configuration code must be provided. + +[endsect] + +[section The solution] + +The approach taken by boost's configuration headers is to separate +configuration into three orthogonal parts: the compiler, the standard +library and the platform. Each compiler/standard library/platform gets +its own mini-configuration header, so that changes to one compiler's +configuration (for example) does not affect other compilers. In addition +there are measures that can be taken both to omit the compiler/standard +library/platform detection code (so that adding support to a new platform +does not break dependencies), or to freeze the configuration completely; +providing almost complete protection against dependency changes. + +[endsect] + +[endsect] + +