[In this reprinted #altdevblogaday-opinion piece, Valve Software programmer Bruce Dawson explains source indexing -- why you need it, what it is, and how to use it for C++ development.] If you've ever had to debug code that was not built on your machine – whether looking at crash dumps or debugging live code – then you need source indexing. If you've ever wasted time trying to find the source file (or the right version of the source file) used to build a DLL or EXE you are debugging, then you need source indexing. Source indexing (also known as source server) is free, fast, available since Visual Studio 2005, easy to use, and it ensures that the correct source file will always appear in your debugger, whether you're debugging a crash from yesterday or yesteryear. The problem is that most people don't know that source indexing exists. In this post, I'm going to explain why you need it, what it is, and how to use it for C++ development. TL;DR The length of this article makes source indexing look more complicated than it really is. Here's the short version. On your build machine you need to:
Modify srcsrv\srcsrv.ini (from the debugging tools) so that MYSERVER points at your Perforce server
run p4index.cmd to embed source indexing information in your PDBs
On your development machines you need to:
Click the check box to enable source server in your debugger
Create a srcrv.ini file (in your Visual Studio install directory, in "common7\ide") to tell VS to stop popping up security warnings
That's it. Read on for the details. The Need For Source Indexing When you step through code in your debugger – whether it's Visual Studio or windbg – you probably want to have the debugger show you your source code. Even if you are stepping through assembly language instructions, it is foolishly inefficient to not have the source code right there. If you built all of the binaries on your machine, then it is straightforward for the debugger to retrieve the correct source files. When VC++ builds your code it embeds the full paths to all of the source files in the PDB file. It also embeds records that associate ranges of instructions with a particular line in a source file. In optimized code this mapping is imperfect, but it gets you to the right area. If you are debugging locally built binaries and you have modified one of the source files since doing the build, then Visual Studio will detect this (by comparing file signatures) and warn you of the potential problem. So far so good. If you are debugging binaries from your build machine (you do have a build machine don't you?), especially if those binaries are from a few days or weeks ago, then this system doesn't work. The first problem is that the source file paths may not match, since the build machine may have a different directory structure for its enlistment. This can be addressed by manually locating the files on your machine, but that extra step is inconvenient. The larger problem is that the version of the source files used to build the binaries may not match what is on your machine. Visual Studio will warn you that the files don't match, but then you need to play a tedious game of find-the-version as you try to sync to the correct version of the source file in the correct branch. Wouldn't it be nice if as you stepped through code the debugger would just automatically retrieve the correct source files? What Is Source Indexing? What we need is a way to embed some extra information in the PDB file. Assuming that we are using Perforce for our version control (I'm a huge fan and it's free for limited use, so try it), then we can uniquely identify each checked in file by its Perforce path and version number. As an example, on my local machine I have this source file:
c:\homedepot\Source\libs\cygnuslib\simpletimer.cpp
This file exists on all clients of my Perforce database, but the path may be different on each client. However using the "p4 have" command I can get the depot path, which is:
//depot/Source/libs/cygnuslib/simpletimer.cpp#5
The depot path is not only a universal identifier of which file we are talking about; it also contains the version number of the file. Thus, if we embed the path above in a PDB file, and associate it with the existing file path which is already associated with blocks of instructions, then we have all of the information needed to retrieve the correct version of the correct file when debugging. That is exactly what source indexing does. It is a simple and efficient process that embeds version-control path and version-number information into the PDB. Both Visual Studio and windbg support this data and can use this information to automatically retrieve the necessary source files. Source indexing is also supported for other version control systems (Source Safe, TFS, and CVS) and can be extended to support arbitrary version control systems. However, since my experience is exclusively with Perforce that is all I will discuss. Running Source Indexing On Your Build Machine The source indexing tools and documentation are installed with the Windows debuggers, which come with the Windows SDK. The default path, for a 64-bit install, is:
No tags.
