Microsoft Source Server

Table Of Contents
Microsoft Source Server......................................................................................................................................................1

Table Of Contents................................................................................................................................................................. 1

General Concepts and Usage................................................................................................................................................3

Usage and Source Indexing...............................................................................................................................................3

Using Source Server with a Debugger................................................................................................................................3

Retrieving the Source File..................................................................................................................................................3

Source Indexing................................................................................................................................................................. 3

Creating a Source Control Provider Module......................................................................................................................7

Language Specification Version 1..........................................................................................................................................9

Source Server Data Blocks.................................................................................................................................................9

How Source Server Works................................................................................................................................................11

Handling Server Errors.....................................................................................................................................................13

API and Usage................................................................................................................................................................. 13

Language Specification Version 2........................................................................................................................................14

SRCSRVCMD.................................................................................................................................................................... 14

Notes on Visual SourceSafe.................................................................................................................................................14

The Database.................................................................................................................................................................. 14

Current Project................................................................................................................................................................ 14

Working Folder................................................................................................................................................................14

Labels.............................................................................................................................................................................. 14

Credentials...................................................................................................................................................................... 15

Platform.......................................................................................................................................................................... 15

Debugging....................................................................................................................................................................... 15
 VSSDump......................................................................................................................................................................... 15

Notes on CVS (Concurrent Versions System)......................................................................................................................16

Disclaimer........................................................................................................................................................................ 16

CVSROOT......................................................................................................................................................................... 16

Client Computer...............................................................................................................................................................16

Revision Tags................................................................................................................................................................... 16

Notes on Team Foundation Server......................................................................................................................................17

HTTP Sites and UNC Shares.................................................................................................................................................17

Set up the web site..........................................................................................................................................................17

Extract and locate the source files...................................................................................................................................17

Modify the pdb source indexing streams.........................................................................................................................18

UNC Shares...................................................................................................................................................................... 18

Supporting HTTP/UNC along with regular version control with the same pdb...............................................................19
General Concepts and Usage
Usage and Source Indexing
The source server enables a client to retrieve the exact version of the source files that were used to build an application.
Because the source code for a module can change between versions and over the course of years, it is important to look
at the source code as it existed when the version of the module in question was built.

The source server retrieves the appropriate files from source control. To use the source server, the application must
have been source indexed.

Using Source Server with a Debugger

To use the source server with WinDbg, KD, NTSD, or CDB, ensure that you have installed a recent version of the
Debugging Tools for Windows package (version 6.3 or later). Then, include srv* in the .srcpath command as follows:

.srcpath srv*;c:\mysource

Note that this example also includes a traditional source path. If the debugger cannot retrieve the file from the source
server, it will search the specified path.

If a source file is retrieved by the source server, it will remain on your hard drive after the debugging session is over.
Source files are stored locally in the src subdirectory of the Debugging Tools for Windows installation directory.

If you experience any trouble extracting the source files from the debugger, start the debugger with the –n command
line parameter to view the actual source extraction commands along with the output of those commands. !sym noisy
will do the same thing, but you may have already missed important information from previous extraction attempts. This
is because the debugger will give up trying to access source from version control repositories that appear to be
unreachable.

Retrieving the Source File

To facilitate the use of Source Server from tools other than the debuggers listed above, the DbgHelp API provides access
to source server functionality through the SymGetSourceFile function. To retrieve the name of the source file to be
retrieved, call the SymEnumSourceFiles or SymGetLineFromAddr64 function.

Source Indexing
The source indexing system is a collection of executable files and Perl scripts. The Perl scripts require Perl 5.6 or greater
(not included). They are installed with the debugger package in a subdirectory sdk\srcsrv. To work with these tools, they
should all be installed in the path.
Generally, binaries are source indexed during the build process after the application has been built. The information
needed by Source Server is stored in the PDB files. Source Server currently supports the following source-control
systems…

Perforce
Microsoft Visual SourceSafe
Microsoft Team Foundation Server
CVS (Concurrent Versions System)

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.

While every attempt has been made to make these above-mentioned modules as bulletproof and robust as possible, the
simple fact is, there is no way to account for all of the variance found in version control enlistments found throughout
the world. It is quite possible that you will not see success on the first attempt to use these tools and it is also possible
that you will have to do a little debugging and even a little Perl coding to customize the scripts to your needs. Here are a
couple of hints.

