72c4116368
Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> |
||
---|---|---|
.github | ||
src | ||
.gitignore | ||
.nvmrc | ||
LICENSE | ||
README.md | ||
package.json | ||
tsconfig.json | ||
yarn.lock |
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
- You must use all-lowercase keys when uploading your symbols to S3.
- 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!
Path Prefix
You can add an optional PATH_PREFIX
environment variables for shorter URLs.
This prefix will be prepended to all requests paths to the S3 bucket.
heroku config:add PATH_PREFIX=/awesome/symbols
Now the symbol server URL can be http://pepto-symbol.gadgetron.com
.
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:
- Fork the project to your own account
- Clone down your fork
- Create a thoughtfully named topic branch to contain your change
- Hack away
- If you are adding new functionality, document it in README.md
- Do not change the version number, I will do that on my end
- If necessary, rebase your commits into logical chunks, without errors
- Push the branch up to GitHub
- Send a pull request for your branch
Copyright
Copyright (c) 2012 Adam Roben. See the LICENSE file for details.