1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<title>Compile Time Configuration</title> 5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 6<link href="theme/style.css" rel="stylesheet" type="text/css"> 7</head> 8 9<body> 10<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif"> 11 <tr> 12 <td width="21"> <h1></h1></td> 13 <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">Compile 14 Time Configuration</font></b></font></td> 15 <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td> 16 </tr> 17</table> 18<br> 19<table border="0"> 20 <tr> 21 <td width="10"></td> 22 <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> 23 <td width="30"><a href="macro_expansion_process.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td> 24 <td width="30"><a href="samples.html"><img src="theme/r_arr.gif" border="0"></a></td> 25 </tr> 26</table> 27<p><b><a name="compiletime_config"></a>Library compile time configuration</b></p> 28<P dir="ltr">The C++ preprocessor iterator library may be configured at compile 29 time by specifying different preprocessor constants to include different additional 30 features. The possible preprocessor constants are described in the following 31 table. </P> 32<table width="100%" border="0" align="center"> 33 <tr> 34 <td colspan="2" class="table_title"><b>Summary of possible preprocessor constants 35 for<br> 36 library configuration</b></td> 37 </tr> 38 <tr> 39 <td width="46%" class="table_cells"><code>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</code></td> 40 <td width="54%" class="table_cells"> <p>Support the <span class="preprocessor">#warning</span> directive</p></td> 41 </tr> 42 <tr> 43 <td width="46%" class="table_cells"><code>BOOST_WAVE_SUPPORT_MS_EXTENSIONS</code></td> 44 <td width="54%" class="table_cells"> <p>Support several MS specific language 45 extensions (i.e. <tt>__int8</tt> et.al.)</p></td> 46 </tr> 47 <tr> 48 <td class="table_cells"><code>BOOST_WAVE_PREPROCESS_ERROR_MESSAGE_BODY</code></td> 49 <td class="table_cells"><p>Enable the preprocessing of the message bodies 50 of <span class="preprocessor">#error</span> and <span class="preprocessor">#warning</span> 51 directives.</p></td> 52 </tr> 53 <tr> 54 <td class="table_cells"><code>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</code></td> 55 <td class="table_cells"><p>If defined, then the <span class="preprocessor">#pragma</span> 56 directives are returned as a token sequence to the caller, if not defined, 57 the whole <span class="preprocessor">#pragma</span> directive is skipped. </p></td> 58 </tr> 59 <tr> 60 <td class="table_cells"><code>BOOST_WAVE_PREPROCESS_PRAGMA_BODY</code></td> 61 <td class="table_cells"><p>Enable the preprocessing of the bodies of all <span class="preprocessor"> 62 #pragma</span> directives.<br> 63 Note though, that the body of an <tt>operator _Pragma()</tt> is always preprocessed as this is required by the C99 Standard <a href="references.html#iso_c">[2]</a>. 64 </p></td> 65 </tr> 66 <tr> 67 <td class="table_cells"><code>BOOST_WAVE_ENABLE_COMMANDLINE_MACROS</code></td> 68 <td class="table_cells"><p>Enable the functionality required to define macros 69 with the command line syntax (-DMACRO(x)=definition)</p></td> 70 </tr> 71 <tr> 72 <td class="table_cells"><code>BOOST_WAVE_STRINGTYPE</code></td> 73 <td class="table_cells"><p>The tokens generated by the <tt>Wave</tt> library 74 contain the token data and the file position, where this token was found 75 in the input stream. <br> 76 This constant may be used to redefine the data type, which is used to 77 hold the token data and the corresponding file name. If this isn't defined 78 it defaults to std::string. (The here defined data type should be compatible 79 to the std::string type)</p></td> 80 </tr> 81 <tr> 82 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_VARIADICS_PLACEMARKERS</code></td> 83 <td class="table_cells"><p>If defined, then the preprocessor library supports 84 variadics and placemarkers. Note, to support C99 mode, this constant must 85 be defined too.</p></td> 86 </tr> 87<tr> 88 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_CPP0X</code></td> 89 <td class="table_cells"><p>If defined, then the preprocessor library supports 90 C++0x keywords and C++0x specific features, such as variadics, placemarkers, extended character and string literals. This implies the definitions of the <code>BOOST_WAVE_SUPPORT_VARIADICS_PLACEMARKERS</code> constant.</p></td> 91 </tr> <tr> 92 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_CPP1Z</code></td> 93 <td class="table_cells"><p>If defined, then the preprocessor library supports 94 C++17 keywords - currently just <code>__has_include</code>. It implies <code>BOOST_WAVE_SUPPORT_CPP0X</code>.</p></td> 95 </tr> 96 </tr> <tr> 97 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_CPP2A</code></td> 98 <td class="table_cells"><p>If defined, then the preprocessor library supports 99 C++20 keywords, specifically <code>__VA_OPT__</code>. It implies <code>BOOST_WAVE_SUPPORT_CPP1Z</code>.</p></td> 100 </tr> 101 </tr> <tr> 102 <td class="table_cells"><code>BOOST_WAVE_MAX_INCLUDE_LEVEL_DEPTH</code></td> 103 <td class="table_cells"><p>If defined, it will determine the initial maximal 104 possible include file nesting depth supported. It defaults to 1024.</p></td> 105 </tr> 106 <tr> 107 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_PRAGMA_ONCE</code></td> 108 <td class="table_cells"><p>If defined, then the <code>#pragma once</code> directive is supported by <tt>Wave</tt>. This specifies that the file, in which the pragma resides, will be included 109 (opened) only once by the compiler in a build. </p></td> 110 </tr> 111 <tr> 112 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE</code></td> 113 <td class="table_cells"><p>If defined, then the <code class="preprocessor">#pragma message("")</code> directive is supported by <tt>Wave</tt>. This pragma simply generates a remark cotaining the message text. The body of the #pragma message is preprocessed whenever the <code><code>BOOST_</code>WAVE_PREPROCESS_PRAGMA_BODY</code> constant is defined as well . </p></td> 114 </tr> 115 <tr> 116 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</code></td> 117 <td class="table_cells"><p>If defined, then the <code>#include_next</code> directive is supported by <tt>Wave</tt>. This is syntactically equivalent to the <code class="preprocessor">#include</code> directives, but may be used to inherit a header file (i.e. to include a file, which is named as the current file containing the <code>#include_next</code>).</p></td> 118 </tr> 119 <tr> 120 <td class="table_cells"><code>BOOST_WAVE_USE_STRICT_LEXER</code></td> 121 <td class="table_cells"><p>If this is defined to something != 0, then the C/C++ lexers recognize the 122 strict C99/C++ basic source character set. If it is not defined or defined 123 to zero, the lexers recognize the <span class="string">'$'</span> character as part of identifiers.</p></td> 124 </tr> 125 <tr> 126 <td class="table_cells"><code>BOOST_WAVE_PRAGMA_KEYWORD</code></td> 127 <td class="table_cells"><p>If this is defined to a string literal it will be used as the pragma keyword recogniyed by the library as specific Wave pragmas. This constant defaults to <span class="literal">"wave"</span>, i.e. the library recognizes all <span class="preprocessor">#pragma wave option [(argument)]</span> directives and dispatches the handling to the interpret_pragma() preprocessing hook function (see: <a href="class_reference_ctxpolicy.html">Preprocessing Hooks</a>). The arguments part of the pragma is optional.<br> 128 </p> </td> 129 </tr> 130 <tr> 131 <td class="table_cells"><code>BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS</code></td> 132 <td class="table_cells"><p>If defined to something not equal to zero (<span class="literal">'0'</span>) Wave will be compiled to use the depreciated preprocessing hooks. The interface of the preprocessing hooks has been changed after the Boost V1.34.x releases. This constant allows to compile applications using the older interface. </p></td> 133 </tr> 134 <tr> 135 <td class="table_cells"><code>BOOST_WAVE_SUPPORT_LONGLONG_INTEGER_LITERALS</code></td> 136 <td class="table_cells"><p>The C++ standard requires the preprocessor to use one of the following 137 types for integer literals: <code>long</code> or <code>unsigned long</code> depending on a optional 138 suffix (<span class="literal">'u'</span>, <span class="literal">'l'</span>, <span class="literal">'ul'</span>, or <span class="literal">'lu'</span>). Sometimes it is required to preprocess integer literals larger than that 139 (i.e. <code>long long</code> or <code>unsigned long long</code>). Defining this pp constant enables the recognition of long long integers 140even if these do not have the <span class="literal">'ll'</span> suffix.</p> 141 <p>This preprocessor constant is effective only, if your target platform supports 142 long long integers (<code>BOOST_HAS_LONG_LONG</code> is defined). Please note, that this setting doesn't relate to the Wave support option 143 <code>support_option_long_long</code>, which enables the recognition of <span class="literal">'ll'</span> suffixes 144 only. 145 </p> 146 </td> 147 </tr> 148 <tr> 149 <td class="table_cells"> 150 <code>BOOST_WAVE_SUPPORT_THREADING</code></td> 151 <td class="table_cells"> 152 <p>This preprocessor constant allows to configer whether the Wave library will be built 153 with threading support enabled or not. This value (if defined) should be set to 154 zero ('0') if threading needs to be disabled and to a numerical value not equal 155 to zero, if threading should be enabled explicitly. 156 </p> 157 <p> 158 If this constant is not defined, the Wave library will be built using the threading 159 as picked up from the Boost build environment (see <code>BOOST_HAS_THREADS</code> in the Boost 160 configuration dosumentation).</p> 161 </td> 162 </tr> 163</table> 164<P dir="ltr"><b><a name="using_custom_lexer"></a>Using a different token type or lexer type in conjunction with Wave </b></P> 165<P dir="ltr">It is possible to use the <tt>Wave</tt> library while using your own token and/or lexer types. This may be achieved by providing your lexer type as the second template parameter while instantiating the <tt>boost::wave::context<></tt> object. The token type used by the library is derived from the <tt>token_type</tt> typedef to be provided by the lexer type. If you want to provide your own token type only, you may use the <tt>boost::wave::lex_iterator<></tt> type contained with the library. This type needs to be parameterized with the token type to use. </P> 166<P dir="ltr">The <tt>Wave</tt> library contains several samples illustrating these possibilities. The <tt>cpp_tokens</tt> sample shows the usage of a custom lexer and a custom token types. The lexer type used is functionally fully compatible to the <tt>re2c</tt> <a href="references.html#re2c">[3]</a> based lexer used by default. It is implemented based on the <tt>SLex</tt> <a href="references.html#slex">[5]</a> lexer example written by Dan Nuffer. The token type used therein is functionally equivalent to the default token type except for an additional <tt>operator<<</tt> used for dumping the information carried by the token.</P> 167<P dir="ltr"><b><a name="compilation_models"></a>Separation and inclusion compilation 168 models</b></P> 169<P dir="ltr">The <tt>Wave</tt> C++ preprocessor iterator library is build almost 170 completely as a header only library (except for the re2c based lexer). If you're 171 trying to include all required files at once you will mention, that the resulting 172 compilation times are very large (up to an hour - depending on your system configuration). 173 This straightforward method we'll call the inclusion compilation model. If you 174 do not pay attention to compilation times, that's the way to go, no special 175 handling is needed.</P> 176<P dir="ltr">If you're interested in decreasing compilation times, the following 177 method is to be used. This we will call it the separation compilation model. 178 The trick is to separate the different objects such, that they are compilable 179 separately. The function, which instantiates the templated object in question 180 is factored out such, that its definition is visible to only one translation 181 unit. To simplify this further this creation function is packaged into a small 182 generator template structure.</P> 183<P dir="ltr">There are two levels of separation implemented: the separation of 184 the compilation of the C++ lexer and the separation of the compilation of the 185 different Spirit grammars used. To use these separations you will have to define 186 two preprocessor constants while compiling the whole application and you will 187 have to explicitly instantiate some helper templates. The following tables 188 shows these constants in detail.</P> 189<table width="90%" border="0" align="center"> 190 <tr> 191 <td colspan="2" class="table_title"><b>Summary of possible compilation constants 192 required <br> 193 to enable the separation compilation model</b></td> 194 </tr> 195 <tr class="table_title"> 196 <td width="25%"><b>Separate</b></td> 197 <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Preprocessor 198 constant</font></code></p></td> 199 </tr> 200 <tr> 201 <td width="25%" class="table_cells"><code>C++ lexer</code></td> 202 <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_LEXER_INSTANTIATION</code></p></td> 203 </tr> 204 <tr> 205 <td width="25%" class="table_cells"><code>Spirit grammars</code></td> 206 <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_GRAMMAR_INSTANTIATION</code></p></td> 207 </tr> 208</table> 209<P dir="ltr">The following table shows the explicit template instantiations required, 210 if you want to use the separation compilation model. The <tt>TokenT</tt> placeholder 211 type has to be replaced with your token type to use and the <code><tt>LexIteratorT</tt></code> placeholder type has to be replaced with your lex iterator type you've used while instantiation of the <tt>boost::wave::context<></tt> object. You will achieve the best 212 results, if you place these into separate compilation units each. The <tt>IteratorT</tt> 213 placeholder should be replaced by the iterator type, which was used to instantiate 214 the <tt>boost::wave::context<></tt> object.</P> 215<table width="90%" border="0" align="center"> 216 <tr> 217 <td colspan="2" class="table_title"><b>Summary of required explicit template 218 instantiations <br> 219 required when using the separation compilation model</b></td> 220 </tr> 221 <tr class="table_title"> 222 <td width="25%"><b>Separate</b></td> 223 <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Templates 224 to explicitly instantiate</font></code></p></td> 225 </tr> 226 <tr> 227 <td width="25%" class="table_cells"><code>C++ lexer</code></td> 228 <td width="75%" class="table_cells"> <code><span class="keyword">template</span> 229 cpplexer::re2clex::new_lexer_gen<<tt>IteratorT</tt>>;</code></td> 230 </tr> 231 <tr> 232 <td width="25%" class="table_cells"><code>Spirit grammars</code></td> 233 <td width="75%" class="table_cells"> <p><code><span class="keyword">template</span> wave::grammars::expression_grammar_gen<<tt>TokenT</tt>>;<br> 234 <span class="keyword"> template</span> wave::grammars::intlit_grammar_gen<<tt>TokenT</tt>>;<br> 235 <span class="keyword"> template</span> wave::grammars::chlit_grammar_gen<<tt>TokenT</tt>>;<br> 236 <span class="keyword"> template</span> wave::grammars::cpp_grammar_gen<<tt>LexIteratorT</tt>>;<br> 237 <span class="keyword"> template</span> wave::grammars::predefined_macros_grammar_gen<<tt>LexIteratorT</tt>>;<br> 238 <span class="keyword"> template</span> wave::grammars::defined_grammar_gen<<tt>LexIteratorT</tt>>;</code></p></td> 239 </tr> 240</table> 241<p>To see an example of this you can look at the <tt>Wave</tt> driver program 242 included as an acompanion sample to the C++ preprocessor iterator library. The 243 corresponding files are named obviously <span class="string">"instantiate_...something.cpp"</span>, 244 where the <span class="string">'...somthing'</span> is a hint, which grammars 245 are explicitly instantiated inside. By using the separation model the compilation 246 times required to build the <tt>Wave</tt> example are dropped by up to 90%.</p> 247<P dir="ltr"><b><a name="compiler_requirements"></a>Compiler Requirements</b></P> 248<p>Beginning with version 1.77, Wave will require building with C++11 features, and will no longer support the use of older compilers. However, Wave will continue to <em>emulate</em> the features of older preprocessors indefinitely.<p> 249<table border="0"> 250 <tr> 251 <td width="10"></td> 252 <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> 253 <td width="30"><a href="macro_expansion_process.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td> 254 <td width="30"><a href="samples.html"><img src="theme/r_arr.gif" border="0"></a></td> 255 </tr> 256</table> 257<hr size="1"> 258<p class="copyright">Copyright © 2003-2011 Hartmut Kaiser<br> 259 <br> 260<font size="2">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) </font> </p> 261<span class="updated"></span> 262<p class="copyright"><span class="updated">Last updated: 263 <!-- #BeginDate format:fcAm1m -->Sunday, January 9, 2011 16:16<!-- #EndDate --> 264</span></p> 265</body> 266</html> 267
