doc/html/predef/check_utilities.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Check Utilities</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../predef.html" title="Chapter&#160;28.&#160;Boost.Predef 1.5">
  10 <link rel="prev" href="reference.html" title="Reference">
  11 <link rel="next" href="history.html" title="History">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="reference.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="history.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="predef.check_utilities"></a><a class="link" href="check_utilities.html" title="Check Utilities">Check Utilities</a>
  29 </h2></div></div></div>
  30 <p>
  31       The <code class="computeroutput"><span class="identifier">predef_check</span></code> utility provides
  32       a facility for building a program that will check a given set of expressions
  33       against the definitions it detected when it was built.
  34     </p>
  35 <h4>
  36 <a name="predef.check_utilities.h0"></a>
  37       <span class="phrase"><a name="predef.check_utilities.predef_check_programs"></a></span><a class="link" href="check_utilities.html#predef.check_utilities.predef_check_programs"><code class="literal">predef_check</code>
  38       programs</a>
  39     </h4>
  40 <p>
  41       Even though there is only one <code class="computeroutput"><span class="identifier">predef_check</span></code>
  42       program, there are variations for each of the languages that are detected by
  43       Predef to match the convention for sources files. For all of them one invokes
  44       with a list of expression arguments. The expressions are evaluated within the
  45       context of the particular <code class="literal">predef_check</code> program and if they
  46       all are true zero (0) is returned. Otherwise the index of the first false expression
  47       is returned.
  48     </p>
  49 <p>
  50       The expression syntax is simple:
  51     </p>
  52 <pre class="programlisting">predef-definition [ relational-operator version-value ]
  53 </pre>
  54 <p>
  55       <em class="replaceable"><code>predef-definition</code></em> can be any of the Predef definitions.
  56       For example <code class="computeroutput"><span class="identifier">BOOST_COMP_GCC</span></code>.
  57     </p>
  58 <p>
  59       <em class="replaceable"><code>relational-operator</code></em> can be any of: <code class="literal">&gt;</code>,
  60       <code class="literal">&lt;</code>, <code class="literal">&gt;=</code>, <code class="literal">&lt;=</code>,
  61       <code class="literal">==</code> and <code class="literal">!=</code>.
  62     </p>
  63 <p>
  64       <em class="replaceable"><code>version-number</code></em> can be a full or partial version
  65       triplet value. If it's a partial version triple it is completed with zeros.
  66       That is <code class="literal">x.y</code> is equivalent to <code class="literal">x.y.0</code> and
  67       <code class="literal">x</code> is equivalent to <code class="literal">x.0.0</code>.
  68     </p>
  69 <p>
  70       The <em class="replaceable"><code>relations-operator</code></em> and <em class="replaceable"><code>version-number</code></em>
  71       can be ommited. In which case it is equivalent to:
  72     </p>
  73 <pre class="programlisting">predef-definition &gt; 0.0.0
  74 </pre>
  75 <h4>
  76 <a name="predef.check_utilities.h1"></a>
  77       <span class="phrase"><a name="predef.check_utilities.using_with_boost_build"></a></span><a class="link" href="check_utilities.html#predef.check_utilities.using_with_boost_build">Using
  78       with Boost.Build</a>
  79     </h4>
  80 <p>
  81       You can use the <code class="literal">predef_check</code> programs directly from Boost
  82       Build to configure target requirements. This is useful for controlling what
  83       gets built as part of your project based on the detailed version information
  84       available in Predef. The basic use is simple:
  85     </p>
  86 <pre class="programlisting">import path-to-predef-src/tools/check/predef
  87     : check require
  88     : predef-check predef-require ;
  89
  90 exe my_windows_program : windows_source.cpp
  91     : [ predef-require "BOOST_OS_WINDOWS" ] ;
  92 </pre>
  93 <p>
  94       That simple use case will skip building the <code class="literal">my_windows_program</code>
  95       unless one is building for Windows. Like the direct <code class="literal">predef_check</code>
  96       you can pass mutiple expressions using relational comparisons. For example:
  97     </p>
  98 <pre class="programlisting">import path-to-predef-src/tools/check/predef
  99     : check require
 100     : predef-check predef-require ;
 101
 102 lib my_special_lib : source.cpp
 103     : [ predef-require "BOOST_OS_WINDOWS != 0" "BOOST_OS_VMS != 0"] ;
 104 </pre>
 105 <p>
 106       And in that case the <code class="literal">my_special_lib</code> is built only when the
 107       OS is not Windows or VMS. The <code class="literal">requires</code> rule is a special
 108       case of the <code class="literal">check</code> rule. And is defined in terms of it:
 109     </p>
 110 <pre class="programlisting">rule require ( expressions + : language ? )
 111 {
 112     return [ check $(expressions) : $(language) : : &lt;build&gt;no ] ;
 113 }
 114 </pre>
 115 <p>
 116       The expression can also use explicit "and", "or" logical
 117       operators to for more complex checks:
 118     </p>
 119 <pre class="programlisting">import path-to-predef-src/tools/check/predef
 120     : check require
 121     : predef-check predef-require ;
 122
 123 lib my_special_lib : source.cpp
 124     : [ predef-require "BOOST_OS_WINDOWS" or "BOOST_OS_VMS"] ;
 125 </pre>
 126 <p>
 127       You can use the <code class="literal">check</code> rule for more control and to implement
 128       something other than control of what gets built. The definition for the <code class="literal">check</code>
 129       rule is:
 130     </p>
 131 <pre class="programlisting">rule check ( expressions + : language ? : true-properties * : false-properties * )
 132 </pre>
 133 <p>
 134       When invoked as a reuirement of a Boost Build target this rule will add the
 135       <code class="literal">true-properties</code> to the target if all the <code class="literal">expressions</code>
 136       evaluate to true. Otherwise the <code class="literal">false-properties</code> get added
 137       as requirements. For example you could use it to enable or disable features
 138       in your programs:
 139     </p>
 140 <pre class="programlisting">import path-to-predef-src/tools/check/predef
 141     : check require
 142     : predef-check predef-require ;
 143
 144 exe my_special_exe : source.cpp
 145     : [ predef-check "BOOST_OS_WINDOWS == 0"
 146         : : &lt;define&gt;ENABLE_WMF=0
 147         : &lt;define&gt;ENABLE_WMF=1 ] ;
 148 </pre>
 149 <p>
 150       For both <code class="literal">check</code> and <code class="literal">require</code> the <code class="literal">language</code>
 151       argument controls which variant of the <code class="literal">predef_check</code> program
 152       is used to check the expressions. It defaults to "c++", but can be
 153       any of: "c", "cpp", "objc", and "objcpp".
 154     </p>
 155 </div>
 156 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 157 <td align="left"></td>
 158 <td align="right"><div class="copyright-footer">Copyright &#169; 2005-2016 Rene Rivera<br>Copyright &#169; 2015 Charly Chevalier<br>Copyright &#169; 2015 Joel Falcou<p>
 159         Distributed under the Boost Software License, Version 1.0. (See accompanying
 160         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>)
 161       </p>
 162 </div></td>
 163 </tr></table>
 164 <hr>
 165 <div class="spirit-nav">
 166 <a accesskey="p" href="reference.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="history.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 167 </div>
 168 </body>
 169 </html>