波形驱动程序

已实现一个用于波形库的驱动程序，它利用了库的几乎所有功能。它可以用作任何其他 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)
    --c++11:                     enable C++11 mode (implies --variadics and --long_long)
    --c++20:                     enable C++20 mode (adds __VA_OPT__ to variadics)
                                                   (implies --variadics and --long_long)
    -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 [-]
    -c [ --macrocounts ] arg     list macro invocation counts to a file [arg] or to
                                 stdout [-]
    -p [ --preserve ] arg (=0):  preserve whitespace
                                 0: no whitespace is preserved (default),
                                 1: begin of line whitespace is preserved,
                                 2: comments and begin of line whitespace is preserved,
                                 3: 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
    -g [ --listguards ]:         list names of files flagged as 'include once' to a
                                 file [arg] or to stdout [-]
    -s [ --state ] arg:          load and save state information from/to the given
                                 file [arg] or 'wave.state' [-] (interactive mode
                                 only)

可能的选项非常简单，不言自明。以下将更详细地描述其中一些选项。请注意，扩展选项（--c99 和 --variadics）仅在使用常量编译驱动程序时可用WAVE_SUPPORT_VARIADICS_PLACEMARKERS定义。

-o [--output] 路径

指定用于生成的预处理输出流的文件名。如果没有给出此选项，则使用标准输出（stdout）。如果给定的文件名等于'-'（不带引号），则不会生成任何输出。这对于仅进行语法检查或与 #pragma wave option(output: ...) 指令结合使用，以限制生成的输出到特定部分（有关说明，请参见部分 支持的预处理指令）。

-E [--autooutput]

生成的输出将最终存储在以输入文件名基名为文件名，文件扩展名为 '.i' 的文件中，即对于输入文件 'inputfile.cpp'，输出将写入 'inputfile.i'。如果使用 --output 选项指定了输出文件名，则此选项将不起作用。

-I [--include] 选项

将目录 dir 添加到搜索头文件的目录列表的开头。这可用于覆盖系统头文件，替换您自己的版本，因为这些目录在系统头文件目录之前搜索。但是，您不应使用此选项添加包含供应商提供的系统头文件的目录（为此使用 '-S'）。如果您使用多个 '-I' 选项，则按从左到右的顺序扫描目录，标准系统目录位于之后。

如果标准系统包含目录或使用 '-S' 指定的目录也使用 '-I' 指定，则将忽略 '-I' 选项。该目录仍将被搜索，但作为系统目录，位于系统包含链中的正常位置。

-I- [--include-] 选项

该波形库为包含文件维护两个独立的搜索路径。用户包含文件的搜索路径和系统包含文件的搜索路径，其中用户包含路径在系统包含路径之前搜索。

在最终给定的 '-I-' 选项之前使用 '-I' 选项指定的任何目录，仅在 '#include "file"'（用户包含文件）的情况下搜索，它们不会在 '#include <file>' 指令（系统包含文件）的情况下搜索。如果在给定 '-I-' 选项之后使用 '-I' 选项指定了其他目录，则这些目录将用于所有 '#include' 指令（通常所有 '-I' 目录都以这种方式使用）。

此外，'-I-' 选项会抑制将当前目录（当前输入文件所在的目录）用作 '#include "file"' 指令的第一个搜索目录。使用 '-I.'，您可以指定搜索编译器调用时的当前目录。这与预处理器默认执行的操作并不完全相同，但通常令人满意。

-S [--sysinclude] 选项

将给定目录添加到搜索系统头文件的目录列表的开头。如果您使用多个 '-S' 选项，则按从左到右的顺序扫描目录。此选项在 wave.cfg 配置文件中非常有用，用于指定系统包含文件所在的位置。

-F [--forceinclude] 选项

将给定文件作为正常输入进行处理，并在处理常规输入文件开始之前包含所有生成的输出。如果给出了多个此类选项，则这些文件按其在命令行上的出现顺序进行预包含。

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

此选项允许从命令行定义 ('-D') 或预定义 ('-P') 宏。与 '-D' 或 '-P' 选项一起给出的字符串应符合通常的语法 MACRO(x)=definition，如 此处 所述。

'-D' 和 '-P' 选项之间的唯一区别在于，后者预定义了一个宏，使得它无法通过#undef来自预处理程序内部的指令。

-U [--undefine] macro

这允许取消定义波形库（请参见 预定义的宏）的一些自动预定义宏。唯一的例外是 __LINE__、__FILE__、__DATE__、__TIME__、__STDC__ 和 __cplusplus 预定义宏，它们无法取消定义。如果同时为一个名称指定 -U 和 -D，则不会预定义该名称。

-n [--nesting] depth

指定新的最大包含嵌套深度。如果预处理达到此包含文件嵌套深度，它将在发出错误消息后中止预处理。默认包含文件嵌套深度为 1024。

-t [--traceto] path

启用波形库中内置的跟踪功能。路径指定用于生成跟踪日志输出的文件名。如果给定的文件名等于'-'（不带引号），则跟踪日志将放入标准错误流（stderr）。

仅对输入中明确启用了跟踪的部分执行跟踪，方法是使用#pragma wave trace(enable)或_Pragma("wave trace(enable)")指令。请参见 此处 了解详细信息。

--timer

启用跟踪给定输入文件所需的总运行时间。编译完成后，运行时间将打印到 stdout。

--variadics

启用对可变参数（具有可变参数列表的宏）、占位符（空宏参数）和operator _Pragma在普通 C++ 模式下的支持。此选项预定义了一个特殊的预定义宏__WAVE_HAS_VARIADICS__.

--c99

启用 C99 模式。此模式启用某些 C99 特定功能，例如可变参数（具有可变参数列表的宏）、占位符（空宏参数）和operator _Pragma支持，并禁用一些 C++ 特定的令牌类型，例如'::', '->*'和'->.'。此模式下，几个预定义宏有所不同，有关预定义宏的更多信息，请参见 此处。

--c++11

启用 C++11 模式。此模式启用 C++11 特定关键字和功能，例如可变参数（具有可变参数列表的宏）、占位符（空宏参数）和operator _Pragma支持。此模式下，几个预定义宏有所不同，有关预定义宏的更多信息，请参见 此处。

-l [--listincludes] path

启用所有打开的包含文件的名称的输出。路径指定用于生成包含日志输出的文件名。如果给定的文件名等于'-'（不带引号），则包含日志将放入标准输出流（stdout）。

-m [--macronames] path

启用所有已定义宏的输出。这包括宏名称、其参数名称（如果宏是函数式宏）及其定义。路径指定用于生成宏列表输出的文件名。如果给定的文件名等于'-'（不带引号），则宏列表将放入标准输出流（stdout）。

-c [--macrocounts] path

启用所有宏调用计数的输出。路径指定用于生成列表输出的文件名。如果给定的文件名等于'-'（不带引号），则宏列表将放入标准输出流（stdout）。

-p [--preserve] arg

保留输入流中的空白，这些空白不位于宏定义内部。参数定义要保留的空白量。值为 '0'（零）将跳过所有空白，值为 '1' 仅保留行首空白，值为 '2' 将保留所有注释和所有行首空白，值为 '3' 将保留输出中的所有空白。

位于宏定义内部的注释将被跳过，即使此选项指定的参数不为 '0'（零）。如果此选项未在命令行上指定，则仅保留基本空白（等效于 '0' 作为参数值）。

-L [--line]

控制波形工具是否生成 #line 指令。如果参数为 '1'，则将发出这些指令，如果参数值为 '0'，则不会生成任何 #line 指令。如果未指定此选项，波形始终会生成 #line 指令。

-x [--extended]

启用 #pragma wave system() 指令。此指令现在默认情况下被禁用，因为它可能会导致潜在的安全威胁。如果未指定此命令行参数并且遇到 #pragma wave system() 指令，则波形驱动程序将发出一个备注。

-G [--noguard]

此选项会禁用 Wave 库在处理包含文件期间通常执行的自动包含保护检测。有关自动包含保护检测的更多信息，请参见 上下文对象 类参考。

-g [--listguards] arg

此选项列出所有找到的包含文件，这些文件要么包含 #pragma once，要么包含到给定文件中的包含保护。如果给定的文件名等于'-'（不带引号），则保护日志将放入标准输出流（stdout）。有关自动包含保护检测的更多信息，请参见 上下文对象 类参考。

-s [--state]

此选项尝试指示波形工具从作为参数给出的文件中加载序列化信息，并在会话结束时将内部状态信息保存回同一文件。使用此选项时波形加载并保存所有定义的宏（包括预定义的宏）以及有关使用 #pragma once 标记或已识别为具有包含保护的已处理头文件的信息。

注意：此选项仅在交互模式下有效。

@ [--config-file] 选项

一些可能的命令行选项可以在特殊的配置文件中指定。这非常有用，作为不同全局配置的简写。配置文件可以包含其他选项（即 -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

在命令行上指定配置文件有一个简写：只需在相应文件名之前立即使用 '@' 字符。

在配置文件中找到的选项被解释为，就好像它们被放置在命令行上的配置文件选项而不是配置文件选项本身一样。

该波形驱动程序在启动时会查找名为 'wave.cfg' 的配置文件，从输入文件所在的目录开始，一直向上遍历文件系统层次结构。找到的第一个文件将停止搜索。如果存在文件，则将其视为正常配置文件，并且其中指定的选项被解释为，就好像它们是在命令行上作为第一个选项给出的。波形预处理器驱动程序。

版权所有 © 2003-2011 Hartmut Kaiser

根据 Boost 软件许可证版本 1.0 发布。（请参见随附的 LICENSE_1_0.txt 文件或复制到 https://boost.ac.cn/LICENSE_1_0.txt）

最后更新2020 年 2 月 16 日星期日 15:05