tracewpp(0) : error wpp : Unknown cmdline option: --help
Microsoft (R) TraceWPP.exe (10.0.19041)
(C) Microsoft Corporation. All rights reserved.
Usage: tracewpp [switches] source-file-names...
General behavior:
- Gather configuration settings from the command-line, the WPP_FLAGS
environment variable, the INI file(s), and any files specified via -Scan.
- Parse source code files (C or C++) to find calls to trace functions.
- Generate output files by processing templates using values from the
configuration settings and the source code files.
The relationship between source code files, templates, and output files is
controlled by the -gen option. If no -gen option is set, a default -gen option
is used. The default -gen option is "{km-default.tpl}*.tmh" if the -km switch
has been set and "{um-default.tpl}*.tmh" otherwise. The default -gen option
means that one .tmh file will be generated for each source file, and that the
.tmh file will be generated using the "um-default.tpl" template (or the
"km-default.tpl" template if the -km switch is used).
Input files that start with a UTF-8 or UTF-16 byte order mark will be parsed
as Unicode. Otherwise, input files will be parsed using the current Windows
code page (the code page returned by GetACP).
By default, output files will be written using the current Windows code page.
The -cp option can configure tracewpp to generate UTF-8 or UTF-16LE output.
Note that a template can override the output encoding, e.g. the manifest.tpl
template always generates UTF-8 output.
Note that the output generated by this tool depends on configuration (INI) and
template (TPL) files. The following documentation describes the behavior of
the tracewpp tool itself (e.g. how a command-line option affects a macro) and
also describes behavior of the Microsoft-provided configuration files and
templates (e.g. how a command-line option will affect the behavior of the
Microsoft-provided templates). The behavior may be different when this tool is
used with other configuration files or templates.
Refer to the defaultwpp.ini file for more information about the available
configuration options and the settings that are enabled by default.
General options:
-man:ManifestFile.man[,HeaderFile.h,Prefix]
****************************************************************
PREVIEW: Behavior of the -man option and the associated
configuration options may change in future versions of tracewpp.
****************************************************************
Configures tracewpp to use manifest-based WPP instead of the
traditional TMF-based WPP. Options after ManifestFile.man are
optional. If HeaderFile is omitted, it defaults to
"ManifestFile.h". If Prefix is omitted, it defaults to
"EventWrite". This switch is equivalent to the following WPP
configuration commands:
MANIFEST_CONFIGURATION(ManifestFile.man[,HeaderFile.h,Prefix]);
SEPARATE_TRACE_GUID_PER_FILE(0);
WPP_FLAGS(gen:{manifest.tpl}ManifestFile.man);
WPP_FLAGS(gen:{provider.tpl}*.tmh);
For the manifest to be useful, you may need to provide an INI or
scanned header file to specify additional configuration options
such as: MANIFEST_RESOURCES, DEFINE_CONTROL_GUID, and DEFINE_BIT.
-ctl:GUID Defines the WPP_DEFAULT_CONTROL_GUID macro with the specified
control GUID. This the same as -DWPP_DEFAULT_CONTROL_GUID=GUID
and is an alternative to defining the macro in the source file.
When this macro is defined, the default template will generate a
WPP_CONTROL_GUIDS definition with WPP_DEFINE_BIT entries named
"Error", "Unusual", and "Noise". (Not for use with -man.)
Example: -ctl:195b5884-edd3-400c-bcc8-cceb8c344c04
-DMacroName Adds "#define MacroName" to the output file.
-DMacroName=Value Adds "#define MacroName Value" to the output file.
-km Defines the WPP_KERNEL_MODE macro. This also changes the default
template. If -km is used, the default template will be
"km-default.tpl" instead of "um-default.tpl".
-um Defines the WPP_USER_MODE macro.
-p:ModuleName Overrides the value of the `CurrentDir` template variable. The
default value of `CurrentDir` is based on the current working
directory when tracewpp is launched. The default templates use
CurrentDir as the event's module name.
Search and formatting options:
-ArgBase:Number
Establishes a numeric base for numbering of format strings, such
as "%1!d!, %2!s!." The default is 1.
-func:FunctionName(ARG1,ARG2,ARG3,...)
Specifies the name and arguments for a trace function that
tracewpp should process. This is an alternative to specifying the
trace functions in an INI file or a scanned header. Any number of
functions can be defined. The default INI file defines the
following trace functions:
DoTraceMessage(LEVEL,MSG,...)
DoDebugTrace(TRACELEVEL,MSG,...)
-LookFor:SpecialSymbol
Directs WPP to search source files for the specified symbol. A
template can determine whether the symbol was found using the
FOUND operator in an IF statement. The default INI settings
direct tracewpp to look for the WPP_INIT_TRACING symbol. If the
WPP_INIT_TRACING symbol is found, the default templates will add
module initialization code to the generated TMH file.
-NoShrieks Directs WPP to try to parse multi-character type names from
format strings even when no exclamation marks are present.
By default, "%HRESULT" will parse as item of type "H" followed
by text "RESULT". With -NoShrieks, "%HRESULT" will parse as an
item of type "HRESULT".
File options:
@ResponseFile Specifies the name of an options response file. Tokens in the
file will be treated as if they were specified on the tracewpp
command line, i.e. they can be switches or source file names.
-IPath1[;Path2]
Specifies the location of configuration and template files. Path1
and Path2 represent the fully qualified path to a directory. If
no paths are specified via -I or -CfgDir, tracewpp uses the
current directory.
-CfgDir:Path1[;Path2...]
Same as -IPath1;Path2. (Deprecated. Use -I instead of -CfgDir.)
-DefWpp:Path Specifies an alternate primary configuration file. If -DefWpp is
not specified, tracewpp uses "defaultwpp.ini".
-ext:.ext1[.ext2.ext3...]
Specifies the file types that WPP recognizes as source files. The
default is ".c.cxx.cpp.c++". The tracewpp tool ignores files with
extensions not on this list. This behavior allows you to provide
an unfiltered list of files to tracewpp, and tracewpp will ignore
files it doesn't recognize such as .mc or .rc files.
-gen:{TemplateName}*.ext
Specifies that for each source file, tracewpp should read that
file and then invoke the specified template to generate an output
file. The output file will have the same name as the source file,
but will have the given file extension. For example,
-gen:{um-default.tpl}*.tmh means that for each source file,
tracewpp should use the um-default.tpl template to generate a
.tmh file with the definitions needed for that source file.
-gen:{TemplateName}OutputName
Specifies that tracewpp should process all of the source files as
a group and then invoke the specified template to generate the
specified output file. This can be used to generate one TMH file
per project.
-ini:File.ini Specifies an additional configuration file. WPP uses this file in
addition to "defaultwpp.ini". More than one -ini file may be
specified. If no -ini option is provided, "localwpp.ini" will be
used as a configuration file if it exists.
-oDir:Path Specifies the directory for the output files.
-cp:Encoding Specifies the text encoding for output files. By default, output
files are generated using the code page returned by the Windows
GetACP() function. Use -cp:UTF-8 or -cp:UTF-16 to generate
output files encoded as UTF-8 (with BOM) or UTF-16LE (with BOM).
Note that a template can override the output encoding, e.g. the
manifest.tpl template always generates UTF-8 output.
-PreserveExt:.ext1[.ext2.ext3...]
Preserves the specified file name extensions when creating TMH
files. By default, the TMH file for <filename>.<ext> will be
named <filename>.tmh. This can cause conflicts when you have more
than one source file with the same name but different extensions,
e.g. myfile.h and myfile.cpp. By using -PreserveExt:.h, the TMH
files would be named "myfile.h.tmh" and "myfile.tmh".
-Scan:File.h Instructs tracewpp to scan the specified file for
"begin_wpp config" blocks containing WPP configuration options,
or "begin_wpp enum" blocks containing enum definitions. Each
"begin_wpp" should be paired with an "end_wpp". This is typically
used to scan .h files so that configuration options can be
edited in source code.
-UnicodeIgnore If this switch is provided, tracewpp will ignore source code
files that start with a UTF-16 byte order mark (i.e. will treat
them as containing no trace function calls). This switch exists
because older versions of tracewpp were unable to parse UTF-16
text. In older versions of tracewpp, this switch simply
suppressed the error message that would have been raised for an
unparseable UTF-16 file. The current version of tracewpp can
parse UTF-8 (with BOM) and UTF-16 (with BOM), but retains this
flag for compatibility with the behavior of older versions.
Other options:
-ManifestFormats, -NoManifestFormats
Before Windows 10 19H1, TDH.dll was unable to load manifests
containing complex formatting (i.e. %1!X!). For compatibility,
tracewpp defaults to using only simple formatting in manifests
(i.e. %1!S!). Set -ManifestFormats to enable better formatting
(manifests will only load correctly on Windows 10 19H1 or later).
Set -NoManifestFormats (currently the default) to generate
manifests that use only simple formatting (manifests will be more
compatible with earlier versions of Windows).
-dll Defines the WPP_DLL macro. This is the same as -DWPP_DLL, and is
an alternative to defining the macro in the source file. In the
default templates, this macro is significant only for user-mode
WPP when WPP_MOF_RESOURCENAME is enabled: if WPP_DLL is set,
WPP_INIT_TRACING uses the AppName parameter as the DLL name to
use when locating MOF resources; without this macro set,
WPP_INIT_TRACING will look in the current process's EXE file to
locate MOF resources. In all other cases, the WPP_DLL macro has
no effect.
-IgnoreDupTypes Do not raise an error if configuration settings define the same
type more than once. The first definition will be used.
-v Write additional status information during processing (verbose).
-q By default, tracewpp returns 0 only on success. Use -q to always
return 0, even if tracewpp encountered an error.
-NoWppVersion Sets template variable `Compiler.Version` to a static value so
that output files do not change based on the specific version of
the tracewpp tool.
-NoDateTime Sets template variables `System.Date` and `System.Time` to static
values so that output files do not change based on time.
-NoEnvironment Disables tracewpp's use of environment variables. If this flag
is set, the WPP_FLAGS environment variable will be ignored. In
addition, any environment variables referenced by templates (e.g.
MAJORCOMP and MINORCOMP) will be treated as unset.
-PerfReport Prints tracewpp timing information.
-ArgLimit:n By default, tracewpp allows 32 arguments per trace statement. Use
the -arglimit option to change this limit.
-Reorder, -NoReorder
By default, tracewpp writes message arguments in the order they
appear in the source code. If -Reorder is set, tracewpp will sort
the arguments based on type priority and then type name. This can
reduce code size by minimizing the number of unique helper
functions required.
-DoNothing Stop processing arguments and exit immediately.
-MD5, -NoMD5 By default, tracewpp will generate trace GUIDs by hashing the
message data. This means that the trace GUIDs will not change
unless the message data changes, so you can use the same TMF
files to decode your logs as long as the source files are
unchanged. If -NoMD5 is set, tracewpp will use UuidGen instead,
so it will generate new GUIDs each time it runs.
-TimeChk Set -TimeChk to exit immediately if all output files already
exist and are newer than all source files. Note that this check
is very simple and might skip regenerating the output files even
if environment variables, INI files, or template files have
changed. In most cases, the default behavior (-NoTimeChk) should
be preferred since the hash check is much more accurate.
-NoHashChk By default, tracewpp will not overwrite an output file if the
existing file's checksum is the same as the new file's checksum.
This behavior helps optimize a build because tracewpp will not
update the timestamp of an already-up-to-date TMH output file.
Set -NoHashChk to skip this check (always overwrite the output).
Note that this checksum is comprehensive and will regenerate the
output if the new output file is different from the existing file
in any way. In particular, if the template references the Date or
Time macros, or if the -NoMD5 option is used, the new output will
always be different from the old output and the existing output
file will always be overwritten.
Implementation note: tracewpp expects to find "Checksum='...'"
at the start of the existing file. The checksum is computed as
the MD5 hash that the output file would have if all instances of
the checksum were removed.
-Public:Func Marks the named function as public. Public functions will omit
certain metadata from the TMF such as filename and line number.
-PublicFilter:(Func,Flag)
Marks the named function as conditionally public. The function
will be public if the WPP_PUBLIC_<Flag> macro is defined when the
file is compiled. This is the same as the
PUBLIC_FILTER(Func,Flag) configuration option.