diff options
Diffstat (limited to 'doc/html/predef/adding_new_predefs.html')
| -rw-r--r-- | doc/html/predef/adding_new_predefs.html | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/doc/html/predef/adding_new_predefs.html b/doc/html/predef/adding_new_predefs.html new file mode 100644 index 0000000000..ee217c543d --- /dev/null +++ b/doc/html/predef/adding_new_predefs.html @@ -0,0 +1,313 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Adding new predefs</title> +<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> +<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> +<link rel="up" href="../predef.html" title="Chapter 26. Boost.Predef 1.4.1"> +<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"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> +<td align="center"><a href="../../../index.html">Home</a></td> +<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="using_the_predefs.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../predef.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="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="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 class="phrase"><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" style="list-style-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_NOT_AVAILABLE</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_AVAILABLE</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 define <code class="computeroutput"><span class="special">*</span><span class="identifier">_AVAILABLE</span></code> + macros as needed. + </li> +<li class="listitem"> + The predef must define a symbolic constant string name macro. + </li> +<li class="listitem"> + The predef must declare itself, after being defined, for the testing system. + </li> +<li class="listitem"> + The predef must guarantee that it is the only one defined as detected per + category. + </li> +<li class="listitem"> + But a predef can define <code class="computeroutput"><span class="special">*</span><span class="identifier">_EMULATED</span></code> macros to indicate that it + was previously detected by another header and is being "emulated" + by the system. Note that the <code class="computeroutput"><span class="special">*</span><span class="identifier">_AVAILABLE</span></code> macros must still be defined + in this situation. + </li> +</ul></div> +<p> + And there are some extra guidelines that predef headers should follow: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-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 class="phrase"><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> + If the detection depends on the detection of another predef you should include + those headers here. + </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">CATEGORY_TAG</span><span class="special">/</span><span class="identifier">DEPENDENCY</span><span class="special">.</span><span class="identifier">h</span><span class="special">></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_NOT_AVAILABLE</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_AVAILABLE</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_AVAILABLE</span> +<span class="preprocessor"># endif</span> +<span class="preprocessor">#endif</span> +</pre> +<p> + We also need to provide the <code class="computeroutput"><span class="special">*</span><span class="identifier">_AVAILABLE</span></code> versions of the predef. + </p> +<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">BOOST_category_tag</span> +<span class="preprocessor"># define</span> <span class="identifier">BOOST_category_tag_AVAILABLE</span> +<span class="preprocessor">#endif</span> +</pre> +<p> + And for convenience we also want to provide a <code class="computeroutput"><span class="special">*</span><span class="identifier">_NAME</span></code> macro: + </p> +<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_catagory_tag_NAME</span> <span class="string">"Name"</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="identifier">BOOST_category_tag_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 class="phrase"><a name="predef.adding_new_predefs.adding_exclusive_predefs"></a></span><a class="link" href="adding_new_predefs.html#predef.adding_new_predefs.adding_exclusive_predefs">Adding + exclusive predefs</a> + </h4> +<p> + For headers of predefs that need to be mutually exclusive in the detection + we need to add checks and definitions to detect when the predef is detected + by multiple headers. + </p> +<p> + Internally compiler, operating system, and platforms define <code class="computeroutput"><span class="identifier">BOOST_PREDEF_DETAIL_COMP_DETECTED</span></code>, + <code class="computeroutput"><span class="identifier">BOOST_PREDEF_DEFAIL_OS_DETECTED</span></code>, + and <code class="computeroutput"><span class="identifier">BOOST_PREDEF_DETAIL_PLAT_DETECTED</span></code> + respectively when the predef is first detected. This is used to guard against + multiple definition of the detection in later included headers. In those cases + the detection would instead be written as: + </p> +<pre class="programlisting"><span class="preprocessor">#if</span> <span class="special">!</span><span class="identifier">BOOST_PREDEF_DETAIL_category_DETECTED</span> <span class="special">&&</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> + And we also include a header that defines the <code class="computeroutput"><span class="special">*</span><span class="identifier">_DETECTED</span></code> macro when we have the detection: + </p> +<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">BOOST_category_tag</span> +<span class="preprocessor"># define</span> <span class="identifier">BOOST_category_tag_AVAILABLE</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">detail</span><span class="special">/</span><span class="identifier">CATEGORY_detected</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span> +<span class="preprocessor">#endif</span> +</pre> +<p> + Everything else about the header is the same as the basic detection header. + </p> +<h4> +<a name="predef.adding_new_predefs.h3"></a> + <span class="phrase"><a name="predef.adding_new_predefs.adding_an_exclusive_but_emulated"></a></span><a class="link" href="adding_new_predefs.html#predef.adding_new_predefs.adding_an_exclusive_but_emulated">Adding + an exclusive but emulated predef</a> + </h4> +<p> + Because compilers are frequently emulated by other compilers we both want to + have exclusive detection of the compiler and also provide information that + we detected the emulation of the compiler. To accomplish this we define a local + <code class="computeroutput"><span class="special">*</span><span class="identifier">_DETECTION</span></code> + macro for the compiler detection. And conditionally define either the base + compiler predef <code class="computeroutput"><span class="identifier">BOOST_COMP_compiler</span></code> + or the alternate <code class="computeroutput"><span class="identifier">BOOST_COMP_compiler_EMULATED</span></code> + predef. + </p> +<p> + The initial detection would look like: + </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"># 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_COMP_tag_DETECTION</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_COMP_tag_DETECTION</span> <span class="identifier">BOOST_VERSION_NUMBER_AVAILABLE</span> +<span class="preprocessor"># endif</span> +<span class="preprocessor">#endif</span> +</pre> +<p> + And then we can conditionally define the base or emulated predefs: + </p> +<pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">BOOST_COMP_tag_DETECTION</span> +<span class="preprocessor"># if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_PREDEF_DETAIL_COMP_DETECTED</span><span class="special">)</span> +<span class="preprocessor"># define</span> <span class="identifier">BOOST_COMP_tag_EMULATED</span> <span class="identifier">BOOST_COMP_tag_DETECTION</span> +<span class="preprocessor"># else</span> +<span class="preprocessor"># undef</span> <span class="identifier">BOOST_COMP_tag</span> +<span class="preprocessor"># define</span> <span class="identifier">BOOST_COMP_tag</span> <span class="identifier">BOOST_COMP_tag_DETECTION</span> +<span class="preprocessor"># endif</span> +<span class="preprocessor"># define</span> <span class="identifier">BOOST_category_tag_AVAILABLE</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">detail</span><span class="special">/</span><span class="identifier">comp_detected</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span> +<span class="preprocessor">#endif</span> +</pre> +<h4> +<a name="predef.adding_new_predefs.h4"></a> + <span class="phrase"><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 utility 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 decomposed and defined as: + </p> +<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_CCOMP_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, 2008-2016 Rene Rivera<br>Copyright © 2015 Charly Chevalier<br>Copyright © 2015 Joel Falcou<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="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../predef.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="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> |