123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219 |
- [/
- 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 <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.
- [section:warnings Disabling Compiler Warnings]
- The header `<boost/config/warning_disable.hpp>` can be used to disable
- certain compiler warnings that are hard or impossible to otherwise remove.
- Note that:
- * This header [*['should never be included by another Boost header]], it should
- only ever be used by a library source file or a test case.
- * The header should be included [*['before you include any other header]].
- * This header only disables warnings that are hard or impossible to otherwise
- deal with, and which are typically emitted by one compiler only, or
- in one compilers own standard library headers.
-
- Currently it disables the following warnings:
- [table
- [[Compiler][Warning]]
- [[Visual C++ 8 and later][[@http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx C4996]: Error 'function': was declared deprecated]]
- [[Intel C++][Warning 1786: relates to the use of "deprecated" standard
- library functions rather like C4996 in Visual C++.]]
- ]
- [endsect]
- [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`. This generates the `.cpp`
- file test cases from the `.ipp` file, updates the
- libs/config/test/all/Jamfile.v2, `config_test.cpp` and `config_info.cpp`.[br][br]
- * cd into `libs/config/test/all` and run `bjam `['MACRONAME` compiler-list`], where
- ['MACRONAME] is the name of the new macro, and ['`compiler-list`] is a space separated list of
- compilers to test with.[br][br]
- The xxx_pass_test and the xxx_fail_test [*should both report `**passed**`].[br][br]
- If ['MACRONAME] is not defined when it should be defined, xxx_pass_test will not report `**passed**`.
- If ['MACRONAME] is defined when it should not be defined, xxx_fail_test will not report `**passed**`.[br][br]
- * cd into `libs/config/test` and run `bjam 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 `<unistd.h>`).
- [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/detail/select_compiler_config.hpp <boost/config/detail/select_compiler_config.hpp>],
- [@../../../../boost/config/detail/select_platform_config.hpp <boost/config/detail/select_platform_config.hpp>] and
- [@../../../../boost/config/detail/select_stdlib_config.hpp <boost/config/detail/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]
|