| crashrpt |
A crash reporting system for Windows applications

# Preparing to Software Release

## Saving the Debugging Information Locally Before Software Release

When you are ready for a software release, the following steps must be performed to be able to properly read end user error reports later.

- Create a directory, for example name it 'CrashRptSaved'.
- In that directory create a subdirectory for your software release, for example 'MyApp v.1.3.5'.
- Copy all binary files (*.EXE, *.DLL) from your project output.
- Copy all debugging symbol files (*.PDB) from your project output.
- Save the source code that you used for compiling the application. If you use a version control system (e.g., SVN), mark the current revision of the code with tag to be able to restore its state later.

These steps should be performed for exactly the same software build that you plan to release. If you rebuild the project after files are copied, you must copy the files again.

When a crash report comes in, you use the release build, source code and symbols you copied, along with the minidump included in the crash report, to debug the crash.

Before release is made, it is recommended that you check if exceptions are properly intercepted (use the crEmulateCrash() function), that error reports are properly received by your support team and that you can properly read received error reports.

Note:
  Files copied to CrashRptSaved directory should be stored locally during the software life time. These saved files should NOT be included in the software release package and should NOT be sent to end users. You should never ship debug builds or debug symbols (PDB files) as they will not only take up more space on your CD/download/client's machine, but they will also make reverse engineering your code a trivial exercise.

## Distributing CrashRpt Files with Your Software Release Package

You must always distribute the following files with your software release. It is recommended that you place these files to the directory where your application executable file is located.

- CrashRpt.dll
- CrashSender.exe
- dbghelp.dll

The CrashRpt.dll and CrashSender.exe are core CrashRpt modules. dbghelp.dll (Microsoft Debug Help Library) is a dependent module.

Since v.1.1.3 it is also required that you copy a language INI file crashrpt_lang.ini to the folder where CrashSender.exe is located.

You can distribute several INI files with your software. On install, rename an appropriate file to crashrpt_lang.ini and copy it to the folder where your CrashSender.exe is located.

Note:
  It is recommended that you distribute dbghelp.dll with your software, because some end-user machines may not have dbghelp.dll installed or dbghelp.dll's version may be different on different user machines. dbghelp.dll is shipped with Windows XP and later, so most user machines have this library installed. If your target OS is Windows XP and later, you may ignore distribution of dbghelp.dll at your own risk.

## FAQ

I do not like that I should distribute all these DLLs. Can I compile them all as static libs?

No, this is impossible. You may ignore distribution of dbghelp.dll, but a end user's operating system may not have dbghelp.dll installed. In addition, architecture of CrashRpt requires two modules: CrashRpt.dll and CrashSender.exe. So, you have to distribute all these binaries.

I use a packer for my EXE or DLL (e.g. PECompact, UPX and so on). How does this affect the way I read the generated minidump file?

Feel free to use a compression utility for reducing the size of your executable or DLL, but be careful of the following.

In order to read the minidump, you need to save a local copy of the uncompressed EXE (DLL) file and a PDB file generated for that EXE (DLL). You also need to have the source code that you used when building the EXE (DLL). These should be enough to read the minidump generated by the compressed version of your EXE.

I sign my EXE with a digital certificate (Authenticode). How does this affect the way I read the generated minidump file?

Feel free to use an Authenticode utility for signing your executable, but be careful of the following.

In order to read the minidump, you need to save a local copy of the unsigned EXE file and a PDB file generated for that EXE. You also need to have the source code that you used when building the EXE. These should be enough to read the minidump generated by the signed version of your EXE.

I need to edit a resource embedded into my compiled EXE (DLL) binary (e.g. I need to upgrade its version). How this affects the way I read the generated minidump file?

Feel free to edit resources in your compiled binaries, but be careful of the following.

In order to read the minidump, you need to save a local copy of the original (unmodified) EXE (DLL) file and a PDB file generated for that EXE (DLL). You also need to have the source code that you used when building the EXE (DLL). These should be enough to read the minidump generated by the resource-modified version of your EXE (DLL).

I use IncrediBuild for compiling my project. Does crashrpt work with PDB files generated such way?

Yes, CrashRpt works with PDB files generated with help of IncrediBuild.

IncrediBuild is a platform for accelerating Visual C++ builds through by distributing the build processes over local area network.