123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377 |
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
- <title>Guidelines for Boost Authors</title>
- <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
- <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
- <link rel="home" href="../index.html" title="Boost.Config">
- <link rel="up" href="../index.html" title="Boost.Config">
- <link rel="prev" href="cstdint.html" title="Standard Integer Types">
- <link rel="next" href="rationale.html" title="Rationale">
- </head>
- <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
- <table cellpadding="2" width="100%"><tr>
- <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
- <td align="center"><a href="../../../../../index.html">Home</a></td>
- <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
- <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
- <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
- <td align="center"><a href="../../../../../more/index.htm">More</a></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <a accesskey="p" href="cstdint.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h2 class="title" style="clear: both">
- <a name="boost_config.guidelines_for_boost_authors"></a><a class="link" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">Guidelines for
- Boost Authors</a>
- </h2></div></div></div>
- <div class="toc"><dl class="toc">
- <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
- Compiler Warnings</a></span></dt>
- <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
- New Defect Macros</a></span></dt>
- <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
- New Feature Test Macros</a></span></dt>
- <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
- the Boost Configuration Headers</a></span></dt>
- </dl></div>
- <p>
- The <a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
- 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.
- </p>
- <p>
- 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.
- </p>
- <p>
- 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.
- </p>
- <p>
- Note that:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- Boost library implementers are not required to "<code class="computeroutput"><span class="preprocessor">#include</span>
- <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>", and are not required in any
- way to support compilers that do not comply with the C++ Standard (ISO/IEC
- 14882).
- </li>
- <li class="listitem">
- If a library implementer wishes to support some non-conforming compiler,
- or to support some platform specific feature, "<code class="computeroutput"><span class="preprocessor">#include</span>
- <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>" is the preferred way to obtain
- configuration information not available from the standard headers such
- as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, etc.
- </li>
- <li class="listitem">
- If configuration information can be deduced from standard headers such
- as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, use those standard headers rather
- than <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
- </li>
- <li class="listitem">
- Boost files that use macros defined in <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
- should have sensible, standard conforming, default behavior if the macro
- is not defined. This means that the starting point for porting <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> 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.
- </li>
- <li class="listitem">
- If a Boost library implementer wants something added to <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>,
- 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.
- </li>
- <li class="listitem">
- 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.
- </li>
- <li class="listitem">
- The intent is not to disable mainstream features now well-supported by
- the majority of compilers, such as namespaces, exceptions, RTTI, or templates.
- </li>
- </ul></div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <a name="boost_config.guidelines_for_boost_authors.warnings"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings" title="Disabling Compiler Warnings">Disabling
- Compiler Warnings</a>
- </h3></div></div></div>
- <p>
- The header <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">warning_disable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
- can be used to disable certain compiler warnings that are hard or impossible
- to otherwise remove.
- </p>
- <p>
- Note that:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- This header <span class="bold"><strong><span class="emphasis"><em>should never be included
- by another Boost header</em></span></strong></span>, it should only ever be
- used by a library source file or a test case.
- </li>
- <li class="listitem">
- The header should be included <span class="bold"><strong><span class="emphasis"><em>before
- you include any other header</em></span></strong></span>.
- </li>
- <li class="listitem">
- 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.
- </li>
- </ul></div>
- <p>
- Currently it disables the following warnings:
- </p>
- <div class="informaltable"><table class="table">
- <colgroup>
- <col>
- <col>
- </colgroup>
- <thead><tr>
- <th>
- <p>
- Compiler
- </p>
- </th>
- <th>
- <p>
- Warning
- </p>
- </th>
- </tr></thead>
- <tbody>
- <tr>
- <td>
- <p>
- Visual C++ 8 and later
- </p>
- </td>
- <td>
- <p>
- <a href="http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx" target="_top">C4996</a>:
- Error 'function': was declared deprecated
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- Intel C++
- </p>
- </td>
- <td>
- <p>
- Warning 1786: relates to the use of "deprecated" standard
- library functions rather like C4996 in Visual C++.
- </p>
- </td>
- </tr>
- </tbody>
- </table></div>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding New Defect Macros">Adding
- New Defect Macros</a>
- </h3></div></div></div>
- <p>
- 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.
- </p>
- <p>
- When you name the macro, follow the <code class="computeroutput"><span class="identifier">BOOST_NO_</span></code><span class="emphasis"><em>SOMETHING</em></span>
- naming convention, so that it's obvious that this is a macro reporting a
- defect.
- </p>
- <p>
- Finally, add the test program to the regression tests. You will need to place
- the test case in a <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code>
- file with the following comments near the top:
- </p>
- <pre class="programlisting"><span class="comment">// MACRO: BOOST_NO_FOO</span>
- <span class="comment">// TITLE: foo</span>
- <span class="comment">// DESCRIPTION: If the compiler fails to support foo</span>
- </pre>
- <p>
- These comments are processed by the autoconf script, so make sure the format
- follows the one given. The file should be named "<code class="computeroutput"><span class="identifier">boost_no_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>",
- 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 "<code class="computeroutput"><span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span></code>" that is declared in a namespace with
- the same name as the macro, but in all lower case, and which returns zero
- on success:
- </p>
- <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_no_foo</span> <span class="special">{</span>
- <span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span>
- <span class="special">{</span>
- <span class="comment">// test code goes here:</span>
- <span class="comment">//</span>
- <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
- <span class="special">}</span>
- <span class="special">}</span>
- </pre>
- <p>
- Once the test code is in place in libs/config/test, updating the configuration
- test system proceeds as:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">tools</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span></code>.
- This generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
- file test cases from the <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code> file, updates the libs/config/test/all/Jamfile.v2,
- <code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code> and <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>.<br>
- <br>
- </li>
- <li class="listitem">
- cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">all</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
- </code><span class="emphasis"><em>MACRONAME<code class="computeroutput"> <span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>,
- where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
- <span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span> is a space separated
- list of compilers to test with.<br> <br> The xxx_pass_test and the
- xxx_fail_test <span class="bold"><strong>should both report <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code></strong></span>.<br> <br> If <span class="emphasis"><em>MACRONAME</em></span>
- is not defined when it should be defined, xxx_pass_test will not report
- <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>. If <span class="emphasis"><em>MACRONAME</em></span>
- is defined when it should not be defined, xxx_fail_test will not report
- <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>.<br> <br>
- </li>
- <li class="listitem">
- cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
- <span class="identifier">config_info</span> <span class="identifier">config_test</span>
- </code><span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>.
- <code class="computeroutput"><span class="identifier">config_info</span></code> should build
- and run cleanly for all the compilers in <span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>
- while <code class="computeroutput"><span class="identifier">config_test</span></code> should
- fail for those that have the defect, and pass for those that do not.
- </li>
- </ul></div>
- <p>
- Then you should:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- Define the defect macro in those config headers that require it.
- </li>
- <li class="listitem">
- Document the macro in this documentation (please do not forget this step!!)
- </li>
- <li class="listitem">
- Commit everything.
- </li>
- <li class="listitem">
- Keep an eye on the regression tests for new failures in Boost.Config
- caused by the addition.
- </li>
- <li class="listitem">
- Start using the macro.
- </li>
- </ul></div>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding New Feature Test Macros">Adding
- New Feature Test Macros</a>
- </h3></div></div></div>
- <p>
- 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 <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
- and name the test file "<code class="computeroutput"><span class="identifier">boost_has_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>".
- Try not to add feature test macros unnecessarily, if there is a platform
- specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
- <code class="computeroutput"><span class="identifier">__BEOS__</span></code>, or <code class="computeroutput"><span class="identifier">__linux</span></code>) 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 <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
- rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
- If the macro describes a POSIX feature group, then add boilerplate code to
- <a href="../../../../../boost/config/detail/suffix.hpp" target="_top"><boost/config/detail/suffix.hpp></a>
- 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
- <code class="computeroutput"><span class="special"><</span><span class="identifier">unistd</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>).
- </p>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying the Boost Configuration Headers">Modifying
- the Boost Configuration Headers</a>
- </h3></div></div></div>
- <p>
- 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:
- </p>
- <p>
- <a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
- should never change, don't alter this file.
- </p>
- <p>
- <a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
- is included by default, don't add extra code to this file unless you have
- to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
- as well.
- </p>
- <p>
- <a href="../../../../../boost/config/detail/suffix.hpp" target="_top"><boost/config/detail/suffix.hpp></a>
- 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.
- </p>
- <p>
- <a href="../../../../../boost/config/detail/select_compiler_config.hpp" target="_top"><boost/config/detail/select_compiler_config.hpp></a>,
- <a href="../../../../../boost/config/detail/select_platform_config.hpp" target="_top"><boost/config/detail/select_platform_config.hpp></a>
- and <a href="../../../../../boost/config/detail/select_stdlib_config.hpp" target="_top"><boost/config/detail/select_stdlib_config.hpp></a>
- are included by default and should change only if support for a new compiler/standard
- library/platform is added.
- </p>
- <p>
- 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.
- </p>
- <p>
- 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!
- </p>
- </div>
- </div>
- <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
- <td align="left"></td>
- <td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
- Maddock<p>
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
- </p>
- </div></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <a accesskey="p" href="cstdint.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
- </div>
- </body>
- </html>
|