| 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="supported_pragmas.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 #warning directive</p></td> |
|---|
| 41 | </tr> |
|---|
| 42 | <tr> |
|---|
| 43 | <td width="46%" class="table_cells"><code><code>BOOST_</code>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><code>BOOST_</code>WAVE_PREPROCESS_ERROR_MESSAGE_BODY</code></td> |
|---|
| 49 | <td class="table_cells"><p>Enable the preprocessing of the message bodies |
|---|
| 50 | of <span class="keyword">#error</span> and <span class="keyword">#warning</span> |
|---|
| 51 | directives.</p></td> |
|---|
| 52 | </tr> |
|---|
| 53 | <tr> |
|---|
| 54 | <td class="table_cells"><code><code>BOOST_</code>WAVE_RETURN_PRAGMA_DIRECTIVES</code></td> |
|---|
| 55 | <td class="table_cells"><p>If defined, then the <span class="keyword">#pragma</span> |
|---|
| 56 | directives are returned as a token sequence to the caller, if not defined, |
|---|
| 57 | the whole <span class="keyword">#pragma</span> directive is skipped. </p></td> |
|---|
| 58 | </tr> |
|---|
| 59 | <tr> |
|---|
| 60 | <td class="table_cells"><code><code>BOOST_</code>WAVE_PREPROCESS_PRAGMA_BODY</code></td> |
|---|
| 61 | <td class="table_cells"><p>Enable the preprocessing of the bodies of <span class="keyword"> |
|---|
| 62 | #pragma</span> directives.<br> |
|---|
| 63 | Note though, that the body of an <tt>operator _Pragma()</tt> is preprocessed |
|---|
| 64 | always, as required by the C99 Standard <a href="references.html#iso_c">[2]</a>. |
|---|
| 65 | </p></td> |
|---|
| 66 | </tr> |
|---|
| 67 | <tr> |
|---|
| 68 | <td class="table_cells"><code><code>BOOST_</code>WAVE_ENABLE_COMMANDLINE_MACROS</code></td> |
|---|
| 69 | <td class="table_cells"><p>Enable the functionality required to define macros |
|---|
| 70 | with the command line syntax (-DMACRO(x)=definition)</p></td> |
|---|
| 71 | </tr> |
|---|
| 72 | <tr> |
|---|
| 73 | <td class="table_cells"><code><code>BOOST_</code>WAVE_STRINGTYPE</code></td> |
|---|
| 74 | <td class="table_cells"><p>The tokens generated by the <tt>Wave</tt> library |
|---|
| 75 | contain the token data and the file position, where this token was found |
|---|
| 76 | in the input stream. <br> |
|---|
| 77 | This constant may be used to redefine the data type, which is used to |
|---|
| 78 | hold the token data and the corresponding file name. If this isn't defined |
|---|
| 79 | it defaults to std::string. (The here defined data type should be compatible |
|---|
| 80 | to the std::string type)</p></td> |
|---|
| 81 | </tr> |
|---|
| 82 | <tr> |
|---|
| 83 | <td class="table_cells"><code><code>BOOST_</code>WAVE_SUPPORT_VARIADICS_PLACEMARKERS</code></td> |
|---|
| 84 | <td class="table_cells"><p>If defined, then the preprocessor library supports |
|---|
| 85 | variadics and placemarkers. Note, to support C99 mode, this constant must |
|---|
| 86 | be defined too.</p></td> |
|---|
| 87 | </tr> |
|---|
| 88 | <tr> |
|---|
| 89 | <td class="table_cells"><code><code>BOOST_</code>WAVE_MAX_INCLUDE_LEVEL_DEPTH</code></td> |
|---|
| 90 | <td class="table_cells"><p>If defined, it will determine the initial maximal |
|---|
| 91 | possible include file nesting depth supported. It defaults to 1024.</p></td> |
|---|
| 92 | </tr> |
|---|
| 93 | <tr> |
|---|
| 94 | <td class="table_cells"><code><code>BOOST_</code>WAVE_SUPPORT_PRAGMA_ONCE</code></td> |
|---|
| 95 | <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 |
|---|
| 96 | (opened) only once by the compiler in a build. </p></td> |
|---|
| 97 | </tr> |
|---|
| 98 | <tr> |
|---|
| 99 | <td class="table_cells"><code>BOOST_</code><code>WAVE_SUPPORT_INCLUDE_NEXT</code></td> |
|---|
| 100 | <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>#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> |
|---|
| 101 | </tr> |
|---|
| 102 | </table> |
|---|
| 103 | <P dir="ltr"><b><a name="using_custom_lexer"></a>Using a different token type or lexer type in conjunction with Wave </b></P> |
|---|
| 104 | <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 parametrized with the token type to use. </P> |
|---|
| 105 | <P dir="ltr">To show, how this may be done, the <tt>Wave</tt> library contains several samples illustrating this possibility. 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> |
|---|
| 106 | <P dir="ltr"><b><a name="compilation_models"></a>Separation and inclusion compilation |
|---|
| 107 | models</b></P> |
|---|
| 108 | <P dir="ltr">The <tt>Wave</tt> C++ preprocessor iterator library is build almost |
|---|
| 109 | completely as a header only library (except for the re2c based lexer). If you're |
|---|
| 110 | trying to include all required files at once you will mention, that the resulting |
|---|
| 111 | compilation times are very large (up to an hour - depending on your system configuration). |
|---|
| 112 | This straightforward method we'll call the inclusion compilation model. If you |
|---|
| 113 | do not pay attention to compilation times, that's the way to go, no special |
|---|
| 114 | handling is needed.</P> |
|---|
| 115 | <P dir="ltr">If you're interested in decreasing compilation times, the following |
|---|
| 116 | method is to be used. This we will call it the separation compilation model. |
|---|
| 117 | The trick is to separate the different objects such, that they are compilable |
|---|
| 118 | separately. The function, which instantiates the templated object in question |
|---|
| 119 | is factored out such, that its definition is visible to only one translation |
|---|
| 120 | unit. To simplify this further this creation function is packaged into a small |
|---|
| 121 | generator template structure.</P> |
|---|
| 122 | <P dir="ltr">There are two levels of separation implemented: the separation of |
|---|
| 123 | the compilation of the C++ lexer and the separation of the compilation of the |
|---|
| 124 | different Spirit grammars used. To use these separations you will have to define |
|---|
| 125 | two preprocessor constants while compiling the whole application and you will |
|---|
| 126 | have to explicitely instantiate some helper templates. The following tables |
|---|
| 127 | shows these constants in detail.</P> |
|---|
| 128 | <table width="90%" border="0" align="center"> |
|---|
| 129 | <tr> |
|---|
| 130 | <td colspan="2" class="table_title"><b>Summary of possible compilation constants |
|---|
| 131 | required <br> |
|---|
| 132 | to enable the separation compilation model</b></td> |
|---|
| 133 | </tr> |
|---|
| 134 | <tr class="table_title"> |
|---|
| 135 | <td width="25%"><b>Separate</b></td> |
|---|
| 136 | <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Preprocessor |
|---|
| 137 | constant</font></code></p></td> |
|---|
| 138 | </tr> |
|---|
| 139 | <tr> |
|---|
| 140 | <td width="25%" class="table_cells"><code>C++ lexer</code></td> |
|---|
| 141 | <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_LEXER_INSTANTIATION</code></p></td> |
|---|
| 142 | </tr> |
|---|
| 143 | <tr> |
|---|
| 144 | <td width="25%" class="table_cells"><code>Spirit grammars</code></td> |
|---|
| 145 | <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_GRAMMAR_INSTANTIATION</code></p></td> |
|---|
| 146 | </tr> |
|---|
| 147 | </table> |
|---|
| 148 | <P dir="ltr">The following table shows the explicit template instantiations required, |
|---|
| 149 | if you want to use the separation compilation model. The <tt>TokenT</tt> placeholder |
|---|
| 150 | 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 |
|---|
| 151 | results, if you place these into separate compilation units each. The <tt>IteratorT</tt> |
|---|
| 152 | placeholder should be replaced by the iterator type, which was used to instantiate |
|---|
| 153 | the <tt>boost::wave::context<></tt> object.</P> |
|---|
| 154 | <table width="90%" border="0" align="center"> |
|---|
| 155 | <tr> |
|---|
| 156 | <td colspan="2" class="table_title"><b>Summary of required explicit template |
|---|
| 157 | instantiations <br> |
|---|
| 158 | required when using the separation compilation model</b></td> |
|---|
| 159 | </tr> |
|---|
| 160 | <tr class="table_title"> |
|---|
| 161 | <td width="25%"><b>Separate</b></td> |
|---|
| 162 | <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Templates |
|---|
| 163 | to explicitly instantiate</font></code></p></td> |
|---|
| 164 | </tr> |
|---|
| 165 | <tr> |
|---|
| 166 | <td width="25%" class="table_cells"><code>C++ lexer</code></td> |
|---|
| 167 | <td width="75%" class="table_cells"> <code><span class="keyword">template</span> |
|---|
| 168 | cpplexer::re2clex::new_lexer_gen<<tt>IteratorT</tt>>;</code></td> |
|---|
| 169 | </tr> |
|---|
| 170 | <tr> |
|---|
| 171 | <td width="25%" class="table_cells"><code>Spirit grammars</code></td> |
|---|
| 172 | <td width="75%" class="table_cells"> <p><code><span class="keyword">template</span> wave::grammars::expression_grammar_gen<<tt>TokenT</tt>>;<br> |
|---|
| 173 | <span class="keyword"> template</span> wave::grammars::intlit_grammar_gen<<tt>TokenT</tt>>;<br> |
|---|
| 174 | <span class="keyword"> template</span> wave::grammars::chlit_grammar_gen<<tt>TokenT</tt>>;<br> |
|---|
| 175 | <span class="keyword"> <code>template</code><code></code><code> wave::grammars::cpp_grammar_gen<<tt>LexIteratorT</tt>>;<br> |
|---|
| 176 | </code>template</span> wave::grammars::predefined_macros_grammar_gen<<tt>LexIteratorT</tt>>;<br> |
|---|
| 177 | <span class="keyword"> template</span> wave::grammars::defined_grammar_gen<<tt>LexIteratorT</tt>>;</code></p></td> |
|---|
| 178 | </tr> |
|---|
| 179 | </table> |
|---|
| 180 | <p>To see an example of this you can look at the <tt>Wave</tt> driver program |
|---|
| 181 | included as an acompanion sample to the C++ preprocessor iterator library. The |
|---|
| 182 | corresponding files are named obviously <span class="string">"instantiate_...something.cpp"</span>, |
|---|
| 183 | where the <span class="string">'...somthing'</span> is a hint, which grammars |
|---|
| 184 | are explicitely instantiated inside. By using the separation model the compilation |
|---|
| 185 | times required to build the <tt>Wave</tt> example are dropped by up to 90%.</p> |
|---|
| 186 | <table border="0"> |
|---|
| 187 | <tr> |
|---|
| 188 | <td width="10"></td> |
|---|
| 189 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
|---|
| 190 | <td width="30"><a href="supported_pragmas.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td> |
|---|
| 191 | <td width="30"><a href="samples.html"><img src="theme/r_arr.gif" border="0"></a></td> |
|---|
| 192 | </tr> |
|---|
| 193 | </table> |
|---|
| 194 | <hr size="1"> |
|---|
| 195 | <p class="copyright">Copyright © 2003-2005 Hartmut Kaiser<br> |
|---|
| 196 | <br> |
|---|
| 197 | <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> |
|---|
| 198 | <span class="updated"></span> |
|---|
| 199 | <p class="copyright"><span class="updated">Last updated: |
|---|
| 200 | <!-- #BeginDate format:fcAm1m -->Sunday, May 15, 2005 12:23<!-- #EndDate --> |
|---|
| 201 | </span></p> |
|---|
| 202 | </body> |
|---|
| 203 | </html> |
|---|
