]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>The Tracing Facility</title> | |
5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
6 | <link href="theme/style.css" rel="stylesheet" type="text/css"> | |
7 | </head> | |
8 | ||
9 | <body> | |
10 | <table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif"> | |
11 | <tr> | |
12 | <td width="21"> <h1></h1></td> | |
13 | <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The | |
14 | Tracing Facility</font></b></font></td> | |
15 | <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td> | |
16 | </tr> | |
17 | </table> | |
18 | <br> | |
19 | <table border="0"> | |
20 | <tr> | |
21 | <td width="10"></td> | |
22 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> | |
23 | <td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td> | |
24 | <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td> | |
25 | </tr> | |
26 | </table> | |
27 | <p>If you ever had the need to debug a macro expansion you had to discover, that | |
28 | your tools provide only little or no support for this task. For this reason | |
29 | the <i>Wave</i> library has a tracing facility, which allows to get selectively | |
30 | some information about the expansion of a certain macro or several macros. </p> | |
31 | <p>The tracing of macro expansions generates a possibly huge amount of information, | |
32 | so it is recommended, that you explicitely enable/disable the tracing for the | |
33 | macro in question only. This may be done with the help of a special, <tt>Wave</tt> | |
34 | specific #pragma:</p> | |
35 | <pre><span class="preprocessor"> #pragma</span> wave trace(enable) <span class="comment">// enable the tracing</span> | |
36 | <span class="comment">// the macro expansions here will be traced</span> | |
37 | <span class="comment">// ...</span> | |
38 | <span class="preprocessor"> #pragma</span> wave trace(disable) <span class="comment">// disable the tracing</span></pre> | |
39 | <p>In C99 mode or when specifying the <tt>--variadics</tt> command line option | |
40 | you may additionally use the <tt>operator _Pragma()</tt> variant to enable/disable | |
41 | the tracing output:</p> | |
42 | <pre><span class="preprocessor"> #define</span> CONCAT(x, y) \ | |
43 | <span class="preprocessor">_Pragma</span>(<span class="string">"wave trace(enable)"</span>) \ | |
44 | x \ | |
45 | <span class="preprocessor">_Pragma</span>(<span class="string">"wave trace(disable)"</span>) \ | |
46 | <span class="keyword">##</span> y</pre> | |
47 | <p>This way you have the possibility to enable the tracing during the expansion | |
48 | of a part of a macro only. In the sample shown there is traced the expansion | |
49 | of the macro argument <tt>'x'</tt> only. Note, that the <tt>operator _Pragma()</tt> | |
50 | directives expand to nothing inside the macro expansion result.</p> | |
51 | <p>To see, what the <tt>Wave</tt> driver generates while expanding a simple macro, | |
52 | let's have a look at the tracing output for the following example:</p> | |
53 | <pre ><span class="comment"> // test.cpp</span> | |
54 | <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 | |
55 | <span class="preprocessor"> #define</span> CONCAT(x, y) CONCAT_(x, y) | |
56 | <span class="preprocessor"> #pragma</span> wave trace(enable) | |
57 | <span class="comment"> // this macro expansion is to be traced</span> | |
58 | CONCAT(X(1), Y()) <span class="comment">// should expand to 12</span> | |
59 | <span class="preprocessor"> #pragma</span> wave trace(disable)</pre> | |
60 | <p>When preprocessed with <tt>'wave -t test.trace test.cpp'</tt> the <tt>Wave</tt> | |
61 | driver generates a file <tt>test.trace</tt>, which contains (without the line | |
62 | numbers in front of the lines):</p> | |
63 | <pre> 1: test.cpp:8:1: CONCAT(X(1), Y()) | |
64 | 2: test.cpp:5:9: see macro definition: CONCAT(x, y) | |
65 | 3: invoked with | |
66 | 4: [ | |
67 | 5: x = X(1) | |
68 | 6: y = Y() | |
69 | 7: ] | |
70 | 8: [ | |
71 | 9: test.cpp:2:9: see macro definition: X(x) | |
72 | 10: invoked with | |
73 | 11: [ | |
74 | 12: x = 1 | |
75 | 13: ] | |
76 | 14: [ | |
77 | 15: 1 | |
78 | 16: rescanning | |
79 | 17: [ | |
80 | 18: 1 | |
81 | 19: ] | |
82 | 20: ] | |
83 | 21: test.cpp:3:9: see macro definition: Y() | |
84 | 22: [ | |
85 | 23: 2 | |
86 | 24: rescanning | |
87 | 25: [ | |
88 | 26: 2 | |
89 | 27: ] | |
90 | 28: ] | |
91 | 29: CONCAT_(1, 2) | |
92 | 30: rescanning | |
93 | 31: [ | |
94 | 32: test.cpp:4:9: see macro definition: CONCAT_(x, y) | |
95 | 33: invoked with | |
96 | 34: [ | |
97 | 35: x = 1 | |
98 | 36: y = 2 | |
99 | 37: ] | |
100 | 38: [ | |
101 | 39: 12 | |
102 | 40: rescanning | |
103 | 41: [ | |
104 | 42: 12 | |
105 | 43: ] | |
106 | 44: ] | |
107 | 45: 12 | |
108 | 46: ] | |
109 | 47: ] | |
110 | </pre> | |
111 | <p>The generated trace output is very verbose, but allows to follow every step | |
112 | of the actual macro expansion process. The first line in this tracing example | |
113 | contains the reference to the position, from where the macro expansion was initiated. | |
114 | Additionally the following information is contained for every single macro expansion:</p> | |
115 | <ul> | |
116 | <li>The reference to the position (line and column numbers), where the macro to expand was defined first | |
117 | (see lines 2, 9, 21 and 32).</li> | |
118 | <li>The real parameters supplied for this macro expansion (see lines 3, 10 and | |
119 | 33), this information is traced inside the <tt>invoked with</tt> block, where | |
120 | the corresponding formal and actual parameters are listed.</li> | |
121 | <li>The expansion of the given arguments (if any and if these are defined as | |
122 | macros). This repeats the full tracing information for the argument macro | |
123 | expansion, only indended by one level. Note though, that the macro expansion | |
124 | of the actual arguments is traced, regardless of the fact, whether this argument | |
125 | is really to be inserted into the replacement list after its expansion | |
126 | or as it was initially supplied (see C++ Standard [16.3.1.1]: "A parameter | |
127 | in the replacement list, unless preceded by a <tt>#</tt> or <tt>##</tt> preprocessing | |
128 | token or followed by a <tt>##</tt> preprocessing token, is replaced by the | |
129 | corresponding argument after all macros contained therein have been expanded" | |
130 | <a href="references.html#iso_cpp">[1]</a>). </li> | |
131 | <li>The result of the argument substitution (see lines 15, 23, 29 and 39), i.e. | |
132 | the substituted replacement list.</li> | |
133 | <li>The rescanning process, which again includes the full subsequent macro expansion | |
134 | process of all found macros (see C++ Standard [16.3.4.1]: "After all | |
135 | parameters in the replacement list have been substituted, the resulting preprocessing | |
136 | token sequence is rescanned with all subsequent preprocessing tokens of the | |
137 | source file for more macro names to replace." <a href="references.html#iso_cpp">[1]</a>).</li> | |
138 | <li>The result of the actual macro expansion (this is the last line inside the | |
139 | corresponding rescanning block - see lines 18, 26, 42 and 45).</li> | |
140 | </ul> | |
141 | <p>Every found macro to expand will add an additional indentation level inside | |
142 | the trace output.</p> | |
143 | <table border="0"> | |
144 | <tr> | |
145 | <td width="10"></td> | |
146 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> | |
147 | <td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td> | |
148 | <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td> | |
149 | </tr> | |
150 | </table> | |
151 | <hr size="1"> | |
152 | <p class="copyright">Copyright © 2003-2011 Hartmut Kaiser<br> | |
153 | <br> | |
154 | <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> | |
155 | <p class="copyright"><span class="updated">Last updated: | |
156 | <!-- #BeginDate format:fcAm1m -->Tuesday, March 21, 2006 9:25<!-- #EndDate --> | |
157 | </span> | |
158 | </p> | |
159 | </body> | |
160 | </html> | |
161 |