- Item 9: Set Yourself Up for Debugging Success
- Item 10: Enable the Efficient Reproduction of the Problem
- Item 11: Minimize the Turnaround Time from Your Changes to Their Result
- Item 12: Automate Complex Testing Scenarios
- Item 14: Consider Updating Your Software
- Item 15: Consult Third-Party Source Code for Insights on Its Use
- Item 16: Use Specialized Monitoring and Test Equipment
- Item 17: Increase the Prominence of a Failure's Effects
- Item 18: Enable the Debugging of Unwieldy Systems from Your Desk
- Item 19: Automate Debugging Tasks
- Item 20: Houseclean Before and After Debugging
- Item 21: Fix All Instances of a Problem Class
Item 15: Consult Third-Party Source Code for Insights on Its Use
Often problems occur due to the way the code you’re debugging uses a third-party library or application (rather than actual bugs in that software—see Item 14: “Consider Updating Your Software”).
This is no surprise, because such software gets integrated with your code as a black box, and therefore you have fewer opportunities to coordinate. A powerful way to debug these problems is to consult the source code of third-party libraries, middleware, and even lower-level software.
First, if you need to know why a particular API behaves in an unexpected way or what triggers a cryptic error message, you can find the answer by browsing the third-party source code around the area that interests you. To debug functionality related to a library, locate the function or method definition and follow the code from there. You’re probably not looking for a bug in the library’s code, but rather for a better understanding of how the library works and ties in with your code. To understand an error message, search through all the code for the wording of the error message, and examine the code leading to it (see Item 23: “Utilize Command-Line Tool Options and Idioms” and Item 4: “Drill Up from the Problem to the Bug or Down from the Program’s Start to the Bug”). You can quickly locate the function or method you’re looking for by indexing the code with the ctags or etags program (most editors support its output), or with your integrated development environment (IDE). Your IDE is likely to handle sophisticated language features such as overloading, overriding, and templates better than ctags. On the other hand, etags handles many more languages: 41 in version 5.8. The following command, when run on a source code directory, will create an index for all files lying under it.
If the third-party code you’re using is open source, you can also search through it through a hosted service, such as the Black Duck Open Hub Code Search.
A more powerful technique involves building the third-party with debugging information (see Item 28: “Use Code Compiled for Symbolic Debugging”). Then link your code with the debug version of the library you built. Having done that, you can easily step through the third-party code and examine variables with the symbolic debugger (see Chapter 4), just as you can do with your own code. Note that some vendors, such as Microsoft, ship with their code debug builds or symbols. This saves you the effort of debug-building their code on your own.
If you happen to find that a fault lies in the third-party code rather than yours, with access to the source code you can actually correct it there. Use this option only in extreme circumstances: if there is no reasonable workaround, and you can’t get the vendor to fix it for you. Once you modify third-party code, you’ll be responsible for maintaining the change across its new versions for the lifetime of your application. Also ensure you’re legally allowed to modify the code. Some vendors ship their code with a “look, don’t touch” license. For open-source software, a reasonable option is to submit your changes to the project responsible for the code. This is also the right thing to do. If the project is hosted on GitHub, you can easily do that with a pull request.
For all these wonderful things to work, you need to have the third-party source code at hand. This is trivial if the library or application you’re using is open source. Then, you can download the source code with a click of a button. Open-source operating system distributions also offer you the ability to download the source code as a package; this is the command you would use under Debian Linux to install the C library source code.
sudo apt-get install glibc-source
In addition, many software development platforms will install important parts of their source code on your system. For instance, you can find the source code for the C runtime library of Microsoft’s Visual Studio at a location VC\crt\src and for the Java Development Kit in an archive named src.zip. In other cases, you may have to pay extra to obtain the source code when you order the third-party software. Insist on this option if the price is not exorbitant. Getting the source code later when you need it might require a lot of time to budget, place the order, and execute any required agreement. Also, the vendor might have stopped supporting the version you use or might even have gone out of business. Getting the source code for proprietary software beforehand is a reasonable insurance policy against these problems.
Things to Remember
Get the source code for third-party code you depend on.
Explore problems with third-party APIs and cryptic error messages by looking at the source code.
Link with the library’s debug build.
Correct third-party code only when there’s no other reasonable alternative.