| 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 got 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-2007 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 | |
|---|
