[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Houdini

How to Debug Custom HDK Code


  • Debugging on Linux

  • Debugging on Linux


    Compiling HDK code with Debugging Turned On

    Use hustom's -g option to compile with debugging information turned on. Without debugging information, the debugger cannot print variable contents and it cannot display source code line numbers. For example, to compile SOP_CustomSop.C, run

    hcustom -g SOP_CustomSop.C

    If Custom Operators Will Not Load Into Houdini

    Make sure the HOUDINI_DSO_ERROR environment variable is set. When this environment variable is set, houdini will print out error messages for any custom dso's that did not load correctly.

    Running Houdini Through a Debugger

    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. Note that SGI machines often don't crash when dereferencing null, so HDK code that runs fine on an SGI might crash on linux.

    gdb (the GNU debugger) is the default debugger for linux. Start gdb by passing it the name of the program being debugged (ie. the path to the houdini executable):

    gdb `which houdini`

    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 behaviour 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

    run -foreground

    If houdini crashes, the where (also aliased as bt) command will give a stack trace. The up and down commands will change the current frame of the stack trace. If your code was compiled with -g, where should give line numbers for crashes in your code.

    After changing custom code and recompiling, there is no need to quit gdb to restart houdini. run -foreground will restart houdini and load the changes you made to your custom dso.

    To quit gdb, type quit.

    Setting Breakpoints

    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 sop. 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, type

    break SOP_Custom::method()

    Note that pressing tab will attempt to complete a method name when setting a breakpoint. Tab is very useful because you don't have to type in the method signature yourself. To break at a specific line number in a file, type

    break SOP_Custom.C:29

    To trace through your code, use the next and stepgdb commands. step will enter into function calls, while next will skip over function calls. To resume execution, use the continue command.

    GDB Abbreviations

    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:
    where whe (or bt)
    run r
    continue c
    print p
    next n
    step s
    quit q

    Disabling Automatic Crash Recovery

    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.

    Be sure to unset these environment variables if you want houdini to save the hip file on a crash. Also note that large core files will be generated if this environment variable is 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:

    gdb `which houdini` core

    Using DDD

    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.

    To start DDD, run

    ddd `which houdini`

    To start houdini from 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

    Note that gdb commands can be run directly via the gdb window.

    Using Assertions

    Note that passing the -g option to hcustom will enable houdini assertions. To use houdini assertions, include <UT/UT_Assert.h> 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're 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 -g is not passed to hcustom.

    On NT systems, pressing the Debug button on an assertion window will invoke the debugger automatically. On Unix systems, however, pressing the Debug buggon 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

    gmsgp -b Debug:1,Ignore:2,IgnoreAll:3 --title="Assertion Failure" -print

    Table of Contents
    Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
    Material & Texture | Objects | Command and Expression | Render Output |
    Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
    Customizing UI | Questions & Answers

    Copyright © 2004 Side Effects Software Inc.
    477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7