ceph/src/boost/libs/config/doc/html/boost_config/guidelines_for_boost_authors.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Guidelines for Boost Authors</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../index.html" title="Boost.Config">
   8 <link rel="up" href="../index.html" title="Boost.Config">
   9 <link rel="prev" href="cstdint.html" title="Standard Integer Types">
  10 <link rel="next" href="rationale.html" title="Rationale">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <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>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <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
  28     Boost Authors</a>
  29 </h2></div></div></div>
  30 <div class="toc"><dl>
  31 <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
  32       Compiler Warnings</a></span></dt>
  33 <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
  34       New Defect Macros</a></span></dt>
  35 <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
  36       New Feature Test Macros</a></span></dt>
  37 <dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
  38       the Boost Configuration Headers</a></span></dt>
  39 </dl></div>
  40 <p>
  41       The <a href="../../../../../boost/config.hpp" target="_top">&lt;boost/config.hpp&gt;</a>
  42       header is used to pass configuration information to other boost files, allowing
  43       them to cope with platform dependencies such as arithmetic byte ordering, compiler
  44       pragmas, or compiler shortcomings. Without such configuration information,
  45       many current compilers would not work with the Boost libraries.
  46     </p>
  47 <p>
  48       Centralizing configuration information in this header reduces the number of
  49       files that must be modified when porting libraries to new platforms, or when
  50       compilers are updated. Ideally, no other files would have to be modified when
  51       porting to a new platform.
  52     </p>
  53 <p>
  54       Configuration headers are controversial because some view them as condoning
  55       broken compilers and encouraging non-standard subsets. Adding settings for
  56       additional platforms and maintaining existing settings can also be a problem.
  57       In other words, configuration headers are a necessary evil rather than a desirable
  58       feature. The boost config.hpp policy is designed to minimize the problems and
  59       maximize the benefits of a configuration header.
  60     </p>
  61 <p>
  62       Note that:
  63     </p>
  64 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  65 <li class="listitem">
  66           Boost library implementers are not required to "<code class="computeroutput"><span class="preprocessor">#include</span>
  67           <span class="special">&lt;</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">&gt;</span></code>", and are not required in any
  68           way to support compilers that do not comply with the C++ Standard (ISO/IEC
  69           14882).
  70         </li>
  71 <li class="listitem">
  72           If a library implementer wishes to support some non-conforming compiler,
  73           or to support some platform specific feature, "<code class="computeroutput"><span class="preprocessor">#include</span>
  74           <span class="special">&lt;</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">&gt;</span></code>" is the preferred way to obtain
  75           configuration information not available from the standard headers such
  76           as <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">climits</span><span class="special">&gt;</span></code>, etc.
  77         </li>
  78 <li class="listitem">
  79           If configuration information can be deduced from standard headers such
  80           as <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">climits</span><span class="special">&gt;</span></code>, use those standard headers rather
  81           than <code class="computeroutput"><span class="special">&lt;</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">&gt;</span></code>.
  82         </li>
  83 <li class="listitem">
  84           Boost files that use macros defined in <code class="computeroutput"><span class="special">&lt;</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">&gt;</span></code>
  85           should have sensible, standard conforming, default behavior if the macro
  86           is not defined. This means that the starting point for porting <code class="computeroutput"><span class="special">&lt;</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">&gt;</span></code> to a new platform is simply to define
  87           nothing at all specific to that platform. In the rare case where there
  88           is no sensible default behavior, an #error message should describe the
  89           problem.
  90         </li>
  91 <li class="listitem">
  92           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>,
  93           post a request on the Boost mailing list. There is no guarantee such a
  94           request will be honored; the intent is to limit the complexity of config.hpp.
  95         </li>
  96 <li class="listitem">
  97           The intent is to support only compilers which appear on their way to becoming
  98           C++ Standard compliant, and only recent releases of those compilers at
  99           that.
 100         </li>
 101 <li class="listitem">
 102           The intent is not to disable mainstream features now well-supported by
 103           the majority of compilers, such as namespaces, exceptions, RTTI, or templates.
 104         </li>
 105 </ul></div>
 106 <div class="section">
 107 <div class="titlepage"><div><div><h3 class="title">
 108 <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
 109       Compiler Warnings</a>
 110 </h3></div></div></div>
 111 <p>
 112         The header <code class="computeroutput"><span class="special">&lt;</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">&gt;</span></code>
 113         can be used to disable certain compiler warnings that are hard or impossible
 114         to otherwise remove.
 115       </p>
 116 <p>
 117         Note that:
 118       </p>
 119 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 120 <li class="listitem">
 121             This header <span class="bold"><strong><span class="emphasis"><em>should never be included
 122             by another Boost header</em></span></strong></span>, it should only ever be
 123             used by a library source file or a test case.
 124           </li>
 125 <li class="listitem">
 126             The header should be included <span class="bold"><strong><span class="emphasis"><em>before
 127             you include any other header</em></span></strong></span>.
 128           </li>
 129 <li class="listitem">
 130             This header only disables warnings that are hard or impossible to otherwise
 131             deal with, and which are typically emitted by one compiler only, or in
 132             one compilers own standard library headers.
 133           </li>
 134 </ul></div>
 135 <p>
 136         Currently it disables the following warnings:
 137       </p>
 138 <div class="informaltable"><table class="table">
 139 <colgroup>
 140 <col>
 141 <col>
 142 </colgroup>
 143 <thead><tr>
 144 <th>
 145                 <p>
 146                   Compiler
 147                 </p>
 148               </th>
 149 <th>
 150                 <p>
 151                   Warning
 152                 </p>
 153               </th>
 154 </tr></thead>
 155 <tbody>
 156 <tr>
 157 <td>
 158                 <p>
 159                   Visual C++ 8 and later
 160                 </p>
 161               </td>
 162 <td>
 163                 <p>
 164                   <a href="http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx" target="_top">C4996</a>:
 165                   Error 'function': was declared deprecated
 166                 </p>
 167               </td>
 168 </tr>
 169 <tr>
 170 <td>
 171                 <p>
 172                   Intel C++
 173                 </p>
 174               </td>
 175 <td>
 176                 <p>
 177                   Warning 1786: relates to the use of "deprecated" standard
 178                   library functions rather like C4996 in Visual C++.
 179                 </p>
 180               </td>
 181 </tr>
 182 </tbody>
 183 </table></div>
 184 </div>
 185 <div class="section">
 186 <div class="titlepage"><div><div><h3 class="title">
 187 <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
 188       New Defect Macros</a>
 189 </h3></div></div></div>
 190 <p>
 191         When you need to add a new defect macro - either to fix a problem with an
 192         existing library, or when adding a new library - distil the issue down to
 193         a simple test case; often, at this point other (possibly better) workarounds
 194         may become apparent. Secondly always post the test case code to the boost
 195         mailing list and invite comments; remember that C++ is complex and that sometimes
 196         what may appear a defect, may in fact turn out to be a problem with the authors
 197         understanding of the standard.
 198       </p>
 199 <p>
 200         When you name the macro, follow the <code class="computeroutput"><span class="identifier">BOOST_NO_</span></code><span class="emphasis"><em>SOMETHING</em></span>
 201         naming convention, so that it's obvious that this is a macro reporting a
 202         defect.
 203       </p>
 204 <p>
 205         Finally, add the test program to the regression tests. You will need to place
 206         the test case in a <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code>
 207         file with the following comments near the top:
 208       </p>
 209 <pre class="programlisting"><span class="comment">//  MACRO:         BOOST_NO_FOO</span>
 210 <span class="comment">//  TITLE:         foo</span>
 211 <span class="comment">//  DESCRIPTION:   If the compiler fails to support foo</span>
 212 </pre>
 213 <p>
 214         These comments are processed by the autoconf script, so make sure the format
 215         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>",
 216         where foo is the defect description - try and keep the file name under the
 217         Mac 30 character filename limit though. You will also need to provide a function
 218         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
 219         the same name as the macro, but in all lower case, and which returns zero
 220         on success:
 221       </p>
 222 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_no_foo</span> <span class="special">{</span>
 223 <span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span>
 224 <span class="special">{</span>
 225     <span class="comment">// test code goes here:</span>
 226     <span class="comment">//</span>
 227     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 228 <span class="special">}</span>
 229
 230 <span class="special">}</span>
 231 </pre>
 232 <p>
 233         Once the test code is in place in libs/config/test, updating the configuration
 234         test system proceeds as:
 235       </p>
 236 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 237 <li class="listitem">
 238             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>.
 239             This generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
 240             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,
 241             <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>
 242             <br>
 243           </li>
 244 <li class="listitem">
 245             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>
 246             </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>,
 247             where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
 248             <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
 249             list of compilers to test with.<br> <br> The xxx_pass_test and the
 250             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>
 251             is not defined when it should be defined, xxx_pass_test will not report
 252             <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>
 253             is defined when it should not be defined, xxx_fail_test will not report
 254             <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>.<br> <br>
 255           </li>
 256 <li class="listitem">
 257             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>
 258             <span class="identifier">config_info</span> <span class="identifier">config_test</span>
 259             </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>.
 260             <code class="computeroutput"><span class="identifier">config_info</span></code> should build
 261             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>
 262             while <code class="computeroutput"><span class="identifier">config_test</span></code> should
 263             fail for those that have the defect, and pass for those that do not.
 264           </li>
 265 </ul></div>
 266 <p>
 267         Then you should:
 268       </p>
 269 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 270 <li class="listitem">
 271             Define the defect macro in those config headers that require it.
 272           </li>
 273 <li class="listitem">
 274             Document the macro in this documentation (please do not forget this step!!)
 275           </li>
 276 <li class="listitem">
 277             Commit everything.
 278           </li>
 279 <li class="listitem">
 280             Keep an eye on the regression tests for new failures in Boost.Config
 281             caused by the addition.
 282           </li>
 283 <li class="listitem">
 284             Start using the macro.
 285           </li>
 286 </ul></div>
 287 </div>
 288 <div class="section">
 289 <div class="titlepage"><div><div><h3 class="title">
 290 <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
 291       New Feature Test Macros</a>
 292 </h3></div></div></div>
 293 <p>
 294         When you need to add a macro that describes a feature that the standard does
 295         not require, follow the convention for adding a new defect macro (above),
 296         but call the macro <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
 297         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>".
 298         Try not to add feature test macros unnecessarily, if there is a platform
 299         specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
 300         <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
 301         that. Try to keep the macro to a feature group, or header name, rather than
 302         one specific API (for example <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
 303         rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
 304         If the macro describes a POSIX feature group, then add boilerplate code to
 305         <a href="../../../../../boost/config/user.hpp" target="_top">&lt;boost/config/suffix.hpp&gt;</a>
 306         to auto-detect the feature where possible (if you are wondering why we can't
 307         use POSIX feature test macro directly, remember that many of these features
 308         can be added by third party libraries, and are not therefore identified inside
 309         <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">unistd</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code>).
 310       </p>
 311 </div>
 312 <div class="section">
 313 <div class="titlepage"><div><div><h3 class="title">
 314 <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
 315       the Boost Configuration Headers</a>
 316 </h3></div></div></div>
 317 <p>
 318         The aim of boost's configuration setup is that the configuration headers
 319         should be relatively stable - a boost user should not have to recompile their
 320         code just because the configuration for some compiler that they're not interested
 321         in has changed. Separating the configuration into separate compiler/standard
 322         library/platform sections provides for part of this stability, but boost
 323         authors require some amount of restraint as well, in particular:
 324       </p>
 325 <p>
 326         <a href="../../../../../boost/config.hpp" target="_top">&lt;boost/config.hpp&gt;</a>
 327         should never change, don't alter this file.
 328       </p>
 329 <p>
 330         <a href="../../../../../boost/config/user.hpp" target="_top">&lt;boost/config/user.hpp&gt;</a>
 331         is included by default, don't add extra code to this file unless you have
 332         to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
 333         as well.
 334       </p>
 335 <p>
 336         <a href="../../../../../boost/config/user.hpp" target="_top">&lt;boost/config/suffix.hpp&gt;</a>
 337         is always included so be careful about modifying this file as it breaks dependencies
 338         for everyone. This file should include only "boilerplate" configuration
 339         code, and generally should change only when new macros are added.
 340       </p>
 341 <p>
 342         <a href="../../../../../boost/config/select_compiler_config.hpp" target="_top">&lt;boost/config/select_compiler_config.hpp&gt;</a>,
 343         <a href="../../../../../boost/config/select_platform_config.hpp" target="_top">&lt;boost/config/select_platform_config.hpp&gt;</a>
 344         and <a href="../../../../../boost/config/select_stdlib_config.hpp" target="_top">&lt;boost/config/select_stdlib_config.hpp&gt;</a>
 345         are included by default and should change only if support for a new compiler/standard
 346         library/platform is added.
 347       </p>
 348 <p>
 349         The compiler/platform/standard library selection code is set up so that unknown
 350         platforms are ignored and assumed to be fully standards compliant - this
 351         gives unknown platforms a "sporting chance" of working "as
 352         is" even without running the configure script.
 353       </p>
 354 <p>
 355         When adding or modifying the individual mini-configs, assume that future,
 356         as yet unreleased versions of compilers, have all the defects of the current
 357         version. Although this is perhaps unnecessarily pessimistic, it cuts down
 358         on the maintenance of these files, and experience suggests that pessimism
 359         is better placed than optimism here!
 360       </p>
 361 </div>
 362 </div>
 363 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 364 <td align="left"></td>
 365 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2007 Beman Dawes, Vesa Karvonen, John
 366       Maddock<p>
 367         Distributed under the Boost Software License, Version 1.0. (See accompanying
 368         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>)
 369       </p>
 370 </div></td>
 371 </tr></table>
 372 <hr>
 373 <div class="spirit-nav">
 374 <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>
 375 </div>
 376 </body>
 377 </html>