Code Analysis with PVS-Studio from the Command Line
- Running project analysis from the command line using Visual Studio (with vcproj\vcxproj project files present)
- An example of running project analysis from the command line with the visible Visual Studio UI window
- An example of using the batch analysis mode when running project analysis from the command line
- The PVS-Studio Command Generator auxiliary utility
- Running project analysis from the command line with the IDE window disabled
This section explains how to run PVS-Studio from the command line instead of directly doing it through the IDE (Visual Studio) to analyze your projects. This way of launching the tool can be applied in developer teams using continuous integration systems (such as Cruise Control, Draco.NET, or Team Foundation Build from Visual Studio Team System).
PVS-Studio allows you to analyze projects built both by Visual Studio's build system and any other build systems given that they use the following compilers: Visual C++, GCC (MinGW), or Clang.
Running project analysis from the command line using Visual Studio (with vcproj\vcxproj project files present)
|We have a special utility to make it easier for you to generate the necessary command line parameters. For details, please refer to the PVS-Studio Command Generator subsection further in this article.|
If your project is built with Visual Studio's build system (vcproj\vcxproj project files), you can analyze it from the command line using the same standard mode as for "manual" analysis from Visual Studio. It means the analysis itself will be started through the devenv.exe application.
You can launch the analysis from the command line by using Visual Studio's command "PVSStudio.CheckSolution". This command is integrated into the IDE by the PVS-Studio plugin and, like any other standard command, can be called from the command line by using the '/command' argument or directly from the IDE in the Commands window. You also need to pass the path to the .sln file you want analyzed into the Visual Studio (as a separate argument). Once the IDE is opened and loaded, this command will pass the control directly into the PVS-Studio plugin. Let's examine the format of this command:
%devenvPath% "%solution%" /command "PVSStudio.CheckSolution %platform%|%configuration%|%plog%|%filelist%|%preprocessor%|%suppressMarker%"
%devenvPath% - path to the Visual Studio executable (devenv.exe) with the PVS-Studio plugin installed.
"%solution%" - path to the solution file (.sln) with the projects to be analyzed
%platform% - target project platform
%configuration% - target project configuration
%plog% - location and name of the PVS-Studio XML plog file which will be generated when all the files have been analyzed
%filelist% - location and name of the text file with the list of C/C++ source files to be analyzed. This parameter will allow you to analyze only those files you explicitly specify in this list if you don't need to analyze all the projects in a solution. If a file specified in the list is absent from the project being analyzed, it is skipped. This parameter is optional; without it, PVS-Studio will just analyze all the files in the solution's projects. We will describe this batch analysis mode in more detail a bit later, in one of the following subsections.
%preprocessor% - preprocessor to be used when analyzing the source files. PVS-Studio can use 2 preprocessors: the IDE's native preprocessor (i.e. cl.exe for Visual Studio, the parameter's value is VisualCPP) or a faster third-party preprocessor clang (the parameter's value is Clang). This parameter is optional. If you haven't specified it, PVS-Studio will by default make an attempt to preprocess the files with clang and then try cl should any errors occur (clang may occasionally fail to process MSVC headers correctly).
%suppressMarker% - enabling automatic suppression of new messages. Possible values:
- SuppressAll - add all the generated messages into the suppression databases.
If this marker is set, all the diagnostic messages will be added into the database of suppressed messages after saving the analysis log file (%plog%). Using this mode, you will only see messages generated for newly written/changed code at each analyzer run; that is, new messages will be written into the new log and get immediately suppressed so that you don't see them at the next run. However, if you need to view old messages (without having to re-run the analysis on the project), you can view them anytime by opening the complete-log file which is automatically saved in the same folder with the new-messages log file. To learn more about the message suppression mode, see this documentation section.
The last three parameters (%preprocessor%, %filelist%, and %suppressMarker%) are optional, but when skipping one of them, you still need to use the dividing vertical bar character '|' (that is, if you skip the %filelist% parameter, the command line will look like this: %platform%|%configuration%|%plog%||%preprocessor%, notice the double dividing vertical bar ||).
An example of running project analysis from the command line with the visible Visual Studio UI window
Assume we have the OmniSample project located in C:\Users\TestUser\Documents\OmniSample and we need to scan it in Visual Studio 2013. To do this, we only need to pass in the command line the following command (arguments specifying the source folders cannot end with the \ character because the character sequence \" is not always processed correctly by the operating system):
C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe "C:\Users\TestUser\Documents\OmniSample\OmniSample.sln" /command "PVSStudio.CheckSolution x64|Release|C:\Users\TestUser\Documents\result.plog"
After that, the corresponding devenv.exe version will be launched and the "OmniSample.sln" solution will open with the x64 architecture and Release configuration selected by default, and PVS-Studio will start the analysis. Once it is over, the log with the analysis results will be saved in the C:\Users\TestUser\Documents\result-log.plog file and Visual Studio will be closed. Later, you can open the log in the IDE through the "Open/Save|Open Analysis Report..." command in the PVS-Studio menu or by double-clicking on it directly in the file manager to comfortably view it in the usual environment with the code navigation, filters, and all the rest functionality of PVS-Studio.
If the project is correct and all the parameters have been defined correctly as well, the analysis will be finished in a certain time, the window will be closed, and you will be able to open the result-log.plog file. But if something goes wrong, the corresponding error message will be written into a text file named %plog%.exceptions, where %plog% is the name of the log file specified in the command line, in the same folder where this log file is located.
When running analysis from the command line, PVS-Studio, by default, scans all the files of the projects of the specified Visual Studio solution file. However, in case you need to analyze only a certain set of files, you can use the batch analysis mode, where only explicitly specified files will be analyzed. To launch the analyzer in the batch analysis mode, you need to specify the path to the list containing the paths of the files to be analyzed as a command line parameter (optional).
To analyze the files in the batch mode from the command line, you need to run analysis with the following parameters:
C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe "C:\Users\TestUser\Documents\OmniSample\OmniSample.sln" /command "PVSStudio.CheckSolution x64|Release|C:\Users\TestUser\Documents\result.plog| C:\Users\TestUser\Documents\ OmniSample\ExtFilelist.txt "
It is necessary that all the C++ files listed in the filelist file should be included into the projects of the solution under analysis. The list should contain full paths to C++ files separated by newline (\r\n) characters. The supported file extensions are c, cc, cpp, and cxx, i.e. the compilable files.
Here's an example of the text file ExtFilelist.txt (one file path per line):
PVS-Studio Command Generator is an auxiliary utility allowing you to generate a command to run project analysis from the command line instead of directly from the IDE (Visual Studio). The command line can be composed manually as described earlier or by using this utility.
The program interface is shown in Figure 1.
Figure 1 - PVS-Studio Command Generator's interface
All the parameters needed for composing a command line are self-evident and have been described before.
PVS-Studio Command Generator is designed to work on the Windows platform with .NET Framework 2.0. At the same time, it doesn't require you to have an installed copy of PVS-Studio or IDE (Microsoft Visual Studio) to work properly. In other words, you can generate a command line on a computer without PVS-Studio and take it to a different computer with PVS-Studio installed. If you have the IDE installed, the real path to the IDE's executable file is inserted into the generated command line. Otherwise, the default path is used, which only disables the analyzer's test mode, while the generated command line remains executable on any other machine with the required IDE installed, so you will only need to fix the path to the IDE's executable file if necessary.
If you need to hide the IDE window, you can run the analysis using a small script file written in Visual Basic Script (vbs). vbs is supported by every modern Windows version.
So, you need to create a run-PVS-Studio.vbs file consisting of the following five lines (an example for Visual Studio):
Set oShell = CreateObject("WScript.Shell")
DevEnv8 = """c:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe """
SolFile = """C:\Users\TestUser\Documents\OmniSample\OmniSample.sln"""
Cmd = " /command ""PVSStudio.CheckSolution Win32|Debug|C:\Users\TestUser\Documents\result-log.plog"""
strCommand = oShell.Run(DevEnv8+SolFile+Cmd, 0, True)
All the parameters here resemble those of an ordinary command file (as in the previous section) except that the analysis in this case is run through a special function Run which has, among other parameters, one to hide the window.
Open the saved file. You won't see the Visual Studio window but the devenv.exe process will be there in the list among other processes. The result-log.plog file will be created in the usual way in the folder you have specified.
Running analysis from the command line for projects built in build systems other than Visual Studio's
If your project doesn't use Visual Studio's standard build systems (VCBuild\MSBuild) or even uses a custom build system \ make files through Visual Studio NMake projects, you won't be able to analyze this project with the IDE PVS-Studio plugin and, consequently, run the analysis by calling the devenv.exe file from the command line.
If this is the case, you can use the compiler monitoring system that allows you to analyze projects regardless of the build systems they use by "intercepting" compilation process invocations (the supported compilers are CL, MinGW GCC, and Clang). The compilation monitoring system can be used both from the command line and through the UI of the Standalone utility.
You can also integrate the invocation of command line analyzer kernel directly into your build system. Notice that this will require you to define the PVS-Studio.exe analyzer kernel call for each file to be compiled, just like in the case when calling the C++ compiler.
How PVS-Studio settings affect the command line launch; analysis results (plog file) filtering and conversion
When running project analysis from the command line, the same settings are used as in the case when it is run from the IDE (Visual Studio). The number of processor cores to be used for analysis depends on the number specified in the analyzer settings.
As for the filtering systems (Keyword Message Filtering and Detectable Errors), they CANNOT be used when running the analysis from the command line. It means you'll see all the messages in the log file anyway, regardless of the parameters you have specified. However, when loading the log file in the IDE, the filters will be applied. This is due to the fact that filters are applied dynamically to the results (including the case when you analyze your project from the IDE as well). It's very convenient since you may want to switch off some of the messages you've got (for example V201). You only need to disable them in the settings to have the corresponding messages disappear from the list WITHOUT you having to rescan the project.
The plog file format (XML) is not intended for directly displaying to or read by a human. However, if you need to filter off the analysis results and convert them into a "readable" format, you can use the PlogConverter utility available within the PVS-Studio distribution.
PlogConverter allows you to convert the plog file into the following formats:
- Light-weight text file with analysis results. It can be useful when you need to output the analysis results (for example new messages) into the log of the build system or continuous integration server.
- HTML file with hyperlinks to the source files. A file in this format is convenient to send via e-mail to all the developers involved.
- CSV table with analysis results.
- Text file with a summary table of the number of messages across different levels and diagnostic rule sets.
The format of the log file is defined by the command line parameters. You can also use them to filter the results by rule sets, levels, and individual error codes.
Here's an example of the plog converter command line launch (in one line):
PlogConverter.exe -p test.plog -o "C:\Results" -r "C:\Test" -a GA:1,2,3;64:1 -t Html,Txt,Totals -d V101,V105,V122
The plog converter will be launched for the test.plog file in the current folder and the results will be saved into the Results folder on disk C; only messages from the General Analysis (GA) rule set of levels 1, 2, and 3, and from the 64-bit diagnostic rule set (64) of level 1 will be used. Diagnostics V101, V105, and V122 will be filtered off from the list. The results will be saved into a text and HTML files as well as a summary text file for all the diagnostics (with the mentioned parameters taken into account). The original plog file will remain unchanged.
A detailed help on all the parameters of the PlogConverter utility can be accessed by executing the following command:
If you need to convert the plog file into some specific format, you can do it by parsing the file as an XML document yourself. Notice that the PlogConverter utility comes with the source files (in C#) which can be found in the PlogConverter_src.zip archive. You can alter the parsing algorithm of plog file structure from our utility to create an analysis results output format of your own.
The process of long-term use of the PVS-Studio code analyzer is comprised of two stages: integration and regular use. When integrating PVS-Studio into an existing large-scale project, programmers will usually read the analyzer messages and either fix the code or mark it using the "Mark as False Alarm" and "Message Suppression" features. Having sorted out all the messages, they will then re-analyze the code once again to get 0 warnings (given that the messages marked as false positives or suppressed through suppress files are set to stay hidden). It means that the integration stage is over and the stage of regular use sets in.
From this point on, all the new code added into the project will be analyzed by PVS-Studio. Actually, the ENTIRE code base will be analyzed, but you'll be seeing only new messages. Errors will be found in freshly written/fixed code or old code that has been left unmarked.
The option of running the analysis from the command line is useful when developers need to launch it regularly (daily, for instance). The procedure looks as follows:
- Running the analysis from the command line.
- Sending the resulting log file to all the developers involved.
This way, regularly running PVS-Studio on your project will help you avoid new bugs in the code.
To install the PVS-Studio distribution from the command line in a "quiet" mode (i.e. without displaying the UI and dialog boxes), you need to pass the following parameters into it (in one line):
PVS-Studio_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /COMPONENTS=Core,Standalone,MSVS,MSVS\2005,MSVS\2008,MSVS\2010, MSVS\2012,MSVS\2013
The /COMPONENTS argument allows specifying the components to be installed (Standalone utility, plugins for different IDEs) and is optional.
Keep in mind that it is required to avoid running Visual Studio (the devenv.exe process) while installing PVS-Studio.
The PVS-Studio-Updater.exe utility can check for analyzer updates and download and install them on a local machine. To run the update utility in the "quiet" mode, you can use the same parameters as for the distribution installation process:
PVS-Studio-Updater.exe /VERYSILENT /SUPPRESSMSGBOXES
If there are no updates available on the server, the utility will terminate with '0' exit code. Since PVS-Studio-Updater.exe performs local installation, you must avoid running the devenv.exe process while it is working as well.
Running PVS-Studio daily from the command line can help you significantly increase the quality of your code. Sticking with this approach, you will get 0 diagnostic messages every day if your code is correct. And should there be any incorrect edits of the old (already scanned and fixed) code, the next run of PVS-Studio will reveal any fresh defects. Newly written code will be regularly scanned in automatic mode (i.e. independently of the programmer).