162 lines
7.7 KiB
HTML
162 lines
7.7 KiB
HTML
<!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>
|
|
|