Click here to Skip to main content
Click here to Skip to main content
Add your own
alternative version
Go to top

Wave: a Standard conformant C++ preprocessor library

, 10 Jan 2004
Describes a free and fully Standard conformant C++ preprocessor library
wave_preprocessor_demo.zip
wave.exe
wave_preprocessor_demo1.zip
wave.exe
wave_preprocessor_src.zip
wave
doc
theme
bkd.gif
bkd2.gif
bullet.gif
l_arr.gif
l_arr_disabled.gif
r_arr.gif
r_arr_disabled.gif
uc.gif
u_arr.gif
wave.gif
test
boost-build.jam
cpp_tokens
Jamfile.v2
list_includes
project-root.jam
wave
Jamfile
Jamfile.v2
runtests.sh
test_files
wave
cpplexer
re2clex
cpp.re
test
lextest.in
lextest.output
run_tests.sh
test_lexer.in
test_lexer.output
slex
test
lextest.in
lextest.re2c.output
lextest.slex.output
run_tests.sh
grammars
idllexer
re2clex
idl.re
util
wave_preprocessor_src1.zip
bkd.gif
bkd2.gif
bullet.gif
l_arr.gif
l_arr_disabled.gif
r_arr.gif
r_arr_disabled.gif
u_arr.gif
uc.gif
wave.gif
boost-build.jam
Jamfile.v2
project-root.jam
Jamfile
Jamfile.v2
runtests.sh
cpp.re
lextest.in
lextest.output
run_tests.sh
test_lexer.in
test_lexer.output
lextest.in
lextest.re2c.output
lextest.slex.output
run_tests.sh
<!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="20"><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="90%" 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="39%" class="table_cells"><code>WAVE_SUPPORT_WARNING_DIRECTIVE</code></td>
    <td width="61%" class="table_cells"> <p>Support the #warning directive</p></td>
  </tr>
  <tr> 
    <td width="39%" class="table_cells"><code>WAVE_SUPPORT_MS_EXTENSIONS</code></td>
    <td width="61%" 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&nbsp;_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>
</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&lt;&gt;</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&lt;<tt>IteratorT</tt>&gt;; <span class="table_cells"><code>or</code></span><br>
      <span class="keyword"> template</span> cpplexer::slex::new_lexer_gen&lt;<tt>IteratorT</tt>&gt;;</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&lt;<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::expression_grammar_gen&lt<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::intlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::chlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::floatlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::predefined_macros_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
        <span class="keyword"> template</span> wave::grammars::defined_grammar_gen&lt;<tt>TokenT</tt>&gt;;</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">&quot;instantiate_...something.cpp&quot;</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="20"><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 &copy; 2003 Hartmut Kaiser<br>
  <br>
  <font size="2">Permission to copy, use, modify, sell and distribute this document 
  is granted provided this copyright notice appears in all copies. This document 
  is provided &quot;as is&quot; without express or implied warranty, and with 
  no claim as to its suitability for any purpose. </font> </p>
<span class="updated">Last updated: 
  <!-- #BeginDate format:fcAm1m -->Saturday, May 10, 2003  21:05<!-- #EndDate -->
  </span></body>
</html>

By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Hartmut Kaiser

United States United States
Actively involved in Boost and the development of the Spirit parser construction framework.

| Advertise | Privacy | Mobile
Web03 | 2.8.140916.1 | Last Updated 11 Jan 2004
Article Copyright 2003 by Hartmut Kaiser
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid