The Wave Driver  Wave驅動器

There is implemented a driver program for the Wave 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:
Wave 庫中實現了一個驅動器程序,它採用了本庫幾乎所有的功能。它可以被用作在任意C++編譯器之上執行的一個預處理器。它輸出從給定的輸入文件生成的預處理單詞的文字表示。這個驅動器程序具有以下命令行語法:

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 [path] to use for output instead of
stdout or disable output [-]
-E [ --autooutput ]: output goes into a file named <input_basename>.i
-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 [-]
-m [ --macronames ] arg: list names of all defined macros to a file [arg] or
to stdout [-]
-p [ --preserve ] arg (=0): preserve whitespace
0: no whitespace is preserved (default),
1: comments are preserved,
2: all whitespace is preserved
-L [ --line ] arg (=1): control the generation of #line directives
0: no #line directives are generated
1: #line directives will be emitted (default)
-x [ --extended ]: enable the #pragma wave system() directive
-G [ --noguard ]: disable include guard detection
-s [ --state ] arg: load and save state information from/to the given
file [arg] or 'wave.state' [-] (interactive mode
only)

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.
可用的選項非常明瞭和清楚。以下是其中一些選項的細節。請注意,擴展選項(--c99 和 --variadics)僅當驅動器在編譯時帶有常量 WAVE_SUPPORT_VARIADICS_PLACEMARKERS 定義時有效。

-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). If the filename given equals to '-' (without the quotes), no output is generated initially. This is especially useful for syntax checks only or in conjunction with the #pragma wave option(output: ...) directive restricting the generated out to specific parts only (for a description see the section Supported Pragma Directives).
指定一個文件名,用於生成的預處理輸出流。如果該選未給出,則使用標準輸出(stdout)。如果給定的文件名為'-'(不帶引號),則不生成輸出。在僅僅進行語法檢查或者使用了 #pragma wave option(output: ...) 指令限制特定部分輸出(相關說明請見 支持的Pragma指令 一節)時,這很有用。

-E [--autooutput]

The generated output will end up in a file named after the input file basename with the file extension '.i', i.e. for an input file 'inputfile.cpp' the output will be written to 'inputfile.i'. This option will not have any effect if there is specified an output file name with a --output option.
生成結果輸出至一個以輸入文件的基本名加上擴展名'.i'為名的文件,例如對於輸入文件'inputfile.cpp',輸出將寫至'inputfile.i'。如果已經用 --output 選項指定了一個輸出文件名,則本選項無效。

-I [--include] option

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.
向 頭文件查找目錄列表的前頭加入目錄 dir。這可以用於覆蓋系統頭文件,替換為你自己的版本,因為加入的目錄將在系統頭文件目錄之前被查找。不過,你不應該用這個選項來增加含有廠家提供的系 統頭文件(請用 '-S')的目錄。如果你用了一個以上的 '-I' 選項,則這些目錄會按從左至右的順序進行掃瞄,然後是標準的系統目錄。

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.
如果標準的系統包含目錄,或某個以'-S'指定的目錄,也被以'-I'指定,則'-I'選項被忽略。該目錄仍然會被查找,只不過是在系統包含目錄鏈的正常位置被當作系統目錄來查找。

-I- [--include-] option

The Wave 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.
Wave 庫維護了兩個獨立的頭文件查找路徑。一個查找路徑用於用戶頭文件,另一個查找路徑用於系統頭文件,用戶頭文件路徑在系統頭文件路徑之前查找。

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.).
在'-I'選項之前的所有以'-I'選項指定的目錄,只用於對 '#include "file"' 指令(用戶頭文件)的文件進行查找,不會用於對 '#include <file>' 指令(系統頭文件)的文件進行查找。而在'-I-'之後以'-I'選項指定的目錄,則用於所有'#include'指令的文件查找(原先所有的 '-I' 指令均使用此方法)。

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.
另外,'-I-'選項禁止了將當前目錄(即當前輸入文件所在目錄)作為 '#include "file"' 指令的第一個查找目錄。通過 '-I.',你可以指定查找執行編譯時的當前目錄。這與預處理器的缺省行為不完全一樣,不過通常也夠了。

-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.
向系統頭文件查找目錄列表的前頭加入給定目錄。如果你使用了一個以上的 '-S' 選項,這些目錄會按從左至右的順序進行掃瞄。該選項非常有用,可在 wave.cfg 配置文件中指定在哪查找系統頭文件。

-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.
該選項允許從命令行定義('-D')或預定義('-P')一個宏。與 '-D' 或 '-P' 選項一起給出的字符串必須符合常用語法 MACRO(x)=definition,更多詳細說明請見此處

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.
'-D' 選項和 '-P' 選項的區別在於,後者是預定義一個宏,即這個宏不能從預處理的程序內部通過 #undef 指令來去定義。

-U [--undefine] macro

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.
該選項可以對 Wave 庫自動的預定義的宏(請見 預定義宏)進行去定義。唯一的例外是 __LINE__, __FILE__, __DATE__, __TIME__, __STDC____cplusplus 這些預定義宏,它們不可以被去定義。如果對同一個名字同時指定了 -U 和 -D,則該名字不是預定義的。

-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.
指定一個新的最大嵌套深度。如果預處理達到了這個頭文件嵌套深度,將發出一個錯誤信息,然後退出。缺省的頭文件嵌套深度為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).
將跟蹤工具構建入 Wave 庫。path 指定用於生成跟蹤日誌輸出的文件名。如果給定的文件名為'-'(不帶引號),則跟蹤日誌被輸出至標準錯誤流(stderr)。

--timer

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.
啟用對給定輸入文件所用的全部處理時間的跟蹤。當編譯完成時,所用時間被打印到 stdout。

--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__.
在正常C++模式下,啟用對 variadics (具有可變參數列表的宏), placemarkers (空的宏參數) 和 operator _Pragma 的支持。該選項預定義了一個專門的預定義宏 __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 instance '::', '->*' and '->.'. Several predefined macros are different for this mode, for more information about predefined macros you may look here.
啟用C99模式。該模式啟用對C99專有特性,如 variadics (具有可變參數列表的宏), placemarkers (空的宏參數) 和 operator _Pragma 的支持,並禁用一些C++專有的單詞類型,如 '::', '->*''->.'。在此模式下,有幾個預定義宏有所不同,關於預定義宏的更多信息請見這裡

-l [--listincludes] path

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 '-' (without the quotes), the include log is put into the standard output stream (stdout).
啟用對所有被打開的頭文件的名字的輸出。path 指定了輸出所生成的包含日誌的文件名。如果給定的文件名為'-'(不帶引號),則包含日誌被輸出至標準輸出流(stdout)。

-m [--macronames] path

Enable the output of all defined macros. This includes the macro names, its parameter names (if the macro is a function like macro) and its definition. The path specifies the filename to use for the output of the generated macro list. If the filename given equals to '-' (without the quotes), the macro list is put into the standard output stream (stdout).
啟用對所有被定義宏的輸出。包括宏名、參數名(如果該宏為函數宏)及其定義。path 指定了輸出所生成的宏列表的文件名。如果給定的文件名為'-'(不帶引號),則宏列表被輸出至標準輸出流(stdout)。

-p [--preserve] arg

Preserve the whitespace from the input stream not located inside of macro definitions. The argument defines the amount of whitespace to be preserved. A value of '0' (zero) skips all whitespace, a value of '1' preserves all the comments and a value of '2' will preserve all whitespace in the output.
保留輸入流中不在宏定義內的空白。參數定義了要保留的空白數量。值'0'(零)跳過所有空白,值'1'則保留所有註釋,值'2'則保留在輸出 中所有空白。

The comments located inside macro definitions are skipped even if this option is specified with an argument not '0' (zero) . If this option is not specified on the command line only essential whitespace is preserved (equivalent to '0' as the argument value).
即使該選項指定了一個非'0'(零)的參數,在宏定義內的註釋還是會跳過。如果在命令行中未指定該選項,則只保留基本的空白(等價於參數值為 '0')。

-L [--line]

Controls whether the Wave tool generates #line directives or not. If the argument is '1' these will be emitted, if the argument value is '0' no #line directives will be generated. If this option is not specified, Wave always will generate #line directives.
控制 Wave 工具是否生成 #line 指令。如果參數為 '1' 則生成,如果參數值為 '0' 則不生成 #line 指令。如果該選項未指定,則 Wave 總是生成 #line 指令。

-x [--extended]

Enable the #pragma wave system() directive. This directive is now disabled by default because it may cause a potential security threat. The Wave driver will issue a remark if this command line argument is not specified and a #pragma wave system() directive is encountered.
啟用 #pragma wave system() 指令。該指令現在是缺省關閉的,因為它可能會引起潛在的安全威脅。如果未指定這個命令行參數且遇到 #pragma wave system() 指令,則 Wave 驅動器將生成一個標記。

-G [--noguard]

This option disables the automatic include guard detection normally performed by the Wave library during the processing of included files. For more information about automatic include guard detection please refer to The Context Object class reference.
該選項在處理包含文件時禁止 Wave 庫正常執行的自動包含防衛檢測。有關自動包含防衛檢測的更多信息,請參考 上下文對像 的類參考。

-s [--state]

This option tries instructs the Wave tool to load the serialized information from the file given as the argument and to save back the internal state information at the end of the session to the same file. When using this option Wave loads and saves all defined macros (even the predefined ones) and the information about processed header files tagged with #pragma once and/or identified to have include guards.
該選項嘗試指示 Wave 工具從參數給定的文件中導入序列化信息,以及在會話結束時將內部的狀態信息存回同一個文件。使用這個選項時,Wave 將導入和保存所有被定義的宏(甚至是預定義宏)以及那些帶有 #pragma once 標籤和/或標識為帶有包含防衛的頭文件是否已處理的信息。

Note: This option has effect in interactive mode only.
註:該選項僅在交互模式下有效。

@ [--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.e. -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:
一些命令行選項可以在特定的配置文件中指定。這很有用,可以作為不同全局配置的縮寫。配置文件可以包含其它選項(如 -I, -S, -F, -U, -D 和 -P 選項),每個選項一行。空行和以'#'字符開始的行被忽略(被視為註釋行)。注意,只有當'#'字符是一行中的第一個非空白字符時,它再被視為註釋行的開始。以下是一個小型示例,示範了所支持的配置文件語法:

    # 
# enable variadics et.al. in C++ mode
#
--variadics #
# enable timer support
#
--timer
#
# emulate gcc V3.3.2
#
-D__GNUC__=3
-D__GNUC_MINOR__=3
-D__GNUC_PATCHLEVEL__=2
-D__GNUG__
#
# add Boost to the system include search paths
#
-S/usr/local/boost

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 at startup looks for a configuration file named 'wave.cfg' in every directory up the file system hierarchy starting from the directory where the input file is located. The first file found stops the search. If a 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.
Wave 驅動器程序啟動時會從輸入文件所在目錄開始沿文件系統層次向上在每個目錄中查找一個名為 'wave.cfg' 的配置文件。找到第一個文件即停止查找。如果存在這樣一個文件,則視之為一個普通的配置文件對其中的選項進行解釋,就像這些選項是作為命令行中最前面的選 項那樣。這一特性對於為 Wave 預處理器驅動器定義一個全局環境非常有用。