The purpose of this chapter is to provide some advice on troubleshooting your Hipparchus-based application. This chapter is not intended as a general discussion on the art of debugging. You should refer to other sources for general input on this important subject. C/C++ can be very demanding when debugging, given all the freedom the languages allow (with pointers, structures, functions, etc.). One good book on the subject is entitled "C Traps and Pitfalls" by Andrew Koenig. See Appendix C - Bibliography.
One important item you must remember when developing your application is that the Hipparchus Library functions perform little data checking. For the sake of speed and efficiency, it is assumed that your application will perform the edits and checks prior to passing information to any of these functions.
If you are working with a 16-bit version of Hipparchus, you must be particularly alert to the possibility of 64K address wrap-around.
There are several debugging tools provided with the Hipparchus SDK that will help you when you are developing your applications. These tools include the following:
In addition, you may have access to other general debugging tools that may be of significant assistance. For example, for complex applications you may find it helpful to install one of the commercially available debugging software packages and route its output to a second computer for display, while your application is running. For the "how to" on these tools and techniques, we will leave you to access your own technical support sources.
The Hipparchus Library Reference Manual is your primary source of information on the specific use and application of the Hipparchus Library and Hipparchus Auxiliary Library functions. For each function, you have been supplied with the following:
If you use the details provided in the Hipparchus headers, you will have little difficulty in the proper syntactic usage of each of the functions. In general, the primary challenge will be in learning the semantics of each of the functions. And, as usual, much of your debugging energy will be spent in resolving issues and irregularities with your data. However, the latter will not likely be new to you and you will have your own tools and approaches for this.
Hipparchus contains a number of functions specifically designed for this purpose. In general, we have assumed that most developers will have graphical capability and will not be restricted to a text only capability. Nevertheless, as a last resort, the Hipparchus SDK includes some tools that operate at this level. The list includes the following functions that output the points or vertices defining an object, in text format:
As mentioned, these functions would likely only be used as a last resort during development. At a minimum, they illustrate how to traverse the internal structures, should you have a need to do this.
The old technique of lacing your source code with printf statements is still valid. But the text sent to your display can obliterate your graphic results. Dual display environments and commercial debugging tools can be more effective.
If you have a second machine, you can use the economy technique. Simply lace your application with fprintf statements sending the output to a serial port using stdaux. For example:
fprintf(stdaux, "Trace message here\n");
Then, with appropriate pauses, you can trace the graphic generation on one display and send the debug messages to another machine. You can do this using a null modem cable and some simple communications software. The second machine can then display the text messages in your fprintf statements. This is a helpful technique if you do not have a debugger or if you are concerned that your debugger might interfere with your graphical output. Using this technique, you can reduce your environment to a more simple state.
Sometimes, debugging can provide a solid justification for an advanced GUI. With such a GUI, you can open a separate debug window and send the fprintf output there while the application proceeds.
In developing your source programs, a consistent standard of indentation can also help. For source programs supplied with the Hipparchus SDK, the following standards have been used:
You may choose to follow a different standard. As long as you follow a consistent approach, your debugging effort will be reduced.
You will probably want to print off a copy of hipparch.h and the other header files supplied with Hipparchus. The structure and type definitions will be helpful in resolving inconsistent usage. Alternatively, if you are debugging in an integrated development environment, you may be able to make direct use its source code browser. Note that the on-line Hipparchus Library Reference Manual provides HTML extensive hyperlinks to the header definitions for the majority of structures referenced by the functions.
We have assumed that you will have some experience with the art of debugging. Specific debugging commands are provided. The on-line HTML Hipparchus Library Reference Manual provides extensive hyperlinked cross-references between function and header specifications. The utilities and sample applications provide additional examples and automated cross references once compiled in the presence of a source browser.