Get familiar with srctool.exe and all of its command line options. It is a valuable tool to see what is going on.

If it comes down to Perl debugging and programming, focus on the module that corresponds with your specific version
control system. These files end with an extension of .pm. It is somewhat unlikely that your problem is in the master
script, (ssindex.cmd).

Feel free to ask questions on our newsgroup, microsoft.public.windbg.

The following table lists the Source Server tools.

Tool Description

SrcSrv.ini This file is the master list of all source control servers. Each entry has the following format:

MYSERVER=serverinfo

When using Perforce, the server info consists of the full network path to the server, followed
by a colon, followed by the port number it uses. For example:

MYSERVER=machine.corp.company.com:1666

Srcsrv.ini is a required file when actually source indexing a build using the modules shipped
with this package. This entry creates an alias that will be used to describe the server info. The
value should be unique for every server you support.

This file can also be installed on the computer running the debugger. When Source Server
starts, it looks at srcsrv.ini for values; these values will override the information contained in
the PDB file. This enables users to configure a debugger to use an alternate source control
server at debug time. However if you manage your servers well and don’t 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 installed with the Source Server tools.

SSIndex.cmd This 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. The script uses one of the following Perl modules to interface with source
control…

p4.pm (Perforce)
vss.pm (Visual SourceSafe)
tfs.pm (Team Foundation Server)
cvs.pm (Concurrent Versions System)
svn.pm (Subversion)

For more information, run the script with the “-?” or “-??” (verbose help) option or examine
the script.

SrcTool.exe This 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.exe to list the raw source file information from the pdb. To do this,
use the “-s” switch on the command line.

SrcTool.exe has other options as well. Use the “-?” switch to see them. Of most interest, is
that srctool.exe can get used to actually extract all of the source files from version control. This
is done with the “-x” switch.

Note: Previous versions of this program used to create a directory called “src” below the
current one, when extracting files. This is no longer the case. If you want this directory used,
you need to create it yourself and run out of there.

PdbStr.exe This utility is used by the indexing scripts to insert the version control information into the
“srcsrv” alternate 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 the utility with the “-?” option.

VSSDump.exe This utility is used by the indexing script for 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 will do only once. Details are listed in the sample version of this file. 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. This 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, then those changes will not be 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, then you need to check
those generated files into 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 and generated PDB files.
Then run the indexing script ssindex.cmd. You will need to specify what version control system you are using as a
parameter. For example:

ssindex.cmd –server=vss

Ssindex.cmd accepts parameters that allow you to run the script from anywhere and to specify the location of the
source files and pdb separately. This is most useful if the source is kept in another location from the output pdb files.
Example:

ssindex.cmd –server=vss –source=c:\source –symbols=c:\outputdir

These directories can also be specified with environment variables. Use the -? or -?? command line options for more
information...

C:\ >ssindex.cmd -system=vss -?

--------------------------------------------------------------------------------
SSIndex.cmd [/option=<value> [...]] [ModuleOptions] [/Debug]

General source server 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 the Source Server 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 will source index 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.exe on the PDB files. This program
will display whether the PDB is source indexed or not. It will also display 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.

Creating a Source Control Provider Module

The source server includes provider modules for Perforce (p4.pm) and Visual Source Safe (vss.pm). It is possible to
generate your own modules to support other version control systems. Included in this package is svn.pm, which was
written by Shahar Talmi of Safeend, Ltd. This shows how you can modify one of the existing scripts to support the
Subversion Version Control system.

To create your own provider module, you must implement the following set of interfaces.

$module::SimpleUsage()

Purpose: Displays simple module usage information to STDOUT.

Parameters: None

Return value: None

$module::VerboseUsage()

Purpose: Displays in-depth module usage information to STDOUT.

Parameters: None

Return value: None

$objref = $module::new(@CommandArguments)

Purpose: Initializes an instance of the provider module.

Parameters: All @ARGV arguments that weren’t recognized by ssIndex.cmd as being general arguments.

Return value: A reference that can be used in later operations.

$objref->GatherFileInformation($SourcePath, $ServerHashReference)
 Purpose: Enables the module to gather the required source indexing information for the directory specified by
the $SourcePath parameter. The module should not assume that this entry will be called only once for each
object instance, as ssIndex.cmd may call it multiple times for different paths.

