Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/wave/doc/compiletime_config.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 14.1 KB
Line 
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_RETURN_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&nbsp;_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_MAX_INCLUDE_LEVEL_DEPTH</code></td>
89    <td class="table_cells"><p>If defined, it will determine the initial maximal
90        possible include file nesting depth supported. It defaults to 1024.</p></td>
91  </tr>
92  <tr>
93    <td class="table_cells"><code>BOOST_WAVE_SUPPORT_PRAGMA_ONCE</code></td>
94    <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
95      (opened) only once by the compiler in a build. </p></td>
96  </tr>
97  <tr>
98    <td class="table_cells"><code>BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE</code></td>
99    <td class="table_cells"><p>If defined, then the <code class="preprocessor">#pragma message(&quot;&quot;)</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>
100  </tr>
101  <tr>
102    <td class="table_cells"><code>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</code></td>
103    <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>
104  </tr>
105  <tr>
106    <td class="table_cells"><code>BOOST_WAVE_USE_STRICT_LEXER</code></td>
107    <td class="table_cells"><p>If this is defined to something != 0, then the C/C++ lexers recognize the
108      strict C99/C++ basic source character set. If it is not defined or defined
109    to zero, the lexers recognize the <span class="string">'$'</span> character as part of identifiers.</p></td>
110  </tr>
111  <tr>
112    <td class="table_cells"><code>BOOST_WAVE_PRAGMA_KEYWORD</code></td>
113    <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 pragma's. This constant defaults to <span class="literal">&quot;wave&quot;</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>
114      </p>    </td>
115  </tr>
116</table>
117<P dir="ltr"><b><a name="using_custom_lexer"></a>Using a different token type or lexer type in conjunction with Wave </b></P>
118<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&lt;&gt;</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&lt;&gt;</tt> type contained with the library. This type needs to be parametrized with the token type to use. </P>
119<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&lt;&lt;</tt> used for dumping the information carried by the token.</P>
120<P dir="ltr"><b><a name="compilation_models"></a>Separation and inclusion compilation
121  models</b></P>
122<P dir="ltr">The <tt>Wave</tt> C++ preprocessor iterator library is build almost
123  completely as a header only library (except for the re2c based lexer). If you're
124  trying to include all required files at once you will mention, that the resulting
125  compilation times are very large (up to an hour - depending on your system configuration).
126  This straightforward method we'll call the inclusion compilation model. If you
127  do not pay attention to compilation times, that's the way to go, no special
128  handling is needed.</P>
129<P dir="ltr">If you're interested in decreasing compilation times, the following
130  method is to be used. This we will call it the separation compilation model.
131  The trick is to separate the different objects such, that they are compilable
132  separately. The function, which instantiates the templated object in question
133  is factored out such, that its definition is visible to only one translation
134  unit. To simplify this further this creation function is packaged into a small
135  generator template structure.</P>
136<P dir="ltr">There are two levels of separation implemented: the separation of
137  the compilation of the C++ lexer and the separation of the compilation of the
138  different Spirit grammars used. To use these separations you will have to define
139  two preprocessor constants while compiling the whole application and you will
140  have to explicitely instantiate some helper templates. The following tables
141  shows these constants in detail.</P>
142<table width="90%" border="0" align="center">
143  <tr> 
144    <td colspan="2" class="table_title"><b>Summary of possible compilation constants
145      required <br>
146      to enable the separation compilation model</b></td>
147  </tr>
148  <tr class="table_title"> 
149    <td width="25%"><b>Separate</b></td>
150    <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Preprocessor
151        constant</font></code></p></td>
152  </tr>
153  <tr> 
154    <td width="25%" class="table_cells"><code>C++ lexer</code></td>
155    <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_LEXER_INSTANTIATION</code></p></td>
156  </tr>
157  <tr> 
158    <td width="25%" class="table_cells"><code>Spirit grammars</code></td>
159    <td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_GRAMMAR_INSTANTIATION</code></p></td>
160  </tr>
161</table>
162<P dir="ltr">The following table shows the explicit template instantiations required,
163  if you want to use the separation compilation model. The <tt>TokenT</tt> placeholder
164  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&lt;&gt;</tt> object. You will achieve the best
165  results, if you place these into separate compilation units each. The <tt>IteratorT</tt> 
166  placeholder should be replaced by the iterator type, which was used to instantiate
167  the <tt>boost::wave::context&lt;&gt;</tt> object.</P>
168<table width="90%" border="0" align="center">
169  <tr> 
170    <td colspan="2" class="table_title"><b>Summary of required explicit template
171      instantiations <br>
172      required when using the separation compilation model</b></td>
173  </tr>
174  <tr class="table_title"> 
175    <td width="25%"><b>Separate</b></td>
176    <td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Templates
177        to explicitly instantiate</font></code></p></td>
178  </tr>
179  <tr> 
180    <td width="25%" class="table_cells"><code>C++ lexer</code></td>
181    <td width="75%" class="table_cells"> <code><span class="keyword">template</span> 
182      cpplexer::re2clex::new_lexer_gen&lt;<tt>IteratorT</tt>&gt;;</code></td>
183  </tr>
184  <tr> 
185    <td width="25%" class="table_cells"><code>Spirit grammars</code></td>
186    <td width="75%" class="table_cells"> <p><code><span class="keyword">template</span> wave::grammars::expression_grammar_gen&lt<tt>TokenT</tt>&gt;;<br>
187        <span class="keyword"> template</span> wave::grammars::intlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
188        <span class="keyword"> template</span> wave::grammars::chlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
189        <span class="keyword"> <code>template</code><code></code><code> wave::grammars::cpp_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;<br>
190        </code>template</span> wave::grammars::predefined_macros_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;<br>
191    <span class="keyword"> template</span> wave::grammars::defined_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;</code></p></td>
192  </tr>
193</table>
194<p>To see an example of this you can look at the <tt>Wave</tt> driver program
195  included as an acompanion sample to the C++ preprocessor iterator library. The
196  corresponding files are named obviously <span class="string">&quot;instantiate_...something.cpp&quot;</span>,
197  where the <span class="string">'...somthing'</span> is a hint, which grammars
198  are explicitely instantiated inside. By using the separation model the compilation
199  times required to build the <tt>Wave</tt> example are dropped by up to 90%.</p>
200<table border="0">
201  <tr> 
202    <td width="10"></td>
203    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
204    <td width="30"><a href="macro_expansion_process.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
205    <td width="30"><a href="samples.html"><img src="theme/r_arr.gif" border="0"></a></td>
206  </tr>
207</table>
208<hr size="1">
209<p class="copyright">Copyright &copy; 2003-2007 Hartmut Kaiser<br>
210  <br>
211<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>
212<span class="updated"></span>
213<p class="copyright"><span class="updated">Last updated:
214  <!-- #BeginDate format:fcAm1m -->Tuesday, May 2, 2006  17:10<!-- #EndDate -->
215</span></p>
216</body>
217</html>
Note: See TracBrowser for help on using the repository browser.