This project describes a workflow and contains tools that make it possible to use a Git repository hosting service (such as GitHub, BitBucket or GitLab) as a debugging symbol and source server that is usable by the Debugging Tools for Windows.

In the following we assume that you have a repository USER/REPO and that the build process produces debugging symbols in the Microsoft PDB format that you wish to make available publicly for use in WinDbg, Visual Studio, etc.

The recommended setup is to create a new repository named USER/REPO.sym that will be used to contain all debugging symbols that you wish to publish. You then add this project (SymSrv) as a submodule under tools:

git submodule add https://github.com/billziss-gh/symsrv.git tools

Suppose that the build process of the USER/REPO repository produces debugging symbols that we wish to publish. We will be publishing those debugging symbols in the sym subdirectory of the USER\REPO.sym repository using the symadd.ps1 command.

Here is an example from the WinFsp project:

billziss@xps:~\Projects\winfsp.sym [test]> .\tools\symadd.ps1 ..\winfsp\build\VStudio\build\Debug\
GitDir: C:\Users\billziss\Projects\winfsp
Origin: https://github.com/billziss-gh/winfsp.git
Commit: 368855676ac602b426c75ae6d7d3a8a47fcc5889
SymDir: C:\Users\billziss\Projects\winfsp.sym\tools\..\sym

Finding ID...  0000000001

SYMSTORE: Number of files stored = 17
SYMSTORE: Number of errors = 0
SYMSTORE: Number of files ignored = 0

NOTE: By default the symadd.ps1 utility places symbols either in the sym or ..\sym directory relative to where the utility is located. It checks the directories for existence in order and if neither directory exists it assumes that the sym subdirectory is desired. If you are following the recommended project setup and this is the first time using symadd.ps1, then the sym directory will not exist and symadd.ps1 will place the symbols under tools\sym, which is likely not desirable. To avoid this make sure to execute mkdir sym in the root of the USER\REPO.sym repository prior to executing symadd.ps1 for the first time.

The symadd.ps1 utility will copy the PDB files and will place them in the file hierarchy required by the Debugging Tools for Windows. It will also modify the PDB files to add information directing the Debugging Tools on how to download the correct version of the associated source files directly from the hosting service (e.g. GitHub)!

All that remains is to commit and push the added files using commands such as:

git add sym
git commit -m "Release XXX"
git push

Suppose that symbols have been published in the USER/REPO.sym using the process described above. To use the symbols you simply need to add the following path to your debugging symbol path:

GitHub:    https://github.com/USER/REPO.sym/raw/BRANCH/sym
BitBucket: https://bitbucket.org/USER/REPO.sym/raw/BRANCH/sym
GitLab:    https://gitlab.com/USER/REPO.sym/-/raw/BRANCH/sym

For example, to enable symbol and source servers in WinDbg for WinFsp:

.sympath+ https://github.com/billziss-gh/winfsp.sym/raw/test/sym
.srcfix

Then upon hitting a breakpoint -- like magic! 🪄🪄🪄

The Debugging Tools for Windows have the capability to fetch symbols and sources from a variety of locations including HTTP servers. We exploit the fact that hosting services can serve raw files from a repository using HTTP and we setup our publishing repository in a manner as to be usable by the Debugging Tools.

For this purpose the symadd.ps1 utility does the following:

• Uses the symstore utility to copy the PDB files to be published and place them in the appropriate file hierarchy.
• Uses the srctool utility to extract a list of source files referenced by each copied PDB file.
• Determines the listed source files that are tracked by Git in one of the supported hosting services.
• Uses the pdbstr utility to write a special srcsrv stream in each PDB file that contains relocation information for any source files found.

For example, the PDB file winfsp-x64.sys.pdb is one of the products of the WinFsp build. Once published it may end up in a location such as https://github.com/billziss-gh/winfsp.sym/raw/test/sym/winfsp-x64.sys.pdb/177B495A386D458FB3697EE3E3EC04C91/winfsp-x64.sys.pdb; this is a location that the Debugging Tools know how to find once the symbol path has been set appropriately.

The published PDB file will also contain relocation information for the associated source files, so the source file C:\Users\billziss\Projects\winfsp\src\sys\driver.c may be redirected to https://github.com/billziss-gh/winfsp/raw/368855676ac602b426c75ae6d7d3a8a47fcc5889/src/sys/driver.c. Notice the use of the commit number to ensure that the correct version of the source will be used!

This project requires Git and the Debugging Tools for Windows to be installed. The command line git must also be in the PATH.

This project is made available under the MIT license.