Parameters: (1) The local directory containing the source to be indexed. (2) A reference to a hash containing
all of the entries from the specified srcsrv.ini file.

Return value: None

($VariableHashReference, $FileEntry) = $objref->GetFileInfo($LocalFile)

Purpose: Provides the necessary information to extract a single, specific file from the source control system.

Parameters: A fully-qualified file name

Return value: (1) A hash reference of the variables necessary to interpret the returned $FileEntry.
SSIndex.cmd caches these variables for every source file used by a single debug file to reduce the amount of
information written to the source index stream. (2) The file entry to be written to the source index stream to
allow SrcSrv.dll to extract this file from source control. The exact format of this line is specific to the source
control system.

$TextString = $objref->LongName()

Purpose: Provides a descriptive string to identify the source control provider to the end user.

Parameters: None

Return value: The descriptive name of the source control system.

@StreamVariableLines = $objref->SourceStreamVariables()

Purpose: Enables the source control provider to add source control specific variables to the source stream for
each debug file. The sample modules use this method for writing the required EXTRACT_CMD and
EXTRACT_TARGET variables.

Parameters: None

Return value: The list of entries for the source stream variables.
Language Specification Version 1
Source Server Data Blocks
Source server relies on two blocks of data within the PDB file.

 Source file list. Building a module automatically creates a list of fully-qualified paths to the source files used to
build the module.

 Data block. Indexing the source as described previously adds an alternate stream to the PDB file named
“srcsrv”. The script that inserts this data is dependent on the specific build process and source control system in
use.

The data block is divided into three sections: ini, variables, and source files. It has the following syntax.

SRCSRV: ini ------------------------------------------------

VERSION=1
VERCTRL=<source_control_str>
DATETIME=<date_time_str>
SRCSRV: variables ------------------------------------------
SRCSRVTRG=%sdtrg%
SRCSRVCMD=%sdcmd%
SRCSRVENV=var1=string1\bvar2=string2
DEPOT=//depot
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
WIN_SDKTOOLS= sserver.microsoft.com:4444
SRCSRV: source files ---------------------------------------
<path1>*<var2>*<var3>*<var4>
<path2>*<var2>*<var3>*<var4>
<path3>*<var2>*<var3>*<var4>
<path4>*<var2>*<var3>*<var4>
SRCSRV: end ------------------------------------------------

All text is interpreted literally, except for text enclosed in percent signs (%). Text enclosed in percent signs is treated as a
variable name to be resolved recursively, unless it is one of the following functions:

%fnvar%()

The parameter text should be enclosed in percent signs and treated as a variable to be expanded.

%fnbksl%()

All forward slashes (/) in the parameter text should be replaced with backward slashes (\).

%fnfile%()

All path information in the parameter text should be stripped out, leaving only the file name.

The ini section contains variables that describe the requirements. The indexing script can add any number of variables to
this section. The following are examples:
VERSION

The language specification version. This variable is required. Someone developing a script based on this
language specification should set this value to 1. The Source Server client code will not attempt to execute any
script that has a value greater than it. Current versions of srcsrv.dll use the value of 2.

VERCTL

A string that describes the source control product. This variable is optional.

DATETIME

A string that indicates the date and time the PDB file was processed. This variable is optional.

The variables section contains variables that describe how to extract a file from source control. It can also be
used to define commonly used text as variables to reduce the size of the data block.

SRCSRVTRG

Describes how to build the target path for the extracted file. This is a required variable.

SRCSRVCMD

Describes how to build the command to extract the file from source control. This includes the name of the
executable file and its command-line parameters. This is required if any extraction command needs to be
executed.

SRCSRVENV

A string that lists environment variables to be created during the file extraction. Separate multiple entries with
a backspace character (\b). This is an optional variable.

SRCSRVVERCTRL

Specifies the version control system in use. For Perforce, this is “perforce”. For Visual SourceSafe, this is “vss”.
For Team Foundation Server, this is “tfs”. This variable is used to persist server errors. This is an optional
variable.

SRCSRVERRDESC

This is a text snippet that matches what is emitted by the version control client when it is unable to contact the
server that contains the source files to extract. Source Server uses this value to check for connection
problems. This is an optional variable.

SRCSRVERRVAR

