forked from boostorg/predef
Restructure the project to match new modular layout.
This commit is contained in:
1 parent
7f08aede99
commit
dbb5965186
150 files changed
+5
-4
No files matched your search
@@ -0,0 +1,190 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Adding new predefs</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Predef 1.0">
|
||||
<link rel="up" href="../index.html" title="Predef 1.0">
|
||||
<link rel="prev" href="using_the_predefs.html" title="Using the predefs">
|
||||
<link rel="next" href="reference.html" title="Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="using_the_predefs.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="reference.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section predef_adding_new_predefs">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="predef.adding_new_predefs"></a><a class="link" href="adding_new_predefs.html" title="Adding new predefs">Adding new predefs</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
We know that a library like this one will be an eternal work-in-progress. And
|
||||
as such we expect, and look forward to, others contributing corrections and
|
||||
additions to the predefs. With that in mind we need to keep a consistent way
|
||||
of defining the new predefs. Hence all current, and future, predefs follow
|
||||
the same structure and requirements.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="predef.adding_new_predefs.h0"></a>
|
||||
<span><a name="predef.adding_new_predefs.requirements_of_the_header"></a></span><a class="link" href="adding_new_predefs.html#predef.adding_new_predefs.requirements_of_the_header">Requirements
|
||||
of the header</a>
|
||||
</h4>
|
||||
<p>
|
||||
All predefs need to follow a set of requirements:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
The headers must use the Boost Software License.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The predef must, by default, be defined as <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">)</span></code>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The predef must be redefined to a non-zero value once detected.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The predef must, by default, be defined to <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">1</span><span class="special">)</span></code> when the predef is detected.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If possible, the predef will be defined as the version number detected.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The predef must declare itself, after being defined, for the testing system.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
And there are some extra guidelines that predef headers should follow:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
The detection should avoid including extra headers that might otherwise
|
||||
not be included by default.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If the detection must include a header, prefer guarding it within the detection
|
||||
if possible.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If the detection must include headers unconditionally, and has a choice
|
||||
of headers to include, prefer the ones with the least impact. I.e. include
|
||||
the one with the minimal set of definitions and other dependencies.
|
||||
</li>
|
||||
</ul></div>
|
||||
<h4>
|
||||
<a name="predef.adding_new_predefs.h1"></a>
|
||||
<span><a name="predef.adding_new_predefs.structure_of_the_header"></a></span><a class="link" href="adding_new_predefs.html#predef.adding_new_predefs.structure_of_the_header">Structure
|
||||
of the header</a>
|
||||
</h4>
|
||||
<p>
|
||||
For general consistency it's suggested that new predef headers follow the structure
|
||||
below, as current predef headers do. First we have the copyright and license
|
||||
statement, followed by the include guard:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">/*
|
||||
Copyright Jane Doe YYYY
|
||||
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)
|
||||
*/</span>
|
||||
|
||||
<span class="preprocessor">#ifndef</span> <span class="identifier">BOOST_PREDEF_category_tag_H</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_PREDEF_category_tag_H</span>
|
||||
</pre>
|
||||
<p>
|
||||
Depending on how you are defining the predef you will at minimum have to include
|
||||
the <code class="computeroutput"><span class="identifier">version_number</span><span class="special">.</span><span class="identifier">h</span></code> header. But you might also want to include
|
||||
the <code class="computeroutput"><span class="identifier">make</span><span class="special">.</span><span class="identifier">h</span></code> header for the version number decomposing
|
||||
utility macros:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">/</span><span class="identifier">version_number</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">/</span><span class="identifier">make</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
The Predef library uses Quickbook for documentation and for the individual
|
||||
predefs to appear in the reference section we add in-code documentation followed
|
||||
by the zero-value default definition of the predef macro. We strongly recommend
|
||||
this particular placement of the documentation and default definition because
|
||||
some development environments automatically interpret this and provide in-line
|
||||
help for the macro. In particular this works for the popular Eclipse IDE:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">/*`
|
||||
[heading `BOOST_category_tag`]
|
||||
|
||||
Documentation about what is detected.
|
||||
*/</span>
|
||||
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_category_tag</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
Next is the detection and definition of the particular predef. The structure
|
||||
for this is to do a single overall check (<code class="computeroutput"><span class="identifier">condition_a</span></code>)
|
||||
and place further version detection inside this. The first action inside the
|
||||
overall check is to "<code class="computeroutput"><span class="preprocessor">#undef</span>
|
||||
<span class="identifier">BOOST_category_tag</span></code>" which undefines
|
||||
the zero-value default. The rest is up to the you how to do the checks for
|
||||
defining the version. But at minimum it must "<code class="computeroutput"><span class="preprocessor">#define</span>
|
||||
<span class="identifier">BOOST_category_tag</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">1</span><span class="special">)</span></code>" as the fallback to minimally indicate
|
||||
that the predef was detected:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#if</span> <span class="special">(</span><span class="identifier">condition_a</span><span class="special">)</span>
|
||||
<span class="preprocessor">#undef</span> <span class="identifier">BOOST_category_tag</span>
|
||||
<span class="preprocessor">#if</span> <span class="special">(</span><span class="identifier">condition_b</span><span class="special">)</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_category_tag</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="identifier">major</span><span class="special">,</span><span class="identifier">minor</span><span class="special">,</span><span class="identifier">patch</span><span class="special">)</span>
|
||||
<span class="preprocessor">#else</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_category_tag</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">1</span><span class="special">)</span>
|
||||
<span class="preprocessor">#endif</span>
|
||||
<span class="preprocessor">#endif</span>
|
||||
</pre>
|
||||
<p>
|
||||
The testing of the predef macros is automated to generate checks for all the
|
||||
defined predefs, whether detected or not. To do this we need to declare the
|
||||
predef to the test system. This declaration is empty for regular use. And during
|
||||
the test programs they expand out specially to create informational output:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">test</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span>
|
||||
<span class="identifier">BOOST_PREDEF_DECLARE_TEST</span><span class="special">(</span><span class="identifier">BOOST_category_tag</span><span class="special">,</span><span class="string">"Name"</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
And, of course, we last need to close out the include guard:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#endif</span>
|
||||
</pre>
|
||||
<h4>
|
||||
<a name="predef.adding_new_predefs.h2"></a>
|
||||
<span><a name="predef.adding_new_predefs.using_utility_pattern_macros"></a></span><a class="link" href="adding_new_predefs.html#predef.adding_new_predefs.using_utility_pattern_macros">Using utility
|
||||
pattern macros</a>
|
||||
</h4>
|
||||
<p>
|
||||
By including:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">predef</span><span class="special">/</span><span class="identifier">make</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
One will get a set of utlity macros to decompose common version macros as defined
|
||||
by compilers. For example the EDG compiler uses a simple 3-digit version macro
|
||||
(M,N,P). It can be decomesed and defined as:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_CXX_EDG</span> <span class="identifier">BOOST_PREDEF_MAKE_N_N_N</span><span class="special">(</span><span class="identifier">__EDG_VERSION__</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
The decomposition macros are split into three types: decimal decomposition,
|
||||
hexadecimal decomposition, and date decomposition. They follow the format of
|
||||
using "N" for decimal, "F" for hexadecimal, and "Y",
|
||||
"M", "D" for dates.
|
||||
</p>
|
||||
</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 © 2005 Rene Rivera<br>Copyright © 2008-2011 Redshift
|
||||
Software Inc<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="using_the_predefs.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="reference.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,195 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Introduction</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Predef 1.0">
|
||||
<link rel="up" href="../index.html" title="Predef 1.0">
|
||||
<link rel="prev" href="../index.html" title="Predef 1.0">
|
||||
<link rel="next" href="using_the_predefs.html" title="Using the predefs">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<div class="spirit-nav">
|
||||
<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>
|
||||
</div>
|
||||
<div class="section predef_introduction">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="predef.introduction"></a><a class="link" href="introduction.html" title="Introduction">Introduction</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
This library defines a set of compiler, architecture, operating system, and
|
||||
library version numbers from the information it can gather of C++ predefined
|
||||
macros or those defined in generally available headers. The idea for this library
|
||||
grew out of a proposal to extend the Boost Config library to provide more,
|
||||
and consistent, information than the feature definitions it supports. What
|
||||
follows is an edited version of that brief proposal.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="predef.introduction.h0"></a>
|
||||
<span><a name="predef.introduction.proposal"></a></span><a class="link" href="introduction.html#predef.introduction.proposal">Proposal</a>
|
||||
</h4>
|
||||
<p>
|
||||
The idea is to define a set of macros to identify compilers and consistently
|
||||
represent their version. This includes:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
A unique BOOST_VERSION_NUMBER(major,minor,patch) macro to specify version
|
||||
numbers (unfortunately, the name BOOST_VERSION is already taken to designate
|
||||
the version number of boost itself).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
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
|
||||
compilers. All macros would be defined, regardless of the compiler. The
|
||||
one macro corresponding to the compiler being used would be defined, in
|
||||
terms of BOOST_VERSION_NUMBER, to carry the exact compiler version. All
|
||||
other macros would expand to an expression evaluating to false (for instance,
|
||||
the token 0) to indicate that the corresponding compiler is not present.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
"Null values" could be set, for all macros, in boost/config/select_compiler.hpp;
|
||||
then, for each compiler the corresponding identification macro would be
|
||||
#undef and re-#defined in the corresponding boost/compiler/(cc).hpp; however
|
||||
in the context of the Boost.Config infrastructure using a "prefix"
|
||||
header (to be introduced) or boost/config/suffix.hpp is a better solution.
|
||||
</li>
|
||||
</ul></div>
|
||||
<h4>
|
||||
<a name="predef.introduction.h1"></a>
|
||||
<span><a name="predef.introduction.current_library"></a></span><a class="link" href="introduction.html#predef.introduction.current_library">Current
|
||||
Library</a>
|
||||
</h4>
|
||||
<p>
|
||||
The current Predef library is now, both an independent library, and expanded
|
||||
in scope. It includes detection and definition of architectures, compilers,
|
||||
languages, libraries, and operating systems. The key benefits are:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Version numbers that are always defined so that one doesn't have to guard
|
||||
with <code class="computeroutput"><span class="preprocessor">#ifdef</span></code>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
All possible definitions are included with the single <code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</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">></span></code>
|
||||
so that it's friendly to precompiled header usage.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Predefs can be directly used in both preprocessor and compiler expressions
|
||||
for comparison to other similarly defined values.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The headers are usable from multiple languages, that support the C preprocessor.
|
||||
In particular C++, C, Objective C, and Objective C++.
|
||||
</li>
|
||||
</ul></div>
|
||||
<h4>
|
||||
<a name="predef.introduction.h2"></a>
|
||||
<span><a name="predef.introduction.design_choices"></a></span><a class="link" href="introduction.html#predef.introduction.design_choices">Design
|
||||
choices</a>
|
||||
</h4>
|
||||
<p>
|
||||
An important design choice concerns how to represent compiler versions by means
|
||||
of a single integer number suitable for use in preprocessing directives. Let's
|
||||
do some calculation. The "basic" signed type for preprocessing constant-expressions
|
||||
is long in C90 (and C++, as of 2006) and intmax_t in C99. The type long shall
|
||||
at least be able to represent the number <code class="literal">+2 147 483 647</code>.
|
||||
This means the most significant digit can only be 0, 1 or 2; and if we want
|
||||
all decimal digits to be able to vary between 0 and 9, the largest range we
|
||||
can consider is <code class="literal">[0, 999 999 999]</code>. Distributing evenly, this
|
||||
means 3 decimal digits for each version number part.
|
||||
</p>
|
||||
<p>
|
||||
So we can:
|
||||
</p>
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
use an uneven distribution or
|
||||
</li>
|
||||
<li class="listitem">
|
||||
use more bits (a larger type) or
|
||||
</li>
|
||||
<li class="listitem">
|
||||
use 3/3/3 and have the particular compiler/platform/stdlib deal with setting
|
||||
the numbers within the 3-digit range.
|
||||
</li>
|
||||
</ol></div>
|
||||
<p>
|
||||
It appears relatively safe to go for the first option and set it at 2/2/5.
|
||||
That covers CodeWarrior and others, which are up to and past 10 for the major
|
||||
number. Some compilers use the build number in lieu of the patch one; five
|
||||
digits (which is already reached by VC++ 8) seems a reasonable limit even in
|
||||
this case.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
A 2/2/6 scheme would allow for bigger patch/build numbers at the cost, for
|
||||
instance, of limiting the major version number to 20 (or, with further constraints,
|
||||
to 21).
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
It might reassure the reader that this decision is actually encoded in one
|
||||
place in the code; the definition of <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code>.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="predef.introduction.h3"></a>
|
||||
<span><a name="predef.introduction.future_work"></a></span><a class="link" href="introduction.html#predef.introduction.future_work">Future
|
||||
work</a>
|
||||
</h4>
|
||||
<p>
|
||||
Even though the basics of this library are done, there is much work that can
|
||||
be done:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Right now we limit the detection of libraries to known built-in predefined
|
||||
macros, and to guaranteed to exist system and library headers. It might
|
||||
be interesting to add something like auto-configuration predefs. This way
|
||||
we can add definitions for user specific libraries and features.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Along with the above, it might be good to add some user control as to which
|
||||
headers are included with the top-level header.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Additionally, even if there is no auto-configure style option.. It would
|
||||
be good to add optionally included headers so that user can get consistent
|
||||
version number definitions for libraries they use.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Having a consistent set of version number definitions opens the door to
|
||||
improving the user level syntax of libraries that do checks against version
|
||||
numbers. Specifically Boost Config's <code class="computeroutput"><span class="identifier">BOOST_WORKAROUND</span></code>
|
||||
macro would benefit from a more readable syntax. As would the <code class="computeroutput"><span class="identifier">BOOST_TESTED_AT</span></code> detail macro.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
And obviously there's lots of work to do in reformulating the existing
|
||||
Boost libraries to use the Predef library once it's accepted.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
And there's the continuing work of adding definitions for present and future
|
||||
compilers, platforms, architectures, languages, and libraries.
|
||||
</li>
|
||||
</ul></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 © 2005 Rene Rivera<br>Copyright © 2008-2011 Redshift
|
||||
Software Inc<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="../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>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,188 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Using the predefs</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Predef 1.0">
|
||||
<link rel="up" href="../index.html" title="Predef 1.0">
|
||||
<link rel="prev" href="introduction.html" title="Introduction">
|
||||
<link rel="next" href="adding_new_predefs.html" title="Adding new predefs">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="introduction.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="adding_new_predefs.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section predef_using_the_predefs">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="predef.using_the_predefs"></a><a class="link" href="using_the_predefs.html" title="Using the predefs">Using the predefs</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
To use the automatically defined predefs one needs to only include the single
|
||||
top-level header:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></span>
|
||||
</pre>
|
||||
<p>
|
||||
This defines <span class="bold"><strong>all</strong></span> the version macros known
|
||||
to the library. For each macro it will be defined to either a <span class="emphasis"><em>zero</em></span>
|
||||
valued expression for when the particular item is not detected, and to a <span class="emphasis"><em>positive</em></span>
|
||||
value if it is detected. The predef macros fall onto five categories each with
|
||||
macros of a particular prefix:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ARCHITECTURE_</span></code>for
|
||||
system/CPU architecture one is compiling for.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">BOOST_CXX_</span></code> for the compiler
|
||||
one is using.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LANGUAGE_</span></code> for language
|
||||
standards one is compiling against.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIBC_</span></code> and <code class="computeroutput"><span class="identifier">BOOST_LIBSTD_</span></code> for the C and C++ standard
|
||||
library in use.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">BOOST_OS_</span></code> for the operating
|
||||
system we are compiling to.
|
||||
</li>
|
||||
</ul></div>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
The detected definitions are for the configuration one is targeting during
|
||||
the compile. In particular in a cross-compile this means the target system,
|
||||
and not the host system.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
One uses the individual definitions to compare against specific versions by
|
||||
comparing against the <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code>
|
||||
macro. For example, to make a choice based on the version of the GCC C++ compiler
|
||||
one would:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">BOOST_CXX_GNUC</span> <span class="special">>=</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">4</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">))</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"GCC compiler is at least version 4.0.0"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">else</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"GCC compiler is at older than version 4.0.0, or not a GCC compiler"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
As you might notice above the <code class="computeroutput"><span class="keyword">else</span></code>
|
||||
clause also covers the case where the particular compiler is not detected.
|
||||
But one can make the test specifically test for the detection. All predef definitions
|
||||
are defined as a zero (0) expression when not detected. Hence one could use
|
||||
the detection with a natural single condition. For example:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">BOOST_CXX_GNUC</span><span class="special">)</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"This is GNU GCC!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">else</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Not GNU GCC."</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
And since the predef's are preprocessor definitions the same is possible from
|
||||
the preprocessor:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||||
|
||||
<span class="preprocessor">#if</span> <span class="identifier">BOOST_CXX_GNUC</span>
|
||||
<span class="preprocessor">#if</span> <span class="identifier">BOOST_CXX_GNUC</span> <span class="special">>=</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">4</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">)</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span> <span class="identifier">the_compiler</span> <span class="special">=</span> <span class="string">"GNU GCC, of at least version 4."</span>
|
||||
<span class="preprocessor">#else</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span> <span class="identifier">the_compiler</span> <span class="special">=</span> <span class="string">"GNU GCC, less than version 4."</span>
|
||||
<span class="preprocessor">#endif</span>
|
||||
<span class="preprocessor">#else</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span> <span class="identifier">the_compiler</span> <span class="special">=</span> <span class="string">"Not GNU GCC."</span>
|
||||
<span class="preprocessor">#endif</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">the_compiler</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<h4>
|
||||
<a name="predef.using_the_predefs.h0"></a>
|
||||
<span><a name="predef.using_the_predefs.using_the_boost_version_number_m"></a></span><a class="link" href="using_the_predefs.html#predef.using_the_predefs.using_the_boost_version_number_m">Using the
|
||||
<code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code> macro</a>
|
||||
</h4>
|
||||
<p>
|
||||
All the predefs are defined to be a use of the <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code>
|
||||
macro. The macro takes individual major, minor, and patch value expressions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span> <span class="identifier">major</span><span class="special">,</span> <span class="identifier">minor</span><span class="special">,</span> <span class="identifier">patch</span> <span class="special">)</span> <span class="special">...</span>
|
||||
</pre>
|
||||
<p>
|
||||
The arguments are:
|
||||
</p>
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
Major version number, as a constant value expression in the range [0,99].
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Minor version number, as a constant value expression in the range [0,99].
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Patch-level version number, as a constant value expression in the range
|
||||
[0,99999].
|
||||
</li>
|
||||
</ol></div>
|
||||
<p>
|
||||
The ranges for each are "enforced" by the use of a modulo ("%"),
|
||||
i.e. truncation, as opposed to a clamp. And hence this means that the limits
|
||||
are enforced only enough to keep from having out-of-range problems. But not
|
||||
enough to prevent other kinds of problems. Like exceeding the range and getting
|
||||
false detections, or non-detections. It is up to the individual predefs to
|
||||
ensure correct usage beyond the range guarantee.
|
||||
</p>
|
||||
<p>
|
||||
The values for the arguments can be any preprocessor valid constant value expression.
|
||||
Only constant value arithmetic is used in the definition of the <code class="computeroutput"><span class="identifier">BOOST_VERSION_NUMBER</span></code> macro and in any of
|
||||
the other predef macros. This means that any allowed base is possible, i.e.
|
||||
binary, octal, decimal, and hexadecimal. For example:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">MY_APPLICATION_VERSION_NUMBER</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="number">0xA</span><span class="special">,</span><span class="number">015</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
Is equivalent to:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">MY_APPLICATION_VERSION_NUMBER</span> <span class="identifier">BOOST_VERSION_NUMBER</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="number">10</span><span class="special">,</span><span class="number">13</span><span class="special">)</span>
|
||||
</pre>
|
||||
</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 © 2005 Rene Rivera<br>Copyright © 2008-2011 Redshift
|
||||
Software Inc<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="introduction.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="adding_new_predefs.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in new issue
Block a user