docs: Setting up symbol server in debugger

diff --git a/docs/README.md b/docs/README.md
index d22ef38..ed7d803 100644 (file)
--- a/docs/README.md
+++ b/docs/README.md
@@ -56,3 +56,4 @@ Modules for both sides:
 * [Build instructions (Mac)](development/build-instructions-mac.md)
 * [Build instructions (Windows)](development/build-instructions-windows.md)
 * [Build instructions (Linux)](development/build-instructions-linux.md)
+* [Setting up symbol server in debugger](development/setting-up-symbol-server.md)

diff --git a/docs/development/setting-up-symbol-server.md b/docs/development/setting-up-symbol-server.md
new file mode 100644 (file)
index 0000000..3b8b83d
--- /dev/null
+++ b/docs/development/setting-up-symbol-server.md
@@ -0,0 +1,56 @@
+# Setting up symbol server in debugger
+
+Debug symbols allow you to have better debugging sessions. They have information
+about the functions contained in executables and dynamic libraries and provide
+you with information to get clean call stacks. A Symbol Server allows the
+debugger to load the correct symbols, binaries and sources automatically without
+forcing users to download large debugging files. The server functions like
+[Microsoft's symbol server](http://support.microsoft.com/kb/311503) so the
+documentation there can be useful.
+
+Note that because released atom-shell builds are heavily optimized, debugging is
+not always easy. The debugger will not be able to show you the content of all
+variables and the execution path can seem strange because of inlining, tail
+calls, and other compiler optimizations. The only workaround is to build an
+unoptimized local build.
+
+The official symbol server URL for atom-shell is
+http://symbols.mozilla.org/firefox.
+You cannot visit this URL directly: you must add it to the symbol path of your
+debugging tool. In the examples below, a local cache directory is used to avoid
+repeatedly fetching the PDB from the server.  Replace `c:\code\symbols` with an
+appropriate cache directory on your machine.
+
+## Using the symbol server in Windbg
+
+The Windbg symbol path is configured with a string value delimited with asterisk
+characters. To use only the atom-shell symbol server, add the following entry to
+your symbol path (__note:__ you can replace `c:\code\symbols` with any writable
+directory on your computer, if you'd prefer a different location for downloaded
+symbols):
+
+```
+SRV*c:\code\symbols\*http://symbols.mozilla.org/firefox
+```
+
+Set this string as `_NT_SYMBOL_PATH` in the environment, using the Windbg menus,
+or by typing the `.sympath` command. If you would like to get symbols from
+Microsoft's symbol server as well, you should list that first:
+
+```
+SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols\*http://symbols.mozilla.org/firefox
+```
+
+## Using the symbol server in Visual Studio
+
+<img src='http://mdn.mozillademos.org/files/733/symbol-server-vc8express-menu.jpg'>
+<img src='http://mdn.mozillademos.org/files/2497/2005_options.gif'>
+
+## Troubleshooting: Symbols will not load
+
+Type the following commands in Windbg to print why symbols are not loading:
+
+```
+> !sym noisy
+> .reload /f chromiumcontent.dll
+```