This indicates which variable in a file entry corresponds to a version control server. It is used by Source Server
to identify commands that won’t work, based on previous failures. The format of the text is “varX” where X is
the number of the variable being indicated. This is an optional variable.
The source files section contains an entry for each source file that has been indexed. The contents of each line are
interpreted as variables with the names VAR1, VAR2, VAR3, and so on until VAR10. The variables are separated by
asterisks. VAR1 must specify the fully-qualified path to the source file as listed elsewhere in the PDB file. For example,
the following line:

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

is interpreted as follows:

VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3

In this example, VAR4 is a revision number. However, most source control systems support labeling files in such a way
that the source state for a given build can be restored. Therefore, you could alternately use the label for the build. The
sample data block could be modified to contain a variable such as the following:

LABEL=BUILD47

Then, presuming the source control system uses the at sign (@) to indicate a label, you could modify the SRCSRVCMD
variable as follows:

sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%

How Source Server Works

The source server client is implemented in symsrv.dll. The client does not extract information directly from the PDB file;
it uses a symbol handler such as the one implemented in dbghelp.dll. It is essentially a recursive variable substitution
engine that creates a command line that can be used to extract the proper source file from the source control system.
Your code should not call Symsrv.dll directly. To integrate its functionality into your application, use the
SymGetSourceFile function.

The first version of source server works as follows. (This behavior may change in future versions.)

First, the client calls SrcSrvInit with the target path to be used as a base for all source file extractions. This path is stored
in the special variable TARG.

When dbghelp loads a module’s PDB file, it extracts the SrcSrv stream from the PDB and passes this data block to SrcSrv
by calling SrcSrvLoadModule.

Then when dbghelp needs to grab a source file, it calls SrcSrvGetFile to retrieve a specified source file from version
control.

Srcsrv looks through all the source file entries in the data block for an entry that matches exactly the requested source
spec. This match is to be found in VAR1.

Once srcsrv finds the entry, it fills in the special variables (VAR1, VAR2, etc.) with the contents of this source file entry.
Now the SRCSRVTRG variable is resolved using these special variables. Beginning with the source line used in the
previous example, the following shows how these variables are resolved. Each line shows the resolution of one more
special variable. The resolved variables are shown in red.

SRCSRVTRG=%sdtrg%

SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\%fnbksl%(sdktools/debuggers/srcsrv/shell.cpp)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(c:\db\srcsrv\shell.cpp)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp

Notice how this generated target path is unique and will not allow two versions of the same file to be extracted to the
same location.

Srcsrv now looks to see if the file is already there. If it is, srcsrv returns the location to the caller. Otherwise, srcsrv
builds the execution command to extract the file by resolving SRCSRVCMD.

In the following example, each line shows the resolution of one more special variable. The resolved variables are shown
in red.

DEPOT=//depot

WIN_SDKTOOLS= sserver.microsoft.com:4444

SRCSRVCMD=%sdcmd%

SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444 print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\

shell.cpp\3\shell.cpp -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\

shell.cpp\3\shell.cpp -q //depot/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\

shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#%var4%

sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\

shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#3
Now srcsrv executes this command line. If the result of this command line is a file in the expected location, then this
path is returned to the caller.

Note that if a variable cannot be resolved, an attempt is made to look it up as an OS environment variable. If that fails,
the variable name is deleted from the text being processed.

Two consecutive percent sign characters are interpreted as a single percent sign.

Handling Server Errors

Sometimes a client will be unable to extract any files at all from a single version control server. This can be because the
server is down and off the network or because the user does not have appropriate privileges to access the source.
However the time consumed attempting to get this source can slow things down significantly. In this situation, it is
desirable to disable any attempt to extract from a source that has been proven to be unavailable.

Whenever Source Server fails to extract a file, it examines the output text produced by the command. If any part of this
command contains an exact match for the contents of the SRCSRVERRDESC, then all future commands to the same
version control server will be skipped. Note that you can define multiple error strings by adding numbers or arbitrary
text to the end of the SRCSRVERRDESC variable name. Examples:

SRCSRVERRDESC=foo: server not found

SRCSRVERRDESC_2=bar: network error

The identity of the server is acquired from SRCSRVERRVAR. So if SRCSRVERRVAR contains “var2” and the file entry in the
pdb looks like this…

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

Then all future attempts to grab source using a file entry that contains “TOOLS_PRJ” in variable 2 will be bypassed.

