1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Build Time Configuration</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="boost_macro_reference.html" title="Boost Macro Reference"> 10<link rel="next" href="cstdint.html" title="Standard Integer Types"> 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="boost_macro_reference.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="cstdint.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.build_config"></a><a class="link" href="build_config.html" title="Build Time Configuration">Build Time Configuration</a> 28</h2></div></div></div> 29<p> 30 There are times when you want to control whether a build target gets built 31 or not, based on what features the compiler supports. For example, suppose 32 you have a test file "test_constexpr_128.cpp" which requires three 33 key features in order to build: 34 </p> 35<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 36<li class="listitem"> 37 The <code class="computeroutput"><span class="keyword">constexpr</span></code> keyword as detected 38 by BOOST_NO_CXX11_CONSTEXPR. 39 </li> 40<li class="listitem"> 41 User defined literals, as detected by BOOST_NO_CXX11_USER_DEFINED_LITERALS. 42 </li> 43<li class="listitem"> 44 The <code class="computeroutput"><span class="identifier">__int128</span></code> data type, 45 as detected by BOOST_HAS_INT128. 46 </li> 47</ul></div> 48<p> 49 Clearly we know that if these features are not supported by the compiler, then 50 there's simply no point in even trying to build the test program. The main 51 advantages being: 52 </p> 53<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 54<li class="listitem"> 55 Faster compile times - build configuration uses lightweight tests the results 56 of which are also cached. 57 </li> 58<li class="listitem"> 59 Less noise in build output - there's no reason to be faced with pages of 60 template instantiation backtrace if we know the file can never compile 61 anyway. 62 </li> 63<li class="listitem"> 64 Less noise in the online test results - the test will show up as blank, 65 rather than as a fail in the online test matrix. 66 </li> 67<li class="listitem"> 68 A better experience for end users building all of Boost, if those libraries 69 which can not be built for the current target compiler are simply skipped, 70 rather than generating pages of error output. 71 </li> 72</ul></div> 73<p> 74 Returning to our example, the test case is probably executed in it's Jamfile 75 via the "run" rule: 76 </p> 77<pre class="programlisting"><span class="identifier">run</span> <span class="identifier">test_constexpr_128</span><span class="special">.</span><span class="identifier">cpp</span> <span class="special">;</span> 78</pre> 79<p> 80 We now need to make this target conditional on the necessary features. We can 81 do that by first importing the necessary rule at the start of the Jamfile: 82 </p> 83<pre class="programlisting"><span class="identifier">import</span> <span class="identifier">path</span><span class="special">-</span><span class="identifier">to</span><span class="special">-</span><span class="identifier">config</span><span class="special">-</span><span class="identifier">lib</span><span class="special">/</span><span class="identifier">checks</span><span class="special">/</span><span class="identifier">config</span> <span class="special">:</span> <span class="identifier">requires</span> <span class="special">;</span> 84</pre> 85<p> 86 Assuming that the test case is in the usual directory: 87 </p> 88<pre class="programlisting"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">yourlib</span><span class="special">/</span><span class="identifier">test</span> 89</pre> 90<p> 91 then the import rule will actually be: 92 </p> 93<pre class="programlisting"><span class="identifier">import</span> <span class="special">../../</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">checks</span><span class="special">/</span><span class="identifier">config</span> <span class="special">:</span> <span class="identifier">requires</span> <span class="special">;</span> 94</pre> 95<p> 96 Then add a "requires" rule invocation to the requirements section 97 of the target: 98 </p> 99<pre class="programlisting"><span class="identifier">run</span> <span class="identifier">test_constexpr_128</span><span class="special">.</span><span class="identifier">cpp</span> 100 <span class="special">:</span> <span class="special">:</span> <span class="special">:</span> <span class="special">#</span><span class="identifier">requirements</span><span class="special">:</span> 101 <span class="special">[</span> <span class="identifier">requires</span> <span class="identifier">cxx11_constexpr</span> <span class="identifier">cxx11_user_defined_literals</span> <span class="identifier">int128</span> <span class="special">]</span> <span class="special">;</span> 102</pre> 103<p> 104 Notice that multiple arguments can be added to the requires rule, and that 105 these are always the same as the Boost.Config macro name, but in lower case 106 and with the <span class="emphasis"><em>boost_no_</em></span> or <span class="emphasis"><em>boost_has_</em></span> 107 prefix removed. You can also use any C++ standard feature-macro name with the 108 leading underscores removed (see more below). 109 </p> 110<p> 111 When building the above example, you will see at the start of the build process 112 the results of the configuration, for example GCC in C++11 mode gives: 113 </p> 114<pre class="programlisting"><span class="special">-</span> <span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Config</span> <span class="identifier">Feature</span> <span class="identifier">Check</span><span class="special">:</span> <span class="identifier">int128</span> <span class="special">:</span> <span class="identifier">yes</span> 115<span class="special">-</span> <span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Config</span> <span class="identifier">Feature</span> <span class="identifier">Check</span><span class="special">:</span> <span class="identifier">cxx11_constexpr</span> <span class="special">:</span> <span class="identifier">yes</span> 116<span class="special">-</span> <span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Config</span> <span class="identifier">Feature</span> <span class="identifier">Check</span><span class="special">:</span> <span class="identifier">cxx11_user_defined_literals</span> <span class="special">:</span> <span class="identifier">yes</span> 117</pre> 118<p> 119 If you wish to make a build conditional on a C++ standard feature macro then 120 you can specify these too, just remove the leading underscores from the name. 121 For example: 122 </p> 123<pre class="programlisting"><span class="special">[</span> <span class="identifier">requires</span> <span class="identifier">cpp_constexpr</span> <span class="special">]</span> 124</pre> 125<p> 126 To require C++11 style const-expressions. If you want to specify a macro from 127 a particular standard, then you append an underscore followed by the (2 digit) 128 year of the standard, for example: 129 </p> 130<pre class="programlisting"><span class="special">[</span> <span class="identifier">requires</span> <span class="identifier">cpp_constexpr_17</span> <span class="special">]</span> 131</pre> 132<p> 133 For C++17 constepxr. If you don't specify a standard then you get the first 134 version that introduced the macro. In addition there are only standard-specific 135 rules for each version bump of the macro, so: 136 </p> 137<pre class="programlisting"><span class="special">[</span> <span class="identifier">requires</span> <span class="identifier">cpp_if_constexpr_17</span> <span class="special">]</span> 138</pre> 139<p> 140 Is fine since the macro was introduced in C++17 and is the same as the un-versioned 141 name, but: 142 </p> 143<pre class="programlisting"><span class="special">[</span> <span class="identifier">requires</span> <span class="identifier">cpp_if_constexpr_20</span> <span class="special">]</span> 144</pre> 145<p> 146 Will result in a build error since there is no C++20 version bump for <code class="computeroutput"><span class="identifier">__cpp_if_constexpr</span></code>. 147 </p> 148<p> 149 That's all there is to this handy feature, should at any time you be unsure 150 of the feature-test names you can pass to the "requires" rule, then 151 search for the Boost.Config macro of interest in libs/config/checks/Jamfiles.v2, 152 and the name of the feature check will follow it. 153 </p> 154<p> 155 And finally, this feature is built around the Boost.Build built in rule <span class="emphasis"><em>check-target-builds</em></span> 156 which can be used to perform more generalized build-time feature testing. The 157 checks in this library are provided as a convenient shorthand without the need 158 for you to write the test cases yourself. 159 </p> 160</div> 161<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 162<td align="left"></td> 163<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John 164 Maddock<p> 165 Distributed under the Boost Software License, Version 1.0. (See accompanying 166 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>) 167 </p> 168</div></td> 169</tr></table> 170<hr> 171<div class="spirit-nav"> 172<a accesskey="p" href="boost_macro_reference.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="cstdint.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 173</div> 174</body> 175</html> 176
