123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <title>The Tracing Facility</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">The
- Tracing Facility</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="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
- <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td>
- </tr>
- </table>
- <p>If you ever had the need to debug a macro expansion you had to discover, that
- your tools provide only little or no support for this task. For this reason
- the <i>Wave</i> library has a tracing facility, which allows to get selectively
- some information about the expansion of a certain macro or several macros. </p>
- <p>The tracing of macro expansions generates a possibly huge amount of information,
- so it is recommended, that you explicitely enable/disable the tracing for the
- macro in question only. This may be done with the help of a special, <tt>Wave</tt>
- specific #pragma:</p>
- <pre><span class="preprocessor"> #pragma</span> wave trace(enable) <span class="comment">// enable the tracing</span>
- <span class="comment">// the macro expansions here will be traced</span>
- <span class="comment">// ...</span>
- <span class="preprocessor"> #pragma</span> wave trace(disable) <span class="comment">// disable the tracing</span></pre>
- <p>In C99 mode or when specifying the <tt>--variadics</tt> command line option
- you may additionally use the <tt>operator _Pragma()</tt> variant to enable/disable
- the tracing output:</p>
- <pre><span class="preprocessor"> #define</span> CONCAT(x, y) \
- <span class="preprocessor">_Pragma</span>(<span class="string">"wave trace(enable)"</span>) \
- x \
- <span class="preprocessor">_Pragma</span>(<span class="string">"wave trace(disable)"</span>) \
- <span class="keyword">##</span> y</pre>
- <p>This way you have the possibility to enable the tracing during the expansion
- of a part of a macro only. In the sample shown there is traced the expansion
- of the macro argument <tt>'x'</tt> only. Note, that the <tt>operator _Pragma()</tt>
- directives expand to nothing inside the macro expansion result.</p>
- <p>To see, what the <tt>Wave</tt> driver generates while expanding a simple macro,
- let's have a look at the tracing output for the following example:</p>
- <pre ><span class="comment"> // test.cpp</span>
- <span class="preprocessor"> #define</span> X(x) x<br><span class="preprocessor"> #define</span> Y() 2<br><span class="preprocessor"> #define</span> CONCAT_(x, y) x <span class="keyword">##</span> y
- <span class="preprocessor"> #define</span> CONCAT(x, y) CONCAT_(x, y)
- <span class="preprocessor"> #pragma</span> wave trace(enable)
- <span class="comment"> // this macro expansion is to be traced</span>
- CONCAT(X(1), Y()) <span class="comment">// should expand to 12</span>
- <span class="preprocessor"> #pragma</span> wave trace(disable)</pre>
- <p>When preprocessed with <tt>'wave -t test.trace test.cpp'</tt> the <tt>Wave</tt>
- driver generates a file <tt>test.trace</tt>, which contains (without the line
- numbers in front of the lines):</p>
- <pre> 1: test.cpp:8:1: CONCAT(X(1), Y())
- 2: test.cpp:5:9: see macro definition: CONCAT(x, y)
- 3: invoked with
- 4: [
- 5: x = X(1)
- 6: y = Y()
- 7: ]
- 8: [
- 9: test.cpp:2:9: see macro definition: X(x)
- 10: invoked with
- 11: [
- 12: x = 1
- 13: ]
- 14: [
- 15: 1
- 16: rescanning
- 17: [
- 18: 1
- 19: ]
- 20: ]
- 21: test.cpp:3:9: see macro definition: Y()
- 22: [
- 23: 2
- 24: rescanning
- 25: [
- 26: 2
- 27: ]
- 28: ]
- 29: CONCAT_(1, 2)
- 30: rescanning
- 31: [
- 32: test.cpp:4:9: see macro definition: CONCAT_(x, y)
- 33: invoked with
- 34: [
- 35: x = 1
- 36: y = 2
- 37: ]
- 38: [
- 39: 12
- 40: rescanning
- 41: [
- 42: 12
- 43: ]
- 44: ]
- 45: 12
- 46: ]
- 47: ]
- </pre>
- <p>The generated trace output is very verbose, but allows to follow every step
- of the actual macro expansion process. The first line in this tracing example
- contains the reference to the position, from where the macro expansion was initiated.
- Additionally the following information is contained for every single macro expansion:</p>
- <ul>
- <li>The reference to the position (line and column numbers), where the macro to expand was defined first
- (see lines 2, 9, 21 and 32).</li>
- <li>The real parameters supplied for this macro expansion (see lines 3, 10 and
- 33), this information is traced inside the <tt>invoked with</tt> block, where
- the corresponding formal and actual parameters are listed.</li>
- <li>The expansion of the given arguments (if any and if these are defined as
- macros). This repeats the full tracing information for the argument macro
- expansion, only indended by one level. Note though, that the macro expansion
- of the actual arguments is traced, regardless of the fact, whether this argument
- is really to be inserted into the replacement list after its expansion
- or as it was initially supplied (see C++ Standard [16.3.1.1]: "A parameter
- in the replacement list, unless preceded by a <tt>#</tt> or <tt>##</tt> preprocessing
- token or followed by a <tt>##</tt> preprocessing token, is replaced by the
- corresponding argument after all macros contained therein have been expanded"
- <a href="references.html#iso_cpp">[1]</a>). </li>
- <li>The result of the argument substitution (see lines 15, 23, 29 and 39), i.e.
- the substituted replacement list.</li>
- <li>The rescanning process, which again includes the full subsequent macro expansion
- process of all found macros (see C++ Standard [16.3.4.1]: "After all
- parameters in the replacement list have been substituted, the resulting preprocessing
- token sequence is rescanned with all subsequent preprocessing tokens of the
- source file for more macro names to replace." <a href="references.html#iso_cpp">[1]</a>).</li>
- <li>The result of the actual macro expansion (this is the last line inside the
- corresponding rescanning block - see lines 18, 26, 42 and 45).</li>
- </ul>
- <p>Every found macro to expand will add an additional indentation level inside
- the trace output.</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="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
- <td width="30"><a href="acknowledgements.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>
- <p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Tuesday, March 21, 2006 9:25<!-- #EndDate -->
- </span>
- </p>
- </body>
- </html>
|