| 187 | | |
| 188 | | == Symbol Stores == |
| 189 | | |
| 190 | | === Introduction === |
| 191 | | |
| 192 | | In order to obtain useful diagnostic information in the event of an application crash, it is necessary to dump a callstack and any other relevant information about what was going on at the time of the crash. Symbols are only needed during a crash event, therefore they are stripped from most applications to cut down on the binary size and bandwidth requirements to deploy a new release. |
| 193 | | |
| 194 | | Without symbols, callstacks tend to be nothing more than a list of function pointers in memory. A developer has to load the un-stripped executable in memory using the same operating system and similar processor to jump to that memory address in order to determine the function name and parameters. This is very labor intensive and generally not a very fun job. |
| 195 | | |
| 196 | | Microsoft created a technology called a 'Symbol Store' to use with their debugger technology which allows Windows debuggers to locate and download compressed symbol files to diagnose problems and convert function pointers into human readable text. This greatly speeds up the process of diagnosing and fixing bugs. |
| 197 | | |
| 198 | | With the BOINC Runtime Debugger for Windows framework a project can publish their symbol files and only have to distribute the application to each of the BOINC clients. When a crash event occurs the runtime framework will download the symbol file from the symbol store and then proceed to dump as much diagnostic information as possible to help projects diagnose the failure. |
| 199 | | |
| 200 | | === Requirements === |
| 201 | | You'll need the latest stable release of the [http://www.microsoft.com/whdc/devtools/debugging/default.mspx Debugging Tools for Windows. ] |
| 202 | | |
| 203 | | Verify that your executable is setup to generate PDB debugging symbols for a release build. |
| 204 | | |
| 205 | | Verify that the advance linker option to generate a checksum is enabled for a release build. |
| 206 | | |
| 207 | | You'll need to explicitly name both your EXE and PDB before compilation since the debugger bases the name of the PDB file off of information that is stored in the executable header. |
| 208 | | |
| 209 | | === Project Symbol Store === |
| 210 | | |
| 211 | | Specifying a project wide symbol store is as easy as adding the symstore element to your config.xml file for the project. |
| 212 | | |
| 213 | | Below is an XML shred with an example symstore element. |
| 214 | | |
| 215 | | {{{ |
| 216 | | <boinc> |
| 217 | | <config> |
| 218 | | <symstore>http://sample.example.com/symstore</symstore> |
| 219 | | </config> |
| 220 | | </boinc> |
| 221 | | }}} |
| 222 | | |
| 223 | | === Adding symbols to the symbol store === |
| 224 | | [http://msdn.microsoft.com/en-us/library/cc266480.aspx Symstore] is a utility to manage symbol stores. You'll want to create a local symbol store on your Windows build machine in which you'll initially add new symbol files with each revision of your application. |
| 225 | | |
| 226 | | Symstore will compress the symbol file and then copy it into your local symbol store. |
| 227 | | |
| 228 | | Below is an example command which you can run from the Windows command line or cygwin command line. |
| 229 | | |
| 230 | | {{{ |
| 231 | | symstore.exe add /l /f c:\SampleSrc\*.pdb /s c:\symstore /compress /t "Sample" /v "5.02" /o /c "Application Release" |
| 232 | | }}} |
| 233 | | |
| 234 | | === Uploading symbols to the symbol store === |
| 235 | | |
| 236 | | Most projects tend to use scp to copy files between Windows machines and their project server. |
| 237 | | |
| 238 | | The example below copies the entire symstore to the target location. After the copy operation you can delete all the subdirectories except '000Admin' to save time uploading for future application symbols. |
| 239 | | |
| 240 | | {{{ |
| 241 | | pscp.exe -r -C -batch c:\symstore sample@project.example.com:projects/sample/html/user/symstore |
| 242 | | }}} |
