<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Compile Time Configuration</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="theme/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
<tr>
<td width="21"> <h1></h1></td>
<td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">Compile
Time Configuration</font></b></font></td>
<td width="96"><a href="http://spirit.sf.net"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="10"></td>
<td width="30"><a href="index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="supported_pragmas.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p><b><a name="compiletime_config"></a>Library compile time configuration</b></p>
<P dir="ltr">The C++ preprocessor iterator library may be configured at compile
time by specifying different preprocessor constants to include different additional
features. The possible preprocessor constants are described in the following
table. </P>
<table width="100%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of possible preprocessor constants
for<br>
library configuration</b></td>
</tr>
<tr>
<td width="46%" class="table_cells"><code>WAVE_SUPPORT_WARNING_DIRECTIVE</code></td>
<td width="54%" class="table_cells"> <p>Support the #warning directive</p></td>
</tr>
<tr>
<td width="46%" class="table_cells"><code>WAVE_SUPPORT_MS_EXTENSIONS</code></td>
<td width="54%" class="table_cells"> <p>Support several MS specific language
extensions (i.e. <tt>__int8</tt> et.al.)</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_PREPROCESS_ERROR_MESSAGE_BODY</code></td>
<td class="table_cells"><p>Enable the preprocessing of the message bodies
of <span class="keyword">#error</span> and <span class="keyword">#warning</span>
directives.</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_RETURN_PRAGMA_DIRECTIVES</code></td>
<td class="table_cells"><p>If defined, then the <span class="keyword">#pragma</span>
directives are returned as a token sequence to the caller, if not defined,
the whole <span class="keyword">#pragma</span> directive is skipped. </p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_PREPROCESS_PRAGMA_BODY</code></td>
<td class="table_cells"><p>Enable the preprocessing of the bodies of <span class="keyword">
#pragma</span> directives.<br>
Note though, that the body of an <tt>operator _Pragma()</tt> is preprocessed
always, as required by the C99 Standard <a href="references.html#iso_c">[2]</a>.
</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_ENABLE_COMMANDLINE_MACROS</code></td>
<td class="table_cells"><p>Enable the functionality required to define macros
with the command line syntax (-DMACRO(x)=definition)</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_STRINGTYPE</code></td>
<td class="table_cells"><p>The tokens generated by the <tt>Wave</tt> library
contain the token data and the file position, where this token was found
in the input stream. <br>
This constant may be used to redefine the data type, which is used to
hold the token data and the corresponding file name. If this isn't defined
it defaults to std::string. (The here defined data type should be compatible
to the std::string type)</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_SUPPORT_VARIADICS_PLACEMARKERS</code></td>
<td class="table_cells"><p>If defined, then the preprocessor library supports
variadics and placemarkers. Note, to support C99 mode, this constant must
be defined too.</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_MAX_INCLUDE_LEVEL_DEPTH</code></td>
<td class="table_cells"><p>If defined, it will determine the initial maximal
possible include file nesting depth supported. It defaults to 1024.</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_ENABLE_CPP0X_EXTENSIONS</code></td>
<td class="table_cells"><p>If defined, the the preprocessor library supports
a couple of experimental C++0x extensions, as macro scopes, variadics
and placemarkers in C++ mode, well defined token pasting of unrelated
tokens. For more details please refer to <a href="preliminary_cpp0x_support.html">The
Preliminary C++0x support</a>.</p></td>
</tr>
<tr>
<td class="table_cells"><code>WAVE_REVERSE_MACRONAMES_FOR_SYMBOLTABLE</code></td>
<td class="table_cells"><p>If defined, the macro names are reversed before
storing them into the symbol table, which allows to speed up name lookup
especially, if the macro names are very long and if these share a common
prefix.</p></td>
</tr>
</table>
<P dir="ltr"></P>
<P dir="ltr"><b><a name="compilation_models"></a>Separation and inclusion compilation
models</b></P>
<P dir="ltr">The <tt>Wave</tt> C++ preprocessor iterator library is build almost
completely as a header only library (except for the re2c based lexer). If you're
trying to include all required files at once you will mention, that the resulting
compilation times are very large (up to an hour - depending on your system configuration).
This straightforward method we'll call the inclusion compilation model. If you
do not pay attention to compilation times, that's the way to go, no special
handling is needed.</P>
<P dir="ltr">If you're interested in decreasing compilation times, the following
method is to be used. This we will call it the separation compilation model.
The trick is to separate the different objects such, that they are compilable
separately. The function, which instantiates the templated object in question
is factored out such, that its definition is visible to only one translation
unit. To simplify this further this creation function is packaged into a small
generator template structure.</P>
<P dir="ltr">There are two levels of separation implemented: the separation of
the compilation of the C++ lexer and the separation of the compilation of the
different Spirit grammars used. To use these separations you will have to define
two preprocessor constants while compiling the whole application and you will
have to explicitely instantiate some helper templates. The following tables
shows these constants in detail.</P>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of possible compilation constants
required <br>
to enable the separation compilation model</b></td>
</tr>
<tr class="table_title">
<td width="25%"><b>Separate</b></td>
<td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Preprocessor
constant</font></code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>C++ lexer</code></td>
<td width="75%" class="table_cells"> <p><code>CPP_SEPARATE_LEXER_INSTANTIATION</code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>Spirit grammars</code></td>
<td width="75%" class="table_cells"> <p><code>CPP_SEPARATE_GRAMMAR_INSTANTIATION</code></p></td>
</tr>
</table>
<P dir="ltr">The following table shows the explicit template instantiations required,
if you want to use the separation compilation model. The <tt>TokenT</tt> placeholder
type has to be replaced with your token type to use. You will achieve the best
results, if you place these into separate compilation units each. The <tt>IteratorT</tt>
placeholder should be replaced by the iterator type, which was used to instantiate
the <tt>wave::context<></tt> object.</P>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of required explicit template
instantiations <br>
required when using the separation compilation model</b></td>
</tr>
<tr class="table_title">
<td width="25%"><b>Separate</b></td>
<td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Templates
to explicitly instantiate</font></code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>C++ lexers</code></td>
<td width="75%" class="table_cells"> <code><span class="keyword">template</span>
cpplexer::re2clex::new_lexer_gen<<tt>IteratorT</tt>>; <span class="table_cells"><code>or</code></span><br>
<span class="keyword"> template</span> cpplexer::slex::new_lexer_gen<<tt>IteratorT</tt>>;</code></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>Spirit grammars</code></td>
<td width="75%" class="table_cells"> <p><span class="keyword"><code>template</code><code></code></span><code>
wave::grammars::cpp_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::expression_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::intlit_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::chlit_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::floatlit_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::predefined_macros_grammar_gen<<tt>TokenT</tt>>;<br>
<span class="keyword"> template</span> wave::grammars::defined_grammar_gen<<tt>TokenT</tt>>;</code></p></td>
</tr>
</table>
<p>To see an example of this you can look at the <tt>Wave</tt> driver program
included as an acompanion sample to the C++ preprocessor iterator library. The
corresponding files are named obviously <span class="string">"instantiate_...something.cpp"</span>,
where the <span class="string">'...somthing'</span> is a hint, which grammars
are explicitely instantiated inside. By using the separation model the compilation
times required to build the <tt>Wave</tt> example are dropped by up to 90%.</p>
<table border="0">
<tr>
<td width="10"></td>
<td width="30"><a href="index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="supported_pragmas.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright © 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to 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>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>
Submit an article or tip