The Wave Driver

There is implemented a driver program for the Wave library, which utilizes the 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:

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
    -n [--nesting] depth:        specify a new maximal include nesting depth
	
  Extended options (allowed everywhere)
    -t [--traceto] path:    output trace info to a file [path] or to stderr [-]
    --variadics:            enable variadics and placemarkers in C++ mode
    --c99:                  enable C99 mode (implies variadics and placemarkers)
    --c++0x:                enable C++0x support (implies --variadics)
 

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 WAVE_SUPPORT_VARIADICS_PLACEMARKERS defined.

-o [--output] path

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).

-I [--include] option

Add the given directory 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. If you use more than one '-I' option, the directories are scanned in left-to-right order, the system directories come after.

-I- [--include-] option

The Wave library maintains two separate search pathes for include files. A search path for user include files and a search path for system include files. 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. In addition, the '-I-' option inhibits the use of the current directory as the first search directory for '#include "file"' directives. Therefore, the current directory is searched only if it is requested explicitly with a '-I.' option. Specifying both '-I-' and '-I.' allows to control precisely which directories are searched before the current one and which are searched after.

-S [--sysinclude] option

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.

-F [--forceinclude] option

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.

-D [--define] macro[=definition]
-P [--predefine] macro[=definition]

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 here.

The only difference between the '-D' and the '-P' options is, that the latter predefines a macro such, that it is not undefinable through an #undef directive from inside the preprocessed program.

-U [--undefine] option

This allows to undefine some of the automatically predefined macros of the Wave library (see Predefined macros). The only exception are the __LINE__, __FILE__, __DATE__, __TIME__, __STDC__ and __cplusplus predefined macros, which are not undefinable. If -U and -D are both specified for one name, the name is not predefined.

-n [--nesting] depth

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.

-t [--traceto] path

Enable the tracing facility build into the Wave library. The path specifies the filename to use for the output of the generated trace log. If the filename given equals to '-' (without the quotes), the trace log is put into the standard error stream (stderr).

--variadics

Enables support for variadics (macros with variable parameter lists), placemarkers (empty macro arguments) and operator _Pragma in normal C++ mode. This option predefines a special predefined macro __WAVE_HAS_VARIADICS__.

--c99

Enable the C99 mode. This mode enables certain C99 specific features as variadics (macros with variable parameter lists), placemarkers (empty macro arguments) and operator _Pragma support and disables some C++ specific token types as for '::', '->*' and '->.'. Several predefined macros are different for this mode, for more information about predefined macros you may look here.
Note that the --c99 and the --c++0x options are mutually exclusive. If both options are given a diagnostic is provided and the C99 mode is assumed.

--c++0x

Enable the (experimental) C++0x mode. This mode enables certain C++ features, which are to be proposed for the new C++ Standard as macro scopes, variadics, placemarkers and well defined pasting of unrelated tokens.
Note that the --c99 and the --c++0x options are mutually exclusive. If both options are given a diagnostic is provided and the C99 mode is assumed.

This option is available only, if the library was compiled with the WAVE_ENABLE_CPP0X_EXTENSIONS compile time constant defined (for more information about this constant please refere here).

@ [--config-file] option

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.

There is a shorthand for specifying a configuration file on the command line: simply use the '@' character immediatly before the corresponding file name.

The options found in a configuration file are interpreted, as if they were place instead of the configuration file option on the command line.

The Wave driver program looks at startup for a configuration file named 'wave.cfg' in the same directory, where it was startet 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 Wave preprocessor driver.


Last updated: Thursday, May 8, 2003 22:19