Sourcepack (indexing PDB files with source archive file)

Introduction

When using third-party libraries in your projects, you often would like to know what’s happening inside the library. For close-source projects, there is no other way than using Reflector or ILSpy debugger (though we may end up with unreadable obfuscated code), but for Open Source projects, there should be no problems with loading the valid source code into the debugger. There is a great initiative (http://www.symbolsource.org/) which aims at providing source-indexed symbol files for Open-Source projects, but unfortunately, not many projects are available there and even for those accessible, their version is not always accurate. Finally, you are left with a manual setup and compilation of the source code (referencing the binaries using, for example, reference paths). But we could do it differently. I observed that it’s more and more popular for Open Source project authors to provide the binaries with their PDB files. The PDB files in this form (especially for managed applications/libraries) are not very useful, although it’s not difficult to change this situation. You will need a Sourcepack script and source code zip file (which is usually provided by the author besides the binaries). Sourcepack modifies the symbols PDB files so that they will reference the source archive file and any debugger (which supports source server) will be able to extract the required source file on demand.

The Sourcepack script is a PowerShell script which examines and then modifies the PDB files in the given directory to make them reference the source code archive file. Firstly we must have a quick look at the PDB file structure.
PDB file structure

When you build your application/library either in the debug or PDB-only release mode, the compiler will emit, besided the binaries, PDB files. In general, PDB files contain information for the debugger on how to bind the processor instruction addresses with the lines of the source code file (PDB files are even more important for native builds when they store metadata about the types and functions declared in the binaries). Normally, PDB files contain only absolute paths to the source code files and thus are usable only on machines which store the source code files in the same place as defined in the PDB file. To find those absolute addresses, you may use the srctool application (with the -r switch) which is a part of Debugging Tools for Windows:

srctool.exe -r ConsoleApplication1.pdb

However, it’s not the only way the PDB files may reference source code. There is a special stream in the PDB file which can inform the debugger where to look for a source code file. The stream format is very extensible and you can actually put there any command you want under only one condition - it must extract the desired source code file into the target directory. Normally, with Debugging Tools for Windows, you receive a bunch of scripts for different source code repositories (SourceSafe, CVS, Subversion). The source indexing usually consists of the following steps:

•     Index all source code files.

•     Index PDB files and match them with the already found source files.

•     Create a temporary stream file, which looks more or less like the one below (I marked with bold the mandatory fields, and in blue the section names):

    SRCSRV: ini ------------------------------------------------
    VERSION=1
    INDEXVERSION=2
    VERCTRL=Subversion
    DATETIME=Sat Aug 13 08:36:36 2011
    SRCSRV: variables ------------------------------------------
    SVN_EXTRACT_TARGET=%targ%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
    SVN_EXTRACT_CMD=cmd /c svn.exe cat "%var2%%var3%@%var4%" --non-interactive
    > "%svn_extract_target%"
    SRCSRVTRG=%SVN_extract_target%
    SRCSRVCMD=%SVN_extract_cmd%
    SRCSRV: source files ---------------------------------------
    d:\lab\symbols-lab\symbols\consoleapplication1\program.cs*svn://localhost/
    *Program.cs*2
    SRCSRV: end ------------------------------------------------

•     (More information about the stream file format may be found here.)

•     Write the temporary stream file to the PDB file.

Read more: Codeproject
QR:

Posted via email from Jasper-net