You can also add error indicators on the debugger client by editing srcsrv.ini. Instructions are provided in the sample file
provided.

API and Usage

This document allows you to understand how to prepare instrumentation scripts so that this source server technology
can be integrated into your build or version control system.

This document exposes many of the specifics of how srcsrv.dll is called by symbol handler code. However this
information is not static and will not become so in the future. No one should attempt to write code that calls srcsrv.dll
directly. This is reserved for dbghelp.dll or the Visual Studio products. Third party vendors wishing to integrate such
functionality in their products should use the SymGetSourceFile function. This function, along with others in the
DbgHelp API, is described in the dbghelp.chm documentation.
Language Specification Version 2
SRCSRVCMD
This package ships with a srcsrv.dll that is able to operate without SRCSRVCMD being defined in the srcsrv data stream
of a PDB. While such capability is of no use for normal file extraction from source control systems, it is useful for direct
access of files from a UNC share or HTTP site. Such usage is described later in this document.

Notes on Visual SourceSafe

The Database
The default Visual SourceSafe database can be set with the SSDIR environment variable. If it is not set there, the Source
Server indexing script can usually determine this from the registry. If it can’t, the script will prompt you to set SSDIR.
Regardless, this database value must be listed in your srcsrv.ini file along with a simple alias to identify the database.
More instructions can be found in the comments in srcsrv.ini. You should add the entry in the [variables] section of the
file as so…

MYDATABASE=\\server\VssShare

Current Project
Visual SourceSafe works with the concept of a “current project”. The Source Server indexing script respects this value
and limits itself to process only source files that are part of the current project. You can see what the current project is
with the “ss.exe project” command. If you want to change the current project, you can do so with the “ss.exe cp”
command. For example, if you want all projects to be processed you would do so by setting the current project to the
root, as so…

ss.exe cp $/

Working Folder
Visual SourceSafe projects are associated with “working folders”. A working folder is the location on the client computer
which corresponds to the root of a project. However it is possible for such a computer to obtain and build source
without a working folder being specified, normally through “ss.exe get –R” or when creating projects through the Visual
Studio interface. This mode of operation is incompatible with Source Server indexing. Source Server requires that a
working folder be specified. If you have not set a working folder, you can do so with the following command…

ss.exe workfold <project> <folder>

Labels
Visual SourceSafe is not able to determine what version of a file exists within the working directory of a build machine.
Consequently, you must use labels to stamp the project with an identifier that will be used to extract source files on the
debugger client. So before indexing, you need to make sure that all changes are checked into the database and then
apply a label to it with the “ss.exe label” command. In the following example, the label “VERSION_3” is applied to a
project called “$/sdktools”…
 E:\nt\user>ss.exe label $/sdktools
Label for $/sdktools: VERSION_3
Comment for $/sdktools:
This is a comment.

After the label is applied, you can specify this label to the Source Server indexing script by setting the environment
variable, SSLABEL, or by passing it as a command line parameter…

vssindex.cmd –label=VERSION_3

Again, this label is required for Source Server indexing to work. Note that if you pass a label that doesn’t exist in the
project, it might take a long time for the script to complete and the results will be of no use.

Credentials
If your Visual SourceSafe database requires a user and optional password in order to access it, then these values must be
set through the SSUSER and SSPWD environment variables. This applies not only at the time the build is indexed, but
also on the debugger client.

Platform
Visual SourceSafe is an X86 application and the source indexing scripts and tools for it are installed only with the X86
package of Debugging Tools for Windows.

Debugging
As described previously, SSUSER and SSPWD may need to be set in your debugging environment. Furthermore, please
note that the version of srcsrv.dll that ships with Visual Studio 2005 is not able to detect if Visual SourceSafe (ss.exe) is
prompting for credentials. This will result in a hang in the application. You can upgrade with the srcsrv.dll that ships
with “Debugging Tools for Windows” to prevent this. Regardless, the credentials must be set for source extraction to
work, if your Visual SourceSafe database requires them.

If Visual SourceSafe is not set in the path of your debugging computer, you can get around this by adding an entry to the
srcsrv.ini file that works with your debugger. When using a standard installation of Visual Studio, this file should be
located in the following location…

%PROGRAMFILES%\Microsoft Visual Studio 8\Common7\IDE\srcsrv.ini

