Merge pull request #806 from atom/symbols-server

Upload PDB to S3 when publishing and add docs on setting up symbol server

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)

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://54.249.141.255:8086/atom-shell/symbols.
+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://54.249.141.255:8086/atom-shell/symbols
+```
+
+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://54.249.141.255:8086/atom-shell/symbols
+```
+
+## 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
+```

script/lib/util.py

@@ -183,6 +183,7 @@ def s3put(bucket, access_key, secret_key, prefix, key_prefix, files):
     '--secret_key', secret_key,
     '--prefix', prefix,
     '--key_prefix', key_prefix,
+    '--no_overwrite',
     '--grant', 'public-read'
   ] + files
 

script/upload-windows-pdb.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+
+import os
+import glob
+
+from lib.util import execute, rm_rf, safe_mkdir, s3put, s3_config
+
+
+SOURCE_ROOT = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
+SYMBOLS_DIR = 'dist\\symbols'
+DOWNLOAD_DIR = 'vendor\\brightray\\vendor\\download\\libchromiumcontent'
+PDB_LIST = [
+  'out\\Release\\atom.exe.pdb',
+  DOWNLOAD_DIR + '\\Release\\chromiumcontent.dll.pdb',
+]
+
+
+def main():
+  os.chdir(SOURCE_ROOT)
+
+  rm_rf(SYMBOLS_DIR)
+  safe_mkdir(SYMBOLS_DIR)
+  for pdb in PDB_LIST:
+    run_symstore(pdb, SYMBOLS_DIR, 'AtomShell')
+
+  bucket, access_key, secret_key = s3_config()
+  files = glob.glob(SYMBOLS_DIR + '/*.pdb/*/*.pdb')
+  files = [f.lower() for f in files]
+  upload_symbols(bucket, access_key, secret_key, files)
+
+
+def run_symstore(pdb, dest, product):
+  execute(['symstore', 'add', '/r', '/f', pdb, '/s', dest, '/t', product])
+
+
+def upload_symbols(bucket, access_key, secret_key, files):
+  s3put(bucket, access_key, secret_key, SYMBOLS_DIR, 'atom-shell/symbols',
+        files)
+
+
+if __name__ == '__main__':
+  import sys
+  sys.exit(main())

script/upload.py

@@ -59,19 +59,24 @@ def main():
     upload_atom_shell(github, release_id,
                       os.path.join(DIST_DIR, CHROMEDRIVER_NAME))
 
-  # Upload node's headers to S3.
-  bucket, access_key, secret_key = s3_config()
-  upload_node(bucket, access_key, secret_key, ATOM_SHELL_VERSION)
-
   if args.publish_release:
-    # Press the publish button.
-    publish_release(github, release_id)
+    # Upload node's headers to S3.
+    bucket, access_key, secret_key = s3_config()
+    upload_node(bucket, access_key, secret_key, ATOM_SHELL_VERSION)
 
     # Upload the SHASUMS.txt.
     execute([sys.executable,
              os.path.join(SOURCE_ROOT, 'script', 'upload-checksums.py'),
              '-v', ATOM_SHELL_VERSION])
 
+    # Upload PDBs to Windows symbol server.
+    if TARGET_PLATFORM == 'win32':
+      execute([sys.executable,
+               os.path.join(SOURCE_ROOT, 'script', 'upload-windows-pdb.py')])
+
+    # Press the publish button.
+    publish_release(github, release_id)
+
 
 def parse_args():
   parser = argparse.ArgumentParser(description='upload distribution file')