Instructions for running ScanVSSolutionForPurifyPlus.pl

IBM® Rational® PurifyPlus™ for Windows works best with programs that are built with certain compiler and linker settings. If you run into problems using PurifyPlus one of the first steps you should take is to determine if you are using the right settings. If you aren't you should correct these settings and then rebuild your program. This script was written to assist you in performing these steps for programs built with Visual Studio .NET, Visual Studio .NET 2003, Visual Studio 2005 and Visual Studio 2008. There is a separate script for programs built with Visual Studio 6.

For more information on the recommended settings please refer to the product's online help, which is available from the product's Help menu. Once the online help is opened, you should view the "Recommended Settings for Visual Studio" topic.

This script can be used to report settings that need to be changed. You can then make these changes yourself via the Visual Studio IDE, or you can optionally tell the script to change those settings and write them to your project files.

Installation

This is a Perl script, and to use it you have to have Perl installed on your system. This was developed and tested with version 5.8.6, and should work with this version or newer. IBM does not provide Perl for this script. Perl is available for free on the Internet.

Syntax

You run this script from a MS-DOS command prompt window. This script uses some MS-DOS commands so it may not work in command prompt windows that install other shells.

Defaults are provided for all values except for either the solution file or project file. It is required to enter one of these.

Here is the syntax.

v1.05 Usage:
perl ScanVSSolutionForPurifyPlus.pl [<options>]
Options:
 -sln=<solution-file> ==> specify the solution file to check or modify.
                          You must specify a solution file or a project file.
 -proj=<project-file> ==> specify the project file to check or modify
 -config=<ConfigurationName | all>
       config=ConfigurationName  ===> only scan the specified configuration
       config=all (default) ==> scan all configurations
 -report=<output file> Specify the output file
       (default)=output to console
 -write=<yes> Modify settings and write.
        It is recommended that you backup the projects before modifying.
        write=yes ==> modify settings and write project file(s) after
                      saving current project file(s) to .backup.
        write=no (default)==> report incorrect settings only,
                              don't modify anything.
e.g. perl ScanVSSolutionForPurifyPlus.pl -sln="C:\My Apps\MyCode.sln" -report=scan.log -write=yes
or   perl ScanVSSolutionForPurifyPlus.pl -proj=C:\MyApps\Myproj.vcproj -report=scan.log -write=yes

How it works

This script reads (and optionally writes) the files created by Visual Studio where the solution and project settings are stored. Visual Studio saves solution data in a .sln file, and project data in differently named files, depending on the project type. This script works by reading these files and comparing different values with the values we expect when the setting is set to the recommended value.

You can check an entire solution, or focus on a project or configuration or a combination of the two. For example:

Check an entire solution, all projects and all configurations:
perl ScanVSSolutionForPurifyPlus.pl -sln=C:\MyApps\MyCode.sln 

Check just one project, all configurations:
perl ScanVSSolutionForPurifyPlus.pl -proj=C:\MyApps\MyCode.vcproj 

Check just one project and one configuration for that project:
perl ScanVSSolutionForPurifyPlus.pl -proj=C:\MyApps\MyProject.vcproj -config=Debug
The script tries to limit it's checks to configurations that we target. Thus the script checks only those configurations that are targeted for the Win32 platform. It also doesn't check unknown project types. The output will list all the projects and configurations that are found, and report what isn't being checked as well as what is being checked.

The script generates a report that lists the files that it checked and the values that weren't set to the recommended values and what the recommended values should be. You can go and manually change these settings in the Visual Studio IDE and run the script again after saving these changes to verify you've made the changes correctly.

If you desire, you can optionally have the script automatically correct the settings and write the files to disk. Follow these instructions before doing this, for safety's sake:

***** IMPORTANT NOTES *****

  1. The most important thing to do before using this script to write anything is to BACKUP your solution and projects so you can restore them. We have made every effort to ensure that we don't write to anything but the project files (and a report file if specified) and we create backups of these project files before writing them, but you should have an untouched set of files to restore in case of some unforseen problem.
  2. Close any open Visual Studio solutions or projects you'll be modifying. You'll need to reload them from scratch after modification.
If used in the 'write=yes' mode, the script generates a report of the incorrect settings that were identified and it lists the files that were changed. Each project file is first copied to a .backup file and then the changed settings are written to . You can compare the and .backup files to see exactly what changes the script made to your projects. After the files are written, you can open the solution in Visual Studio and you'll see the new settings. You should then ensure that you can rebuild your solution with these changed settings. If that's a success, you should re-run under Purify, Quantify or PureCoverage after clearing the cache so all files get re-instrumented.

Note that if you rerun the script telling it to write again, we won't create new .backup files. If an .backup file already exists we'll leave it in place so you can always easily get back to your original project contents if desired.