/analyze (Code analysis)
Enables code analysis and control options.
General analysis options:
Analysis plugin options:
External file analysis options:
Analysis log options:
Log file format options:
Log file content options:
General analysis options
Turns on code analysis. Use
/analyze- to explicitly turn off analysis.
/analyze- is the default behavior.
By default, analysis output goes to the console or the Visual Studio Output window like other error messages. Code analysis also creates a log file named
filename is the name of the analyzed source file.
By default, the compiler compiles the code to generate object files before code analysis runs. The
/analyze:only option makes the compiler skip the code generation pass, and does code analysis directly. Compiler errors still prevent code analysis from running. However, the compiler won't report other warnings that it might find during the code generation pass. If the program isn't free of code-generation warnings, analysis results might be unreliable. We recommend you use this option only if the code passes code-generation syntax checks without errors or warnings.
Turns off analysis output to the console or Visual Studio Output window.
number parameter specifies the maximum number of code paths to analyze. Analysis defaults to 256 paths. Larger values cause more thorough checking, but the analysis might take longer.
number parameter specifies the size in bytes of the stack frame that generates warning C6262. The default stack frame size is 16KB.
Tells the compiler not to treat code analysis warnings as errors even when the
/WX option is used. For more information, see
/WX (Warning level).
Analysis plugin options
Enables the specified code analysis plug-in DLL for code analysis.
/analyze:plugin and the
plugin_dll file path is optional if the path doesn't require double-quotes (
"). For example, you can write
/analyze:plugin EspxEngine.dll. However, if the path is enclosed in double-quotes, you can't have a space between
/analyze:plugin and the file path. Here's an example:
The code analysis engine uses plug-ins to help find specific categories of defects. The code analysis engine comes with some built-in plug-ins that detect various defects. To use another plug-in with the code analysis engine, specify it by using the
LocalEspC.dll, use compiler option
Some plug-ins, like
EspXEngine.dll, which ships with Visual Studio, employ extensions that can do further analysis. Visual Studio includes these extensions for EspXEngine:
VariantClear.dll. They check for defects for concurrency issues, CppCoreGuidelines violations, inappropriate uses of
enum values as indexes,
HRESULT values, or
VARIANT values, respectively.
When you build on the command line, you can use the
Esp.Extensions environment variable to specify EspXEngine extensions. For example:
Use a semicolon (
;) to delimit the extensions, as shown in the example. A trailing semicolon isn't needed. You can use an absolute file path for an extension, or specify a relative path from the directory that contains
If you're building in a developer command prompt window, first set the
Esp.Extensions environment variable to specify the
Then, use compiler option
/analyze:plugin EspXEngine.dll to use the EspXEngine plug-in.
External file analysis options
Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. Use the
/external:anglebrackets options to specify directories as "external" directories. Any files that are included by using
#includefrom an external directory or its subdirectories are considered as external headers. For more information, see
/external (External headers diagnostics).
Code analysis provides these options to control analysis of external files:
Skips analysis of external header files. By default, code analysis analyzes external header files just like other files. When the
/analyze:external- option is set, code analysis skips any files specified as external, except templates from external files. Templates defined in external headers are treated as non-external by using the
/external:templates- option. The
/external:Wn option doesn't affect code analysis. For example, code analysis analyzes external files and reports defects even when
/external:W0 is specified.
ruleset_files parameter specifies one or more semicolon-delimited ruleset files to use for analysis of external files. For information on rulesets, refer to "Options for rulesets" section.
There's an environment variable (
CAExcludePath) that provides similar but simpler capability to skip analysis of files under the directories specified in the environment variable. If a directory is specified in both
/external:* option and in the
CAExcludePath environment variable, it's considered as excluded, and
/analyze:external* options won't apply to that directory.
Analysis log options
This flag used to be required to enable creation of analysis log file for each of the source files being analyzed. Log files are now created by default, so this flag is mostly redundant. When used, it changes the default log extension to
*.pftlog instead of
/analyze:autolog- to disable logging to files.
Overrides the default extension of the analysis log files, and uses
extension instead. If you use the
.sarif extension, the log file uses the SARIF format instead of the default XML format.
Specifies a log file path
log_path instead of the automatically generated log file path. When the
log_path path has a trailing backslash and refers to an existing directory, code analysis creates all log files in the specified directory. Otherwise,
log_path specifies a file path. A file path instructs the compiler to combine logs for all analyzed source files into the specified log file. If the file path has a
.sarif extension, the log file uses the SARIF format instead of the default XML format. You can override this behavior by using the
Log file format options
Starting in Visual Studio 2019 version 16.9, you can specify different log format options for code analysis.
Forces the use of XML log format irrelevant of the file extension used.
Forces the use of SARIF log format irrelevant of the file extension used.
Log file content options
Starting in Visual Studio 2019 version 16.9, you can specify different log content options for code analysis.
Adds file artifacts entries to the SARIF log file for analyzed files that don't issue warnings. This option is disabled by default. Artifacts for the source file and for files that emitted results are always included.
Adds rule configuration entries to determine how the user overrode the default rule configuration (disabled by default).
Adds both any defects the analysis engine finds, and all compiler warnings, to the analysis log file. By default, compiler warnings aren't included in the analysis log file. For more information on compiler warnings during code analysis, see the
Adds both suppressed warnings and unsuppressed warnings to the analysis log file. By default, suppressed warnings aren't included in the analysis log file. If ruleset files are specified for analysis, the warnings disabled by the ruleset files aren't included in the log even when
/analyze:log:includesuppressed is specified.
Specifies the current project directory. If the ruleset (or an item it includes) is a file name, the compiler first looks for the file under the specified
project_directory. If not found, it next searches the
ruleset_directories specified by
/analyze:rulesetdirectory, if any. If the ruleset (or an item it includes) is a relative path, the compiler first looks for the file under the project directory. If the ruleset isn't found, then it looks in the current working directory. This option is available starting in Visual Studio 2019 version 16.9.
Specifies a semicolon-separated list of ruleset search paths. If the ruleset (or an item it includes) is a file name, then the compiler first looks for the file under the
project_directory specified by
/analyze:projectdirectory, if any, followed by the specified
ruleset_directories. This option is available starting in Visual Studio 2019 version 16.9.
Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled.
Specifies a ruleset file to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled.
The ruleset files that ship with Visual Studio are found in
%VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets.
The following example custom ruleset tells the analysis engine to check for C6001 and C26494, and report them as warnings.
You can place this file anywhere as long as you specify the full path in the argument.
You can place this file anywhere as long as you specify the full path in the argument, or under the directories specified in the
<?xml version="1.0" encoding="utf-8"?> <RuleSet Name="New Rule Set" Description="New rules to apply." ToolsVersion="15.0"> <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native"> <Rule Id="C6001" Action="Warning" /> <Rule Id="C26494" Action="Warning" /> </Rules> </RuleSet>
By default, the file extension for ruleset files is
*.ruleset. Visual Studio uses the default extension when browsing for ruleset files. However, you can use any extension.
For more information about rulesets, see Use rule sets to specify the C++ rules to run.
To set this compiler option in the Visual Studio development environment
Open the project's Property Pages dialog box. For details, see Set C++ compiler and build properties in Visual Studio.
Select the Configuration Properties > Code Analysis > General property page.
Modify one or more of the Code Analysis properties.
Choose OK or Apply to save your changes.
To set external file analysis options in Visual Studio 2019 version 16.10 and later:
Open the project's Property Pages dialog box.
Select the Configuration Properties > C/C++ > External Includes property page.
Disable Code Analysis for External Headers sets the
Analysis Ruleset for External Headers sets the
Choose OK or Apply to save your changes.
To set this compiler option programmatically
- See EnablePREfast.