1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Wave Driver</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
Wave Driver</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="samples.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="tracing_facility.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>There is implemented a driver program for the <tt>Wave</tt> library, which
utilizes nearly all capabilities of the library. It is usable as a preprocessor executable
on top of any other C++ compiler. It outputs the textual representation of the
preprocessed tokens generated from a given input file. This driver program has
the following command line syntax:</p>
<pre>Usage: wave [options] [@config-file(s)] file:
Options allowed on the command line only:
-h [--help]: print out program usage (this message)
-v [--version]: print the version number
-c [--copyright]: print out the copyright statement
--config-file filepath: specify a config file (alternatively: @filepath)
Options allowed additionally in a config file:
-o [--output] path: specify a file to use for output instead of stdout
-I [--include] path: specify an additional include directory
-S [--sysinclude] syspath: specify an additional system include directory
-F [--forceinclude] file: force inclusion of the given file
-D [--define] macro[=[value]]: specify a macro to define
-P [--predefine] macro[=[value]]: specify a macro to predefine
-U [--undefine] macro: specify a macro to undefine
-u [--undefineall]: undefine all macrodefinitions
-n [--nesting] depth: specify a new maximal include nesting depth
Extended options (allowed everywhere)
-t [--traceto] arg: output trace info to a file [arg] or to stderr [-]
--timer output overall elapsed computing time
--long_long: enable long long support if C++ mode
--variadics: enable variadics and placemarkers in C++ mode
--c99: enable C99 mode (implies variadics and placemarkers)
-l [ --listincludes ] arg: list included file to a file [arg] or to stdout [-]
-p [ --preserve ]: preserve comments
</pre>
<P dir="ltr">The possible options are straightforward and self explanatory. The
following describes some of these options in more detail. Please note, that
the extended options (--c99 and --variadics) are available only, if the driver
was compiled with the constant <tt>WAVE_SUPPORT_VARIADICS_PLACEMARKERS</tt>
defined. </P>
<P dir="ltr">-o [--output] path</P>
<blockquote>
<p dir="ltr">Specify a filename to be used for the generated preprocessed output
stream. If this option is not given, then the standard output is used (stdout).</p>
</blockquote>
<P dir="ltr">-I [--include] option</P>
<blockquote>
<p dir="ltr">Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system
header file, substituting your own version, since these directories are
searched before the system header file directories. However, you should
not use this option to add directories that contain vendor-supplied
system header files (use '-S' for that). If you use more than
one '-I' option, the directories are scanned in left-to-right order,
the standard system directories come after. </p>
<p>If a standard system include directory, or a directory specified with
'-S', is also specified with '-I', the '-I' option will be
ignored. The directory will still be searched but as a system
directory at its normal position in the system include chain. </p>
</blockquote>
<p dir="ltr">-I- [--include-] option</p>
<blockquote>
<p dir="ltr">The <tt>Wave</tt> library maintains two separate search paths
for include files. A search path for user include files and a search path
for system include files, where the user include paths are searched before the system include paths. </p>
<p dir="ltr">Any directories specified with '-I' options before
an eventually given '-I-' option are searched only for the case of '#include "file"'
(user include files), they are not searched for '#include <file>'
directives (system include files). If additional directories are specified
with '-I' options after a '-I-' option was given, these directories are searched
for all '#include' directives (ordinarily all '-I' directories are used this way.). </p>
<p dir="ltr">In addition, the '-I-' option inhibits the
use of the current directory (where the current input file came from) as the first search directory for '#include "file"'
directives . With '-I.' you can specify searching the directory which was current when the compiler was invoked. That is not exactly the same as what the
preprocessor does by default, but it is often satisfactory. </p>
</blockquote>
<p dir="ltr">-S [--sysinclude] option</p>
<blockquote>
<p dir="ltr">Add the given directory to the head of the list of directories
to be searched for system header files. If you use more than one '-S' option,
the directories are scanned in left-to-right order. This option is most useful
in the wave.cfg configuration file to specify, where the system include files
are to be searched.</p>
</blockquote>
<p dir="ltr">-F [--forceinclude] option</p>
<blockquote>
<p dir="ltr">Process the given file as normal input and include all the resulting
output before the processing the regular input file starts. If more than one
such option is given, the files are pre-included in the sequence of its occurance
on the command line.</p>
</blockquote>
<p dir="ltr">-D [--define] macro[=definition]<br>-P [--predefine] macro[=definition]</p>
<blockquote>
<p dir="ltr">This option allows to define ('-D') or predefine ('-P') a macro
from the command line. The string given in conjunction with the '-D' or '-P'
option should conform to the usual syntax MACRO(x)=definition as is described
in more detail <a href="class_reference_context.html#add_macro_definition">here</a>.</p>
<p dir="ltr"> The only difference between the '-D' and the '-P' options is,
that the latter predefines a macro such, that it is <b>not</b> undefinable
through an <tt>#undef</tt> directive from inside the preprocessed program.</p>
</blockquote>
<p dir="ltr">-U [--undefine] macro </p>
<blockquote>
<p dir="ltr">This allows to undefine some of the automatically predefined macros
of the <tt>Wave</tt> library (see <a href="predefined_macros.html">Predefined macros</a>). The only exception are
the <code class="keyword">__LINE__</code>, <code class="keyword">__FILE__</code>,
<code class="keyword">__DATE__</code>, <code class="keyword">__TIME__</code>,
<code class="keyword">__STDC__</code> and <code class="keyword">__cplusplus</code>
predefined macros, which are not undefinable. If -U and -D are both specified
for one name, the name is not predefined.</p>
</blockquote>
<p dir="ltr">-n [--nesting] depth</p>
<blockquote>
<p dir="ltr">Specify a new maximal include nesting depth. If the preprocessing
reaches this include file nesting depth, it aborts the preprocessing after
emitting an error message. The default include file nesting depth is 1024.</p>
</blockquote>
<p dir="ltr">-t [--traceto] path</p>
<blockquote>
<p dir="ltr">Enable the tracing facility build into the <tt>Wave</tt> library.
The path specifies the filename to use for the output of the generated trace
log. If the filename given equals to <tt>'-'</tt> (without the quotes), the
trace log is put into the standard error stream (stderr).</p>
</blockquote>
<p dir="ltr">--timer</p>
<blockquote>
<p dir="ltr">Enable to track the overall elapsed computing time required for
the given input file. The elapsed time is printed to stdout after the compilation
is completed.</p>
</blockquote>
<p dir="ltr">--variadics</p>
<blockquote>
<p dir="ltr">Enables support for variadics (macros with variable parameter lists),
placemarkers (empty macro arguments) and <tt>operator _Pragma</tt> in
normal C++ mode. This option predefines a special predefined macro <tt>__WAVE_HAS_VARIADICS__</tt>.</p>
</blockquote>
<p dir="ltr">--c99</p>
<blockquote>
<p dir="ltr">Enable the C99 mode. This mode enables certain C99 specific features
as variadics (macros with variable parameter lists), placemarkers (empty macro
arguments) and <tt>operator _Pragma</tt> support and disables some C++
specific token types as for instance <tt>'::'</tt>, <tt>'->*'</tt> and <tt>'->.'</tt>.
Several predefined macros are different for this mode, for more information
about predefined macros you may look <a href="predefined_macros.html">here</a>.
</p>
</blockquote>
<p dir="ltr">-l [--listincludes] path</p>
<blockquote>
<p dir="ltr">Enable the output of the names of all opened include files. The path specifies the filename to use for the output of the generated include log. If the filename given equals to <tt>'-'</tt> (without the quotes), the include log is put into the standard output stream (stdout).</p>
</blockquote>
<p dir="ltr">-p [--preserve] </p>
<blockquote>
<p dir="ltr">Preserve the comments from the input stream not located inside of macro definitions. The comments located inside macro definitions are skipped even if this option is specified. If this option is not specified on the command line all comments are skipped. </p>
</blockquote>
<p dir="ltr">@ [--config-file] option</p>
<blockquote>
<p dir="ltr">Some of the possible command line options may be specified inside
of special configuration files. This is very useful, as a shorthand for different
global configurations. A config file may contain additional options (-I, -S,
-F, -U, -D and -P options), one option per line. Empty lines and lines beginning
with a '#' character are ignored (are treated as a comment lines). Note that
the '#' character is treated as the beginning of a comment only, if it is
the first non-whitespace character on a line. Here is a small sample illustrating the supported configuration file syntax:</p>
<pre><span class="comment"> #
# enable variadics et.al. in C++ mode
#</span>
--variadics
<span class="comment"> #
# enable timer support
#
</span> --timer
<span class="comment"> #
# emulate gcc V3.3.2
#
</span> -D__GNUC__=3
-D__GNUC_MINOR__=3
-D__GNUC_PATCHLEVEL__=2
-D__GNUG__
<span class="comment"> #
# add Boost to the system include search paths
#</span>
-S/usr/local/boost</pre>
<p dir="ltr"> There is a shorthand for specifying a configuration file on the
command line: simply use the '@' character immediatly before the corresponding
file name.</p>
<p dir="ltr"> The options found in a configuration file are interpreted, as
if they were place instead of the configuration file option on the command
line.</p>
</blockquote>
<p dir="ltr">The <tt>Wave</tt> driver program looks at startup for a configuration
file named 'wave.cfg' in the same directory, where it was started from (where
is located the driver executable). If this file exists, it is treated as a normal
configuration file and the specified herein options are interpreted as if they
were given as the first options on the command line. This feature is very useful
for defining a global environment for the <tt>Wave</tt> preprocessor driver.</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="samples.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="tracing_facility.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright © 2003-2005 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, May 15, 2005 12:23<!-- #EndDate -->
</span></p>
</body>
</html>
|
