Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

It makes Windows debug symbols on S3 easier to digest.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 Procfile
Octocat-spinner-32 README.md
Octocat-spinner-32 package.json
Octocat-spinner-32 pepto-symbol.js
README.md

Pepto Symbol

Pepto Symbol lets you use S3 as a Windows symbol server for debugging Windows-based applications.

Wait, what's a symbol server?

"Symbol files" (aka PDB files) contain information about your software that a debugger can use to show you backtraces, local variables, etc. They are generated by the compiler when you build your software. Debugging is a nightmare without symbols. Really.

A "symbol server" hosts symbol files for Windows-based software. Debuggers use symbol servers to obtain symbol files for the software you're debugging automatically. John Robbins has written a great article explaining all of this and more on his blog. Symbol servers can serve symbol files over HTTP or a Windows file share.

That doesn't sound so hard. Why do I need this?

symstore.exe, which creates the directory structure that the symbol server serves, and symsrv.dll, which implements the logic for retrieving symbols from a symbol server, operate case-insensitively (like much Windows software). This means that symsrv.dll might ask for symbols using a URL that uses uppercase where symstore.exe used lowercase, or vice versa.

Many web servers treat URLs case-insensitively. S3 does not. So one job of Pepto Symbol is to provide case-insensitive access to symbol files stored on S3.

In addition, if you try to access a file that doesn't exist on S3, you will get a 403 Forbidden error, rather than 404 Not Found. When symsrv.dll gets a 403 error from a symbol server, it blacklists that server for the rest of the debugging session. So Pepto Symbol also converts 403 errors to 404 errors.

Requirements

  1. You must use all-lowercase keys when uploading your symbols to S3.
  2. You need a server on which Pepto Symbol can run as an HTTP proxy.

Usage

Let's say you've uploaded your symbols (using lowercased keys, remember!) to http://my-bucket.s3.amazonaws.com/awesome/symbols, and that you're going to deploy Pepto Symbol to http://pepto-symbol.gadgetron.com/.

First, deploy Pepto Symbol to a server. Pepto Symbol comes preconfigured for deployment on Heroku:

heroku create --stack cedar
heroku config:add S3_BUCKET=my-bucket
git push heroku master

(It should be fairly simple to deploy it elsewhere if needed.)

Next, add the following URL to your symbol path:

http://pepto-symbol.gadgetron.com/awesome/symbols

That's it!

Running locally

To run Pepto Symbol locally on port 5000:

echo S3_BUCKET=my-bucket > .env
foreman start

Source

Pepto Symbol's Git repository is available on GitHub, and can be browsed at https://github.com/aroben/pepto-symbol. You can clone the repository with this command:

git clone https://github.com/aroben/pepto-symbol

Contributing

If you'd like to hack on Pepto Symbol, follow these instructions:

  1. Fork the project to your own account
  2. Clone down your fork
  3. Create a thoughtfully named topic branch to contain your change
  4. Hack away
  5. If you are adding new functionality, document it in README.md
  6. Do not change the version number, I will do that on my end
  7. If necessary, rebase your commits into logical chunks, without errors
  8. Push the branch up to GitHub
  9. Send a pull request for your branch

Copyright

Copyright (c) 2012 Adam Roben. See the LICENSE file for details.

Something went wrong with that request. Please try again.