|
HDK
|
You need debug information to be enabled in your custom HDK Code. Without debugging information, the debugger cannot print variable contents, display source code line numbers or set breakpoints.
If you are compiling using hcustom, then you can use the -g flag to turn on debugging information. For example, to compile SOP/SOP_Flatten.C, run:
If you are compiling with a Makefile, make sure to pass the -g flag when compiling with g++. You can set these flags using the OPTIMIZER variable. Here is an example Makefile:
Similarly, when compiling with CL.exe, pass the /Z7 and /Od flags to turn on debugging and disable optimizations. Here is another example Makefile:
When finished, you can compile your HDK plugin or application as usual.
If a bug in custom HDK code causes Houdini to crash, the easiest way to find the point of the crash is to run Houdini through a debugger like gdb (the GNU debugger) on Linux and OSX. If you are developing on Windows, use the Microsoft Visual Studio debugger (see Using a Debugger on Windows: Visual Studio).
Start gdb by passing it the name of the program being debugged (ie. the path to the houdini executable). On Windows (cygwin), this would be $HFS/bin/houdini. On Linux, $HFS/bin/houdini is actually a wrapper script which invokes the real executable, $HFS/bin/houdini-bin. So when debugging, you will want to point gdb to houdini-bin instead of houdini. For example, on the command-line, run:
Once gdb loads, it will present you with the (gdb) prompt. The run command will start the program being debugged. Arguments passed to run will be passed to the program being run.
Since Houdini's default behavior is to run in the background by forking off another process, it is important that Houdini be started with the -foreground option. Otherwise, Houdini will fork and gdb will return the message "Program exited normally". So, to start Houdini, type:
If Houdini crashes, type the where command (or bt) at the gdb prompt to print a stack trace of the program's execution. You can use the up and down commands to jump between frames in the stack. If your code is compiled with debugging information, then the where command will display source files and line numbers for each frame in the stack.
Use the print command to display the contents of variables in the current frame of the stack trace. For more information on print, type help print at the gdb prompt. For more information on all the gdb commands, just type help instead.
If you want to quit gdb, type quit at the prompt. Otherwise, you can restart the Houdini session by typing run -foreground again. If you have made changes and recompiled your custom HDK code since starting gdb, then re-running the Houdini session will automatically load in those changes.
Note that when gdb starts it does not automatically load symbols from shared libraries, so you cannot set breakpoints. By interrupting Houdini after it has started by pressing Ctrl-C in the gdb window, you can set a breakpoint in your code. You can then continue execution with the continue command.
The break command in gdb will set breakpoints. To set a breakpoint at the start of a method, use the class name and method signature as an argument. If your class is in a separate namespace, make sure to include the namespace in the argument as well. For example, to set a breakpoint at the beginning of the SOP Flatten's cookMySop() method, type:
Alternatively, you can set a breakpoint at a specific line in the source code. For example, to break at line 166 in SOP/SOP_Flatten.C, type:
When Houdini hits a breakpoint, gdb will suspend execution and show you the command prompt. You can debug Houdini in the same fashion as debugging Houdini when it crashes.
To step through your code, use the next and step commands. step will enter into function calls, while next will skip over function calls. To resume execution and escape the gdb prompt, use the continue command.
gdb does not require you to type the full name of a command if it can uniquely identify the command. The following common commands can be abbreviated:
| Command | Abbreviation |
where | whe (or bt) |
run | r |
continue | c |
print | p |
next | n |
step | s |
quit | q |
ENTER (no command) at the prompt.DDD (the data display debugger) is a more user-friendly debugger that can be downloaded from http://www.gnu.org/software/ddd/. It uses gdb as a backend and is not available for Windows.
To start DDD, run:
To start Houdini with DDD, choose Program->Run and set "Run with Arguments" to -foreground.
To get a stack trace, run Status->Backtrace.
To set breakpoints, run Source->Breakpoints and press the Break button.
To interrupt Houdini from within DDD, run Program->Interrupt.
Valgrind is a an open source debugging tool on Linux and OSX that can automatically detect various memory-related bugs. It does so by running the child application in a specially instrumented virtual CPU. Although this causes the child to run 10-50 times slower, it is still useful for detecting many hard to find bugs.
To run Houdini with valgrind you need to tell it to use the native libc allocator instead of jemalloc. Here's an example:
When Houdini crashes, the Visual Studio Just-In-Time Debugger will attach itself to Houdini. A dialog will pop-up asking whether you would like to debug the crashed process. Click on Yes to open Microsoft Visual Studio and run the debugger. If you compiled your HDK code with debugging turned on, then you should see the source code and line which Houdini crashed on.
You can view the stack trace in the Call Stack pane of the Visual Studio interface.
To print the values of variables in the current frame of the stack, use the Watch List pane.
To trace through your code, press F10 to step over functions and F11 to step into functions. To continue, press F5. To quit debugging, press SHIFT + F5.
For more details on how to use the Visual Studio Debugger, please read the comprehensive online MSDN documentation: http://msdn.microsoft.com/en-us/library/k0k771bt.aspx.
Note that turning on debugging information at compile-time will enable Houdini assertions at run-time. To use Houdini assertions, include UT/UT_Assert.h in your HDK code and call UT_ASSERT(expression). If expression evaluates to true, nothing will happen. However, if it evaluates to false, a window will pop up giving the file and line number where the assertion failed. The window will give you the option to debug your code, ignore the assertion this time, or always ignore this assertion.
Assertions are very useful at finding bugs in your code at an early stage. They are a way of stating the conditions that you believe are guaranteed to be true at a particular point in your program, and which you rely on being true for your program to work correctly. For example, if you are about to deference a pointer, you might assert that the pointer is not null.
There is no performance penalty for using assertions since they are not compiled when debugging information is turned off.
On Windows, pressing the Debug button on an assertion window will invoke the debugger automatically. On Linux and Mac OSX systems, however, pressing the Debug button will call abort. If you are not already running Houdini through a debugger then a core file will be produced.
Note that on Linux, UT_ASSERT uses the xmessage command to display the assertion window. However, xmessage is broken in some versions of Linux. If you see the buttons on the assertion window but no text then your version of xmessage is broken. We recommend you download GNU's gmsgp as a replacement for xmessage. To tell Houdini to use gmsgp, set the HOUDINI_ASSERT_COMMAND environment variable to:
When Houdini crashes it will try to recover by saving the hip file to a temporary directory, displaying an error message, and exiting gracefully. When debugging custom HDK code through a debugger, however, this crash recovery can be a nuisance. To disable it, set the environment variables HOUDINI_COREDUMP and HOUDINI_UI_COREDUMP before running Houdini. On Windows, this will enable just in time debugging for debuggers such as Visual Studio. Be sure to unset HOUDINI_UI_COREDUMP if you want Houdini to save the hip file again on a crash.
On Unix operating systems, large core files will be generated if HOUDINI_COREDUMP or HOUDINI_UI_COREDUMP are set and Houdini crashes. If you start Houdini through gdb and it crashes, however, it will not generate a core file. To examine where Houdini crashed from a core file, pass the name of the core file as the second argument to gdb:
This is most likely due to a an error in the plugin library itself. Maybe an external library that your plugin requires is not referenced, or there might be missing symbols in the plugin, etc.
You can try setting the HOUDINI_DSO_ERROR environment variable. When HOUDINI_DSO_ERROR is set, Houdini prints out error messages for any custom dso's that did not load correctly.
1.8.6