Application Debugging with the Kernel Debugger (Compact 7)
3/12/2014
Platform Builder includes a kernel debugger that can debug both applications and the run-time image. An important difference between the Platform Builder kernel debugger and the Visual Studio application debugger is that the Visual Studio debugger controls only the behavior of a single application, while the kernel debugger controls the behavior of the entire run-time image, including any applications that are running on the OS.
You can debug both applications that are subprojects of an OS design and applications that you built by using an SDK as long as you have the compilation symbols corresponding to the application’s source code as explained below. When used as an application debugger, the kernel debugger differs from the Visual Studio application debugger in the following ways:
- The kernel debugger can debug code both in the Windows Embedded Compact kernel and in an application running on Windows Embedded Compact.
- When you stop the kernel debugger, the run-time image stops responding to outside input while it waits for feedback from the kernel debugger. Because of this behavior, you must manually run any application that you want to debug with the kernel debugger.
- The debugger and the application run independently: when you shut down an application that is being debugged on the device, the kernel debugger continues to run. Similarly, when you issue a stop debugging command to the kernel debugger, the application being debugged continues to run on the device.
- The kernel debugger requires compilation symbols.
- To perform application debugging, the kernel debugger must have access to the compilation symbols for the application. Symbols for application modules are contained in the program database (.pdb) files located in the Release directory. (As an alternative to putting the .pdb files in the Release directory, you can map your application’s source code files to their .pdb files in other directories. For more information, see Associate Source Code with PDB Files.) If you want to create a .pdb file for an application that has an extension other than .dll or .exe, make a copy of the application with the extension .dll in the same directory as the original application. For example, if you want symbols for Main.cpl, make a copy of it in the same target directory as Main.cpl and call the file Main.dll.
- The kernel debugger uses unique debug zones and debug messages.
- Debug zones provide a way to selectively turn on and off debugging message output. Each module (a .dll or .exe) has its own debug zones. If a zone is active, messages for that zone are printed. If a zone is inactive, messages for that zone are suppressed. With debug zones, you can trace execution of the code without halting the Windows Embedded Compact OS. For more information, see Add Debug Messages and Use Debug Zones.
You can use the kernel debugger to debug an application as follows.
To debug an application by using the kernel debugger
Build your OS and your application.
Put your application executable and its associated .pdb file in the Release directory if they aren’t there already. Alternatively, you can map your application’s source code files to their .pdb files. For more information, see Associate Source Code with PDB Files.
Note
The kernel debugger must have access to the compilation symbols for the application, which are typically in the .pdb file. If a file has an extension that is not .exe or .dll, then you must make a copy of the file with the .dll extension in the same directory as the original file.
If you have not already configured a transport and downloaded the OS and the application to the device, you must do so before you can begin debugging. For more information, see Download the OS to a Target Device for Debugging.
In Platform Builder, on the File menu, click Open, and select the source code file for your application.
To set breakpoints in the source code file, place the cursor in a line of code and press F9. Because your application is not running yet, the breakpoint appears as a hollow circle with a yellow caution triangle. Your breakpoints only become solid red when the application is running on your device.
While the OS is running on your device, on the Platform Builder Target menu, do the following:
- Click Run Programs.
- In the Available Programs list, click the name of the .exe file for your application.
- Click Run to start your application.
When execution stops at the breakpoint in your application, and you are ready to resume execution of the application, press the F5 key.