That programs have bugs is a given in modern times. We all make mistakes, and even if we don’t, we use somebody else’s code, which may contain errors. When your program crashes on user’s computer, you should know about it, and that’s where Crash Reporting comes in. We all have seen it in Windows, MacOS X and even in KDE applications. But what if you want to add such capability to your own project?<\/p>\n
As long as you’re only using mobile platforms like iOS, Android or Windows Phone, you have a rich choice of 3rd-party APIs which allows generation, collection and processing of crash reports. iOS has TestFlight. For a cross-platform applications, you may use HockeyApp SDK or CApptain. But on desktop, your choice is limited.<\/p>\n
Actually, I was unable to find any free alternatives to Google’s Breakpad<\/a>. The good news, however, is that Breakpad is a well-tested piece of code (it is used in Mozilla Firefox and some other major software products) and it’s certainly cross-platform. In fact, not only does it support desktop, but also mobile platforms!<\/p>\n However, its integration is far from straightforward.<\/p>\n <\/p>\n From what I can see, Breakpad does not offer any ready-made packages on its page. So, your only options is to check out its sources from Google’s Git via command provided here<\/a>. After that, things begin to go slightly wrong. gyp is a Python script, so first be sure to download and install Python 2.7. A copy of gyp source tree is included in Breakpad Git, so you do not need to download it separately. To generate Visual Studio solution, run this string from command line (I’m assuming you have added %BreakpadFolder%\\src\\tools\\gyp\\ to your path): 2015 update:<\/b>Well, Google decided to remove a section on building Breakpad for Windows completely from their documentation. Also, Gyp is no longer included in Breakpad repository (even though it would be much easier to to this with Git and its submoudles system). Still, basic steps remain the same: get Gyp, use Gyp to generate Visual Studio project, use generated project to build Breakpad.<\/p>\n First, you’ll need to check out Gyp<\/a> in a directory somewhere. You’ll also need a copy of Python 2.7, which could be obtained from the official site<\/a>. Then, assuming that you added Gyp root folder to Path or are using the full path to to batch file, you can use the following command line to generate a Visual Studio project:<\/p>\n gyp.bat –no-circular-check src\\client\\windows\\breakpad_client.gyp -Dwin_release_RuntimeLibrary=2 -Dwin_debug_RuntimeLibrary=2<\/b><\/p>\n If you need to, you can also specify Visual Studio version, for which you want your project to be generated. I did it via environment variable “set GYP_MSVS_VERSION=2010”, but I guess you can just pass it throught command line with -DMSVS_VERSION=2010 (I haven’t tried it, though).<\/p>\n The first switch is necessary to make gyp work at all, since otherwise it will report an error. The second and the third switch is more interesting. In fact, it tells gyp to generate a project which will use “\\MD” switch (Multi-Threaded DLL) instead of “\\MT” (Multi-Threaded) when choosing CRT version. You may omit this, if you NEED to use static version of CRT, or specify 0 instead of 2.<\/p>\n This will generate \\src\\client\\windows\\breakpad_client.sln and various other files. The project generated by Gyp, however, would not compile by default. It seems like Breakpad’s maintainers are treating Windows as a second-class platform and do not bother to keep it working. The first thing you will need to do is to disable C\/C++->General->Treat Warnings As Errors for all projects. Otherwise you will get errors in Windows SDK headers. Even after that, some projects still would not compile, because they lack necessary files or are mis-configured, but you should be able to get all you need for following integration steps: common.lib, crash_generation_client.lib, crash_report_sender.lib and exception_handler.lib.<\/p>\n Please note, that despite the fact that gyp is a cross-platform project generator, Breakpad ONLY uses it for generating Windows projects. On all other systems, you can use the usual configure && make process. This difference makes it harder to integrate Breakpad in a cross-platform product, but oh well…<\/p>\n Google’s instructions about Windows Client Integration<\/a> are perfectly OK in that they tell you what to do with your code. However, Breakpad authors advise to include the whole source tree for Breakpad in your project and build it along with everything else. It seems to me that whoever wrote this was bitten by a radioactive stupid. Breakpad is not a small library, with sprawling source tree, which even includes some binary files. You don’t need all this trash in your own repository.<\/p>\n However, Breakpad does not make it easy to separate end-user files (libraries and headers) from source files. You will have to do it by hand. Here’s a list of directories and files that you will need for basic integration (with sending of crash reports to server):<\/p>\n You will also need this libraries:<\/p>\n You may want to clean those directories of .cc files and other trash.<\/p>\n Now, to make Breakpad work, in your application you will only need to include exception_handler.h<\/b>, and, if you need to send crash reports to server, client\/windows\/sender\/crash_report_sender.h<\/b>.<\/p>\n Please note, that under other OSes, you will need a slightly different set of files and directories (oh, the pain).<\/p>\n Here, I will repeat a basic process for integrating Breakpad into your code.<\/p>\n First, include exception_handler.h<\/b> and create an instance of google_breakpad::ExceptionHandler:<\/p>\n Note, that the directory you have specified for storing dumps should already be created – Breakpad will not create it itself. Also, it should be writeable by your application, obsviously.<\/p>\n Callback functions (DmpFilter and DmpCallback) are needed if you want to do something when crash happens. For example, if you want to ask user if he WANTS to send you a crash report, you can do it in Filter callback, and then, if he answers yes, use CrashReportSender in Minidump callback.<\/p>\n For your convenience, here’s some information about constants used by ExceptionHandler:<\/p>\n For information about Microsoft’s minidump type (in example, MiniDumpNormal is used), see MSDN<\/a>.<\/p>\n You can just ask your users to send you minidumps generated by breakpad to your mail, or upload them manually, but Breakpad also includes facility for sending them to server directly. There is a class, called CrashReportSender in client\/windows\/sender\/crash_report_sender.h<\/b>, which is easy to use.<\/p>\n In your MinidumpHandler, write something like this:<\/p>\n Now that you have a client that sends crash reports, you may wonder where’s the server which will receive and store them. Unfortunately, Google does not provide such server, even a basic one. Unless you want to write one yourself (which could be easy or hard, depending on feature set), you have just two alternatives.<\/p>\n There is Mozilla’s Socorro<\/a> server, which can handle millions of crashes per day, display all kinds of statistics about them, aggregate them in useful manner etc. Unfortunately, it’s a bitch to set up, because it has a list of dependencies long enough to scare a grown man, including non-negotiable PostgressSQL database. I haven’t even tried it.<\/p>\n The other server is mini-breakpad-server<\/a>. It has very small number of features, but it’s far easier to set up, even though it requires Node.js. It only supports uploading and displaying of crash reports with resolved symbols, but it should be enough for the most small projects.<\/p>\n One thing it does NOT support is uploading of symbol files. Documentation specifies that you should upload them manually into pool\/symbols\/PRODUCT_NAME. This is a (partial) lie. Actually, your symbols should be stored in this way:<\/p>\n pool\/symbols\/ExeOrDllName.pdb\/VERSION_ID\/ExeOrDllName.sym<\/b><\/p>\n Note, that Breakpad does not use native symbol formats (pdb, dwarf or otherwise), but instead its own, which can be generated from native formats by running dump_syms<\/b> or symupload<\/b> tools, provided with Breakpad. VERSION_ID could be obtained from .sym file by looking for a long string of digits and letters in the first line of file.<\/p>\n After you have mini-breakpad-server set up correctly (don’t forget to change its directory’s ownership to a proper user!), you can now specify “http:\/\/your.site:1127\/post” in call to SendCrashReport, and a minidump file will be uploaded.<\/p>\n This tools are bound to Visual Studio version. So, for example, if they are compiled with VS2013, they will NOT work with PDB files generated by VS2010. Versions, which are committed to Google’s Git are created in Visual Studio 2013. If you need to use them with some other version, you’ll have to recompile them yourself (which shouldn’t be hard), otherwise you’ll get some cryptic errors about msdia*.dll<\/b> not being registered.<\/p>\n Returning to mini-breakpad-server, I found that you can’t install it using npm<\/b>, as specified in documentation, because some dependencies are broken. However, you can just download it from GitHub and run npm install<\/b> in its root directory. After that, run bin\/mini-breakpad-server<\/i> and watch it work (don’t forget to run it a a daemon if you want to collect crash reports at all times!).<\/p>\n I found the process of uploading symbols manually to be inconvenient, so I modified mini-breakpad-server to allow using Google’s symupload<\/b> to upload symbols to correct paths from my Windows machine. Some time, I’ll try to get my changes merged into master branch, but currently you can download my modified version here: mini-breakpad-server-maxed.zip<\/a>. If you use this version, you can run<\/p>\n symupload YourProgram.exe http:\/\/your.server:1127\/symbols<\/b><\/p>\n and symbols should be uploaded to a correct path.<\/p>\n I found all information necessary to get all this set up from examining source files and, in one case, running strace to find out where the hell does mini-breakpad-server looks for symbol files. I hope this post should make up somewhat for the lack of documentation for both Breakapd and mini-breakpad-server. If you have any further questions, feel free to post them here.<\/p>\n","protected":false},"excerpt":{"rendered":"1. Getting and compiling Breakpad on Windows<\/h3>\n
The documentation says “Once you build the solution inside src\/client\/windows, an output file of exception_handler.lib will be generated.”<\/i> However, there is no Visual Studio solution in this directory. You have to generate it using Google’s alternative to CMake, gyp<\/a> (Generate Your Project).<\/p>\n
\n<\/strike><\/p>\n2. Integrating Breakpad with your application<\/h3>\n
\r\n|--google_breakpad\r\n |---processor\r\n |---common\r\n|--common\r\n |---windows\r\n|---client\r\n |---windows\r\n |---crash_generation\r\n |---sender\r\n |---handler\r\n |---common\r\nexception_handler.h\r\n<\/pre>\n
\r\ncrash_report_sender.lib\r\ncrash_generation_client.lib\r\ncommon.lib\r\nexception_handler.lib\r\n<\/pre>\n
\r\n \/\/ Creates a new ExceptionHandler instance to handle writing minidumps.\r\n \/\/ Before writing a minidump, the optional filter callback will be called.\r\n \/\/ Its return value determines whether or not Breakpad should write a\r\n \/\/ minidump. Minidump files will be written to dump_path, and the optional\r\n \/\/ callback is called after writing the dump file, as described above.\r\n \/\/ handler_types specifies the types of handlers that should be installed.\r\n \r\n google_breakpad::ExceptionHandler *pHandler = new google_breakpad::ExceptionHandler( \r\n L"dumps\\\\", \r\n DmpFilter, \r\n DmpCallback, \r\n 0, \r\n google_breakpad::ExceptionHandler::HANDLER_ALL, \r\n MiniDumpNormal, \r\n L"", \r\n 0 );\r\n<\/pre>\n
\r\nenum HandlerType {\r\n HANDLER_NONE = 0,\r\n HANDLER_EXCEPTION = 1 << 0, \/\/ SetUnhandledExceptionFilter\r\n HANDLER_INVALID_PARAMETER = 1 << 1, \/\/ _set_invalid_parameter_handler\r\n HANDLER_PURECALL = 1 << 2, \/\/ _set_purecall_handler\r\n HANDLER_ALL = HANDLER_EXCEPTION |\r\n HANDLER_INVALID_PARAMETER |\r\n HANDLER_PURECALL\r\n };\r\n<\/pre>\n3. Sending crash information to server<\/h3>\n
\r\n \/\/ Instantiate CrashReportSender, specifying checkpoint file, where it stores information about number of dumps sent per day, to limit itself\r\n\tgoogle_breakpad::CrashReportSender sender( L"crash.checkpoint" );\r\n \/\/ Set maximum numer of reports per day from one user, or -1 for unlimited reports\r\n\tsender.set_max_reports_per_day( 5 );\r\n \/\/ You can fill this map with additional params, for example, video adapter information or application's inner version, or something\r\n\tstd::map<std::wstring, std::wstring> params;\r\n \/\/ Callback parameters do not give you an exact name of generated minidump file, but you can reconstruct it\r\n\tstd::wstring filename = dump_path;\r\n\tfilename += L"\\\\";\r\n\tfilename += minidump_id;\r\n\tfilename += L".dmp";\r\n \/\/ Finally, send a report\r\n\tgoogle_breakpad::ReportResult r = sender.SendCrashReport( L"http:\/\/your.site.here", params, filename, 0 );\r\n\r\n \/\/ Possibly notify user about success\/failure\r\n\tif ( r == google_breakpad::RESULT_SUCCEEDED )\r\n\t\tMessageBox( 0, "Crash report was sent. Thank you!", "Crash report", MB_OK|MB_ICONINFORMATION );\r\n\telse\r\n\t\tMessageBox( 0, "Could not send crash report. Thank you for trying, though!", "Crash report", MB_OK|MB_ICONWARNING );\r\n\r\n\treturn false;\r\n<\/pre>\n
4. Receiving crash reports<\/h3>\n
\nPLEASE NOTE: My version of server could now be obsolete; I’m not planning on maintaining it until I have the need to do it, so you might be better off by looking at one of the forks<\/a> of original server, some of which are in active development<\/b><\/p>\n5. Conclusion<\/h3>\n