| Debugging Tools for Windows |
Generally, binaries are source-indexed during the build process after the application has been built. The information needed by SrcSrv is stored in the .pdb files. SrcSrv currently supports the following source control systems:
Perforce
Microsoft Visual SourceSafe
Microsoft Team Foundation Server
You can also create a custom script to index your code for a different source control system. One such module for Subversion is included in this package. Anyone interested in using SrcSrv with CVS should send e-mail to windbgfb@microsoft.com.
SrcSrv includes five tools that are used in the source indexing process: the Srcsrv.ini file, the SSIndex (Ssindex.cmd) script, the SrcTool (Srctool.exe) tool, the PDBStr (Pdbstr.exe) tool, and the VSSDump (Vssdump.exe) tool. They are installed with Debugging Tools for Windows in the subdirectory srcsrv, and should remain installed in the same path as SrcSrv. The PERL scripts in these tools require PERL 5.6 or later.
The Srcsrv.ini file is the master list of all source control servers. Each entry has the following format:
When using Perforce, the ServerInfo consists of the full network path to the server, followed by a colon, followed by the port number it uses. For example:
Srcsrv.ini is a required file when you are actually source indexing a build using the modules shipped with this package. This entry creates an alias that is used to describe the server info. The value should be unique for every server that you support.
This file can also be installed on the computer running the debugger. When SrcSrv starts, it looks at Srcsrv.ini for values; these values override the information contained in the .pdb file. This enables users to configure a debugger to use an alternative source control server at debug time. However, if you manage your servers well and do not rename them, there should be no need to include this file with your client debugger installations.
This file also serves other purposes on the client side. For more information, see the sample Srcsrv.ini file installed with SrcSrv tools.
The SSIndex (SSindex.cmd) script builds the list of files checked into source control along with the version information of each file. It stores a subset of this information in the .pdb files generated when you built the application. SSIndex uses one of the following Perl modules to interface with source control:
p4.pm (Perforce)
vss.pm (Visual SourceSafe)
tfs.pm (Team Foundation Servers)
svn.pm (Subversion)
For more information, run SSIndex with the -? or -?? (verbose help) option or examine the script.
The SrcTool (Srctool.exe) utility lists all files indexed within the .pdb file. For each file, it lists the full path, source control server, and version number of the file. You can use this information for reference.
You can also use SrcTool to list the raw source file information from the .pdb file. To do this, use the –s switch on the command line.
SrcTool has other options as well. Use the ? switch to see them. Of most interest is that this utility can be used to extract all of the source files from version control. This is done with the -x switch.
Note: Previous versions of this program created a directory called src below the current directory when extracting files. This is no longer the case. If you want the src directory used, you must create it yourself and run the command from that directory.
The PDBStr (Pdbstr.exe) tool is used by the indexing scripts to insert the version control information into the “srcsrv” alternative stream of the target .pdb file. It can also read any stream from a .pdb file. You can use this information to verify that the indexing scripts are working properly.
For more information, run PDBStr with the -? option.
The VSSDump (Vssdump.exe) tool is used by the indexing script for Microsoft Visual SourceSafe. It gathers the list of source files to be indexed. This program is also a valuable command-line utility that you can use to examine which files may be processed by the indexing script.
To prepare for source indexing, edit Srcsrv.ini so that it contains an entry for your version control server. This is an operation that you must do only once. Details are listed in the sample version Srcsrv.ini. You can use an environment variable or switch to the indexing script to denote the location of this file. However, it is best to put it in the same directory as the script because the contents of this file are intended to be global across all projects in your business or development system. This file serves to uniquely identify different version control servers. Note that you can provide a different version of this file to debuggers so that they look at a replicated copy of the version control server, which can be useful if you want to reduce traffic on the server.
To source-index a particular build, make certain that no source files are checked out on the build computer. If any files are checked out and edited, those changes are not reflected in the final source indexed .pdb files. Furthermore, if your build process includes a pre-compilation pass that generates source files from other files, you must check in those generated files to version control as part of the pre-compilation.
Upon completion of the build, set the current working directory to be the root of all source files and generated .pdb files. Then run SSIndex. You must specify what version control system you are using as a parameter. For example:
SSIndex accepts parameters that allow you to run the script from anywhere and to specify the location of the source files and .pdb files separately. This is most useful if the source is kept in another location from the output .pdb files. For example:
These directories can also be specified with environment variables. Use the
Here is an example of the output generated by this script:
--------------------------------------------------------------------------------
SSIndex.cmd [/option=<value> [...]] [ModuleOptions] [/Debug]
General SrcSrv settings:
NAME SWITCH ENV. VAR Default
-----------------------------------------------------------------------------
1) srcsrv.ini Ini SRCSRV_INI .\srcsrv.ini
2) Source root Source SRCSRV_SOURCE .
3) Symbols root Symbols SRCSRV_SYMBOLS .
4) Control system System SRCSRV_SYSTEM <N/A>
5) Save File (opt.) Save SRCSRV_SAVE <N/A>
6) Load File (opt.) Load SRCSRV_LOAD <N/A>
Visual Source Safe specific settings:
NAME SWITCH ENV. VAR Default
-----------------------------------------------------------------------------
A) VSS Server Server SSDIR <N/A>
B) VSS Client Client SSROOT <Current directory>
C) VSS Project Project SSPROJECT <N/A>
D) VSS Label Label SSLABEL <N/A>
Precedence is: Default, environment, cmdline switch. (ie. env overrides default,
switch overrides env).
Using '/debug' will turn on verbose output.
Use "SSIndex.cmd -??" for verbose help information.
See SrcSrv documentation for more information.
--------------------------------------------------------------------------------
You can also use one of the provided wrapper scripts (Vssindex.cmd) to avoid specifying the version control system. The script source-indexes all .pdb files found in the current directory and below with version control information to locate all source files found in the current directory and below. You can specify different locations for these files by using environment variables and command-line switches.
Upon completion of the source indexing, you can test the output by running SrcTool on the .pdb files. This program displays data that indicates whether or not the .pdb file is source indexed. It also displays the specific information for every source file. Lastly, it displays the number of indexed sources and the number of sources that no indexing information was found for. It sets an %ERRORLEVEL% of -1 if the file is not source-indexed. Otherwise, it sets %ERRORLEVEL% to the number of indexed source files.
VSSDump can also be used independently to diagnose issues while source-indexing. The syntax is as follows:
Options can be any combination of the following options.