libs/predef/doc/html/predef/introduction.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Introduction</title>
   5 <link rel="stylesheet" href="../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="Predef 1.1">
   8 <link rel="up" href="../index.html" title="Predef 1.1">
   9 <link rel="prev" href="../index.html" title="Predef 1.1">
  10 <link rel="next" href="using_the_predefs.html" title="Using the predefs">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <div class="spirit-nav">
  14 <a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="using_the_predefs.html"><img src="../images/next.png" alt="Next"></a>
  15 </div>
  16 <div class="section">
  17 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  18 <a name="predef.introduction"></a><a class="link" href="introduction.html" title="Introduction">Introduction</a>
  19 </h2></div></div></div>
  20 <p>
  21       This library defines a set of compiler, architecture, operating system, library,
  22       and other version numbers from the information it can gather of C, C++, Objective
  23       C, and Objective C++ predefined macros or those defined in generally available
  24       headers. The idea for this library grew out of a proposal to extend the Boost
  25       Config library to provide more, and consistent, information than the feature
  26       definitions it supports. What follows is an edited version of that brief proposal.
  27     </p>
  28 <h4>
  29 <a name="predef.introduction.h0"></a>
  30       <span class="phrase"><a name="predef.introduction.proposal"></a></span><a class="link" href="introduction.html#predef.introduction.proposal">Proposal</a>
  31     </h4>
  32 <p>
  33       The idea is to define a set of macros to identify compilers and consistently
  34       represent their version. This includes:
  35     </p>
  36 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  37 <li class="listitem">
  38           A unique BOOST_VERSION_NUMBER(major,minor,patch) macro to specify version
  39           numbers (unfortunately, the name BOOST_VERSION is already taken to designate
  40           the version number of boost itself).
  41         </li>
  42 <li class="listitem">
  43           A compiler identification macro, suitable for use in <code class="computeroutput"><span class="preprocessor">#if</span></code>/<code class="computeroutput"><span class="preprocessor">#elif</span></code> directives, for each of the supported
  44           compilers. All macros would be defined, regardless of the compiler. The
  45           one macro corresponding to the compiler being used would be defined, in
  46           terms of BOOST_VERSION_NUMBER, to carry the exact compiler version. All
  47           other macros would expand to an expression evaluating to false (for instance,
  48           the token 0) to indicate that the corresponding compiler is not present.
  49         </li>
  50 <li class="listitem">
  51           "Null values" could be set, for all macros, in boost/config/select_compiler.hpp;
  52           then, for each compiler the corresponding identification macro would be
  53           #undef and re-#defined in the corresponding boost/compiler/(cc).hpp; however
  54           in the context of the Boost.Config infrastructure using a "prefix"
  55           header (to be introduced) or boost/config/suffix.hpp is a better solution.
  56         </li>
  57 </ul></div>
  58 <h4>
  59 <a name="predef.introduction.h1"></a>
  60       <span class="phrase"><a name="predef.introduction.current_library"></a></span><a class="link" href="introduction.html#predef.introduction.current_library">Current
  61       Library</a>
  62     </h4>
  63 <p>
  64       The current Predef library is now, both an independent library, and expanded
  65       in scope. It includes detection and definition of architectures, compilers,
  66       languages, libraries, operating systems, and endianness. The key benefits are:
  67     </p>
  68 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  69 <li class="listitem">
  70           Version numbers that are always defined so that one doesn't have to guard
  71           with <code class="computeroutput"><span class="preprocessor">#ifdef</span></code>.
  72         </li>
  73 <li class="listitem">
  74           Guard macros that can be used for <code class="computeroutput"><span class="preprocessor">#ifdef</span></code>
  75           checks.
  76         </li>
  77 <li class="listitem">
  78           All possible definitions are included with the single <code class="computeroutput"><span class="preprocessor">#include</span>
  79           <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code>
  80           so that it's friendly to precompiled header usage.
  81         </li>
  82 <li class="listitem">
  83           Specific definitions can be included, ex. <code class="computeroutput"><span class="preprocessor">#include</span>
  84           <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">/</span><span class="identifier">os</span><span class="special">/</span><span class="identifier">windows</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code>
  85           for single checks.
  86         </li>
  87 <li class="listitem">
  88           Predefs can be directly used in both preprocessor and compiler expressions
  89           for comparison to other similarly defined values.
  90         </li>
  91 <li class="listitem">
  92           The headers are usable from multiple languages, that support the C preprocessor.
  93           In particular C++, C, Objective C, and Objective C++.
  94         </li>
  95 </ul></div>
  96 <h4>
  97 <a name="predef.introduction.h2"></a>
  98       <span class="phrase"><a name="predef.introduction.design_choices"></a></span><a class="link" href="introduction.html#predef.introduction.design_choices">Design
  99       choices</a>
 100     </h4>
 101 <p>
 102       An important design choice concerns how to represent compiler versions by means
 103       of a single integer number suitable for use in preprocessing directives. Let's
 104       do some calculation. The "basic" signed type for preprocessing constant-expressions
 105       is long in C90 (and C++, as of 2006) and intmax_t in C99. The type long shall
 106       at least be able to represent the number <code class="literal">+2 147 483 647</code>.
 107       This means the most significant digit can only be 0, 1 or 2; and if we want
 108       all decimal digits to be able to vary between 0 and 9, the largest range we
 109       can consider is <code class="literal">[0, 999 999 999]</code>. Distributing evenly, this
 110       means 3 decimal digits for each version number part.
 111     </p>
 112 <p>
 113       So we can:
 114     </p>
 115 <div class="orderedlist"><ol class="orderedlist" type="1">
 116 <li class="listitem">
 117           use an uneven distribution or
 118         </li>
 119 <li class="listitem">
 120           use more bits (a larger type) or
 121         </li>
 122 <li class="listitem">
 123           use 3/3/3 and have the particular compiler/platform/stdlib deal with setting
 124           the numbers within the 3-digit range.
 125         </li>
 126 </ol></div>
 127 <p>
 128       It appears relatively safe to go for the first option and set it at 2/2/5.
 129       That covers CodeWarrior and others, which are up to and past 10 for the major
 130       number. Some compilers use the build number in lieu of the patch one; five
 131       digits (which is already reached by VC++ 8) seems a reasonable limit even in
 132       this case.
 133     </p>
 134 <div class="note"><table border="0" summary="Note">
 135 <tr>
 136 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
 137 <th align="left">Note</th>
 138 </tr>
 139 <tr><td align="left" valign="top"><p>
 140         A 2/2/6 scheme would allow for bigger patch/build numbers at the cost, for
 141         instance, of limiting the major version number to 20 (or, with further constraints,
 142         to 21).
 143       </p></td></tr>
 144 </table></div>
 145 <p>
 146       It might reassure the reader that this decision is actually encoded in one
 147       place in the code; the definition of <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code>.
 148     </p>
 149 <h4>
 150 <a name="predef.introduction.h3"></a>
 151       <span class="phrase"><a name="predef.introduction.future_work"></a></span><a class="link" href="introduction.html#predef.introduction.future_work">Future
 152       work</a>
 153     </h4>
 154 <p>
 155       Even though the basics of this library are done, there is much work that can
 156       be done:
 157     </p>
 158 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 159 <li class="listitem">
 160           Right now we limit the detection of libraries to known built-in predefined
 161           macros, and to guaranteed to exist system and library headers. It might
 162           be interesting to add something like auto-configuration predefs. This way
 163           we can add definitions for user specific libraries and features.
 164         </li>
 165 <li class="listitem">
 166           Along with the above, it might be good to add some user control as to which
 167           headers are included with the top-level header. Although in the current
 168           form of the library this is less of an issue as one can include the specific
 169           headers one needs.
 170         </li>
 171 <li class="listitem">
 172           Additionally, even if there is no auto-configure style option.. It would
 173           be good to add optionally included headers so that user can get consistent
 174           version number definitions for libraries they use.
 175         </li>
 176 <li class="listitem">
 177           Having a consistent set of version number definitions opens the door to
 178           improving the user level syntax of libraries that do checks against version
 179           numbers. Specifically Boost Config's <code class="computeroutput"><span class="identifier">BOOST_WORKAROUND</span></code>
 180           macro would benefit from a more readable syntax. As would the <code class="computeroutput"><span class="identifier">BOOST_TESTED_AT</span></code> detail macro.
 181         </li>
 182 <li class="listitem">
 183           And obviously there's lots of work to do in reformulating the existing
 184           Boost libraries to use the Predef library once it's accepted.
 185         </li>
 186 <li class="listitem">
 187           And there's the continuing work of adding definitions for present and future
 188           compilers, platforms, architectures, languages, and libraries.
 189         </li>
 190 </ul></div>
 191 </div>
 192 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 193 <td align="left"></td>
 194 <td align="right"><div class="copyright-footer">Copyright &#169; 2005, 2008-2014 Rene Rivera<p>
 195         Distributed under the Boost Software License, Version 1.0. (See accompanying
 196         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>)
 197       </p>
 198 </div></td>
 199 </tr></table>
 200 <hr>
 201 <div class="spirit-nav">
 202 <a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="using_the_predefs.html"><img src="../images/next.png" alt="Next"></a>
 203 </div>
 204 </body>
 205 </html>