guidelines_for_boost_authors.html 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377
  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.79.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 class="toc">
  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. <span class="special">}</span>
  230. </pre>
  231. <p>
  232. Once the test code is in place in libs/config/test, updating the configuration
  233. test system proceeds as:
  234. </p>
  235. <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  236. <li class="listitem">
  237. 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>.
  238. This generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
  239. 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,
  240. <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>
  241. <br>
  242. </li>
  243. <li class="listitem">
  244. 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>
  245. </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>,
  246. where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
  247. <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
  248. list of compilers to test with.<br> <br> The xxx_pass_test and the
  249. 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>
  250. is not defined when it should be defined, xxx_pass_test will not report
  251. <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>
  252. is defined when it should not be defined, xxx_fail_test will not report
  253. <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>.<br> <br>
  254. </li>
  255. <li class="listitem">
  256. 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>
  257. <span class="identifier">config_info</span> <span class="identifier">config_test</span>
  258. </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>.
  259. <code class="computeroutput"><span class="identifier">config_info</span></code> should build
  260. 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>
  261. while <code class="computeroutput"><span class="identifier">config_test</span></code> should
  262. fail for those that have the defect, and pass for those that do not.
  263. </li>
  264. </ul></div>
  265. <p>
  266. Then you should:
  267. </p>
  268. <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  269. <li class="listitem">
  270. Define the defect macro in those config headers that require it.
  271. </li>
  272. <li class="listitem">
  273. Document the macro in this documentation (please do not forget this step!!)
  274. </li>
  275. <li class="listitem">
  276. Commit everything.
  277. </li>
  278. <li class="listitem">
  279. Keep an eye on the regression tests for new failures in Boost.Config
  280. caused by the addition.
  281. </li>
  282. <li class="listitem">
  283. Start using the macro.
  284. </li>
  285. </ul></div>
  286. </div>
  287. <div class="section">
  288. <div class="titlepage"><div><div><h3 class="title">
  289. <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
  290. New Feature Test Macros</a>
  291. </h3></div></div></div>
  292. <p>
  293. When you need to add a macro that describes a feature that the standard does
  294. not require, follow the convention for adding a new defect macro (above),
  295. but call the macro <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
  296. 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>".
  297. Try not to add feature test macros unnecessarily, if there is a platform
  298. specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
  299. <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
  300. that. Try to keep the macro to a feature group, or header name, rather than
  301. one specific API (for example <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
  302. rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
  303. If the macro describes a POSIX feature group, then add boilerplate code to
  304. <a href="../../../../../boost/config/detail/suffix.hpp" target="_top">&lt;boost/config/detail/suffix.hpp&gt;</a>
  305. to auto-detect the feature where possible (if you are wondering why we can't
  306. use POSIX feature test macro directly, remember that many of these features
  307. can be added by third party libraries, and are not therefore identified inside
  308. <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>).
  309. </p>
  310. </div>
  311. <div class="section">
  312. <div class="titlepage"><div><div><h3 class="title">
  313. <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
  314. the Boost Configuration Headers</a>
  315. </h3></div></div></div>
  316. <p>
  317. The aim of boost's configuration setup is that the configuration headers
  318. should be relatively stable - a boost user should not have to recompile their
  319. code just because the configuration for some compiler that they're not interested
  320. in has changed. Separating the configuration into separate compiler/standard
  321. library/platform sections provides for part of this stability, but boost
  322. authors require some amount of restraint as well, in particular:
  323. </p>
  324. <p>
  325. <a href="../../../../../boost/config.hpp" target="_top">&lt;boost/config.hpp&gt;</a>
  326. should never change, don't alter this file.
  327. </p>
  328. <p>
  329. <a href="../../../../../boost/config/user.hpp" target="_top">&lt;boost/config/user.hpp&gt;</a>
  330. is included by default, don't add extra code to this file unless you have
  331. to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
  332. as well.
  333. </p>
  334. <p>
  335. <a href="../../../../../boost/config/detail/suffix.hpp" target="_top">&lt;boost/config/detail/suffix.hpp&gt;</a>
  336. is always included so be careful about modifying this file as it breaks dependencies
  337. for everyone. This file should include only "boilerplate" configuration
  338. code, and generally should change only when new macros are added.
  339. </p>
  340. <p>
  341. <a href="../../../../../boost/config/detail/select_compiler_config.hpp" target="_top">&lt;boost/config/detail/select_compiler_config.hpp&gt;</a>,
  342. <a href="../../../../../boost/config/detail/select_platform_config.hpp" target="_top">&lt;boost/config/detail/select_platform_config.hpp&gt;</a>
  343. and <a href="../../../../../boost/config/detail/select_stdlib_config.hpp" target="_top">&lt;boost/config/detail/select_stdlib_config.hpp&gt;</a>
  344. are included by default and should change only if support for a new compiler/standard
  345. library/platform is added.
  346. </p>
  347. <p>
  348. The compiler/platform/standard library selection code is set up so that unknown
  349. platforms are ignored and assumed to be fully standards compliant - this
  350. gives unknown platforms a "sporting chance" of working "as
  351. is" even without running the configure script.
  352. </p>
  353. <p>
  354. When adding or modifying the individual mini-configs, assume that future,
  355. as yet unreleased versions of compilers, have all the defects of the current
  356. version. Although this is perhaps unnecessarily pessimistic, it cuts down
  357. on the maintenance of these files, and experience suggests that pessimism
  358. is better placed than optimism here!
  359. </p>
  360. </div>
  361. </div>
  362. <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  363. <td align="left"></td>
  364. <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2007 Beman Dawes, Vesa Karvonen, John
  365. Maddock<p>
  366. Distributed under the Boost Software License, Version 1.0. (See accompanying
  367. 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>)
  368. </p>
  369. </div></td>
  370. </tr></table>
  371. <hr>
  372. <div class="spirit-nav">
  373. <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>
  374. </div>
  375. </body>
  376. </html>