263 lines
17 KiB
HTML
263 lines
17 KiB
HTML
<!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://www.boost.org"><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="macro_expansion_process.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
|
|
<td width="30"><a href="samples.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>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</code></td>
|
|
<td width="54%" class="table_cells"> <p>Support the <span class="preprocessor">#warning</span> directive</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td width="46%" class="table_cells"><code>BOOST_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>BOOST_WAVE_PREPROCESS_ERROR_MESSAGE_BODY</code></td>
|
|
<td class="table_cells"><p>Enable the preprocessing of the message bodies
|
|
of <span class="preprocessor">#error</span> and <span class="preprocessor">#warning</span>
|
|
directives.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</code></td>
|
|
<td class="table_cells"><p>If defined, then the <span class="preprocessor">#pragma</span>
|
|
directives are returned as a token sequence to the caller, if not defined,
|
|
the whole <span class="preprocessor">#pragma</span> directive is skipped. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_PREPROCESS_PRAGMA_BODY</code></td>
|
|
<td class="table_cells"><p>Enable the preprocessing of the bodies of all <span class="preprocessor">
|
|
#pragma</span> directives.<br>
|
|
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>.
|
|
</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_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>BOOST_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>BOOST_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>BOOST_WAVE_SUPPORT_CPP0X</code></td>
|
|
<td class="table_cells"><p>If defined, then the preprocessor library supports
|
|
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>
|
|
</tr> <tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_SUPPORT_CPP1Z</code></td>
|
|
<td class="table_cells"><p>If defined, then the preprocessor library supports
|
|
C++17 keywords - currently just <code>__has_include</code>. It implies <code>BOOST_WAVE_SUPPORT_CPP0X</code>.</p></td>
|
|
</tr>
|
|
</tr> <tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_SUPPORT_CPP2A</code></td>
|
|
<td class="table_cells"><p>If defined, then the preprocessor library supports
|
|
C++20 keywords, specifically <code>__VA_OPT__</code>. It implies <code>BOOST_WAVE_SUPPORT_CPP1Z</code>.</p></td>
|
|
</tr>
|
|
</tr> <tr>
|
|
<td class="table_cells"><code>BOOST_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>BOOST_WAVE_SUPPORT_PRAGMA_ONCE</code></td>
|
|
<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
|
|
(opened) only once by the compiler in a build. </p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE</code></td>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</code></td>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_USE_STRICT_LEXER</code></td>
|
|
<td class="table_cells"><p>If this is defined to something != 0, then the C/C++ lexers recognize the
|
|
strict C99/C++ basic source character set. If it is not defined or defined
|
|
to zero, the lexers recognize the <span class="string">'$'</span> character as part of identifiers.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_PRAGMA_KEYWORD</code></td>
|
|
<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>
|
|
</p> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells"><code>BOOST_WAVE_SUPPORT_LONGLONG_INTEGER_LITERALS</code></td>
|
|
<td class="table_cells"><p>The C++ standard requires the preprocessor to use one of the following
|
|
types for integer literals: <code>long</code> or <code>unsigned long</code> depending on a optional
|
|
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
|
|
(i.e. <code>long long</code> or <code>unsigned long long</code>). Defining this pp constant enables the recognition of long long integers
|
|
even if these do not have the <span class="literal">'ll'</span> suffix.</p>
|
|
<p>This preprocessor constant is effective only, if your target platform supports
|
|
long long integers (<code>BOOST_HAS_LONG_LONG</code> is defined). Please note, that this setting doesn't relate to the Wave support option
|
|
<code>support_option_long_long</code>, which enables the recognition of <span class="literal">'ll'</span> suffixes
|
|
only.
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="table_cells">
|
|
<code>BOOST_WAVE_SUPPORT_THREADING</code></td>
|
|
<td class="table_cells">
|
|
<p>This preprocessor constant allows to configer whether the Wave library will be built
|
|
with threading support enabled or not. This value (if defined) should be set to
|
|
zero ('0') if threading needs to be disabled and to a numerical value not equal
|
|
to zero, if threading should be enabled explicitly.
|
|
</p>
|
|
<p>
|
|
If this constant is not defined, the Wave library will be built using the threading
|
|
as picked up from the Boost build environment (see <code>BOOST_HAS_THREADS</code> in the Boost
|
|
configuration dosumentation).</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<P dir="ltr"><b><a name="using_custom_lexer"></a>Using a different token type or lexer type in conjunction with Wave </b></P>
|
|
<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>
|
|
<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>
|
|
<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 explicitly 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><code>BOOST_</code>WAVE_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><code>BOOST_</code>WAVE_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 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
|
|
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>boost::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++ lexer</code></td>
|
|
<td width="75%" class="table_cells"> <code><span class="keyword">template</span>
|
|
cpplexer::re2clex::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><code><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::cpp_grammar_gen<<tt>LexIteratorT</tt>>;<br>
|
|
<span class="keyword"> template</span> wave::grammars::predefined_macros_grammar_gen<<tt>LexIteratorT</tt>>;<br>
|
|
<span class="keyword"> template</span> wave::grammars::defined_grammar_gen<<tt>LexIteratorT</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 explicitly 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>
|
|
<P dir="ltr"><b><a name="compiler_requirements"></a>Compiler Requirements</b></P>
|
|
<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>
|
|
<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="macro_expansion_process.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
|
|
<td width="30"><a href="samples.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<hr size="1">
|
|
<p class="copyright">Copyright © 2003-2011 Hartmut Kaiser<br>
|
|
<br>
|
|
<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>
|
|
<span class="updated"></span>
|
|
<p class="copyright"><span class="updated">Last updated:
|
|
<!-- #BeginDate format:fcAm1m -->Sunday, January 9, 2011 16:16<!-- #EndDate -->
|
|
</span></p>
|
|
</body>
|
|
</html>
|