In the [trusted commands] section described previously, add an entry like the following, making sure that the path
points to the correct location of ss.exe.

ss.exe=”C:\Program Files\Microsoft Visual SourceSafe\ss.exe”

VSSDump
VSSDump.exe is a program that is used by the indexing scripts to locate and resolve source files to the database. You
can also use this program standalone so as to diagnose issues when source indexing. Calling the program with “-?” will
list the command line parameters…

vssdump: enumerates files in the current VSS project.

-a ignores the current project and lists all projects.
 -p:<projectname> specifies a VSS project to use.
not to be used -with '-a'
-d:<directory> specifies a root directory
otherwise the current directory is used.
-l:<label> specifies a version label
-t don't test version to match a passed label
-v:<sharepath> specifies location of the VSS database - overrides SSDIR
-r recurse subdirectories
-f don't list files - just directories
-i ignore current directory and list entire project
not to be used with '-r'
-s format output for scripting
-c display only the VSS configuration info

Notes on CVS (Concurrent Versions System)

Disclaimer
The cvs module for Source Server was developed using Concurrent Versions System (CVS) 1.11.17 (client). It has not
been tested with any other versions of cvs. Furthermore it has not been tested extensively. We have noticed that the
great variance in user installations has exposed a lot of opportunities for the scripts to fail. So anyone using this script
should consider that there is a chance he or she will have to do a little Perl debugging of the scripts to make they work
out. Those finding they need to do this should please let us know by posting to the microsoft.public.windbg newsgroup
so that we can help you and enhance the scripts.

CVSROOT
On the machine that you source index the build, CVSROOT cannot contain password and user information. You should
use cvs.exe to set your credentialing information.

To prepare srcsrv.ini for cvs indexing you need to enter an alias for your repository that will uniquely identify it from any
others in your network. This repository needs to match the value of CVSROOT in your environment. There is no need to
set this value in the srcsrv.ini that you keep with your debugger clients since the alias will be defined in the source
indexed pdb.

Client Computer
The client computer that will be extracting files during debugging does not need a cvs sandbox or CVSROOT set. It does
need cvs binaries in the path and if the repository is locked, you will need to set the username and password with
cvs.exe.

Revision Tags
Cvs is unable to extract a file by its version number. Instead it must be done using what is known as a “tag”. So when
indexing a cvs-based system you need to make sure that all changes are checked into the repository and then apply a tag
with the “cvs tag” command. Then when indexing the file, make certain you use the “label” command line parameter to
specify the tag that you want to associate with the build you are indexing. You can achieve the same result by setting
CVS_LABEL in the environment. Other values can be set from the environment or the command line. Don’t forget to
use the -? command line parameter to examine your choices and to make sure that all was configured correctly.
 ssindex.cmd –system=cvs -??

Notes on Team Foundation Server

The script provided for processing using TFS is incapable of working with labels that have spaces in them. Code as been
added to the script to handle spaces in the labels, however it is commented out for stability. If you wish to source index
with TFS using labels and you want to allow spaces in the labels, please examine the code at line 453 of tfs.pm.

HTTP Sites and UNC Shares

It is possible to set up a web site that provides version-specific source to the windbg.exe debugger through the srcsrv
module. Such a mechanism does not provide dynamic extraction of the source files from version control; however it is a
valuable feature because it allows you to set the source path of windbg.exe to a single unified path that will provide
source from many versions of many modules, instead of having to set separate paths for each debugging scenario. This
is not of interest to debugging clients that have direct access to the actual version control systems, but can be of
assistance to those wanting to provide secure http-based access to source from remote locations. The web sites in
question can be secured through HTTPS and smartcards, if desired. This same technique can be used to provide source
files through a simple UNC share.

Set up the web site

Set up a web site to share the source files from and note the root directory of the site. You will probably also want to
make the pdbs available on the web site, using Symbol Server technology. So you might have symbols and source made
available from locations such as this…

https://diehelkthidoeodlby.com/symbols
https://diehelkthidoeodlby.com/source

While it is outside the scope of this document to describe how to set up a web site, there are some step-by-step
instructions for doing this in symhttp.doc that ships with the “Debugging Tools For Windows” package. Please note that
much of these instructions apply specifically to symbol servers.

Extract and locate the source files

Use srctool.exe –x to extract all the source files from all the modules that you want to provide source for. You need to
run this tool on pdb files that have already been source indexed for your version control system and you will need to run
the tool on a computer that has version control access. This will put all the source files into a common directory tree.
Copy the contents of this tree to the root of the web site. You can do this as often as you wish on any new products or
modules that you wish to add. There is no worry about files overwriting each other, since the directory tree structure
keep dissimilar files separated and uniquely accessible.

A script file called walk.cmd is provided in this package to make it easier to run srctool.exe and other scripts on all
matching files within a directory tree. walk.cmd walks recursively through a directory tree and executes any specified
command on any file that matches a passed file mask. You can pass a simple file mask if you want it to start in the
current working directory, or you can pass the starting directory with the file mask. Here is an example…
 walk.cmd c:\symbols\*.pdb srctool.exe -x

This will run the srctool file extraction on all pdb files in c:\symbols or directories below it.

Modify the pdb source indexing streams

pdb: specifies the name of the pdb to modify. For the debugger clients to use the Source Server web site, the pdbs
must be modified to point to it. Normally you would make a copy of all the pdbs, change them, and make them
available from a separate location, usually the web site, itself.

Three files are provided to assist you in reconfiguring the pdbs. cv2http.cmd and cv2http.pl extract the Source Server
stream, modify it through a perl script, and put the altered stream back in the pdb.

cv2http.cmd: pdb alias url

you must specify a pdb file,
a logical http site alias
and the URL of the site

The script takes three required parameters…

pdb: specifies the name of the pdb to modify.

alias: specifies the logical name to apply to your web site.
url: specifies the full URL of the site.

The alias parameter is especially interesting; as it will be stored in the pdb as a variable name that can be overridden on
the debugger client in srcsrv.ini should you ever move the location of the web site.

This script requires that all the standard Source Server tools be available in the path, since it calls both srctool.exe and
pdbstr.exe. Don’t forget that cv2http.pl is a Perl script and can be modified as you see fit to meet your needs.

You can use walk.cmd to modify an entire set of pdb files.

walk.cmd *.pdb cv2http.cmd HTTP_ALIAS https://diehelkthidoeodlby.com/source

The above command will call cv2http.cmd on every pdb file in a tree, passing the following parameters…

the name of each pdb

HTTP_ALIAS for the alias
https://diehelkthidoeodlby.com/source for the url.

After running this command on a tree of pdb files, they will be ready for installation into the web site (or whatever
location you want to put them. You may want to refer to the Symbol Server documentation for more details on this.
Remember that you can use srctool.exe and pdbstr.exe to examine the changes to the pdbs.

UNC Shares
There is nothing preventing you from using these same scripts to provide source files from a simple UNC share. To do
this, just eliminate all the previously described steps for setting up a web site. When calling cv2http.cmd, replace the url
parameter with the root of the UNC share that you extracted the source files to with srctool.exe, like so…

walk.cmd *.pdb cv2http.cmd MY_SOURCE_ROOT \\server\share

Supporting HTTP/UNC along with regular version control with the same pdb
Imagine the scenario in which you want to support your developers using the standard Source Server functionality that
extracts files from version control, however you also want to make source files available through a web site or UNC
share. This may make sense if you have set up a test lab that does not have access to version control. It is possible to
support both users using the same set of pdbs.

First, extract the source files using srctool.exe as described previously and make the share available as either a web site
or UNC share. Then ignore all the steps that convert the pdbs using cv2http.cmd.

Now on the computers that will use the HTTP/UNC shares, edit the srcsrv.ini that is in the debugger directory. In the
[variables] section of the file, add the following three statements…

MY_SOURCE_ROOT=\\server\share
SRCSRVCMD=
SRCSRVTRG=%MY_SOURCE_ROOT%\%var2%\%var3%\%var4%\%fnfile%(%var1%)

You should replace “\\server\share” with the root of the UNC share you are providing or the URL of the web site that
contains the source files. You can also change “MY_SOURCE_ROOT” to be any alias you want that describes this
location. With these exceptions, everything else should be entered exactly as described.

All debuggers set up in this fashion will ignore the standard version control extraction instructions, and will, instead,
access the source files from the location specified. Meanwhile, all debuggers without these items included in srcsrv.ini
will use the normal version control mechanism to extract source files.