Testing And Debugging
From K-3D
K-3D must know the paths to external resources (e.g. plugins, share directory) before it can be run. The defaults for these paths are compiled into the program based on how it was configured for installation. Because of this, the executable cannot be run from the source tree unless you explicitly override the default paths. To facilitate testing, there is a special makefile target, "test", that overrides the defaults so you can run a newly-built executable without having to install it. After building the app, simply do
$ make test
to run the program in-place. All of the default resource paths will be overridden so that resources are loaded from the source tree instead of their installed locations. If you wish to pass additional command-line arguments to the program for testing, use the EXTRA_OPTIONS make variable:
$ make test EXTRA_OPTIONS="--no-splash --new"
... use the "--help" option or check the man page to see available arguments.
Debugging can also be tricky, since we use libtool to build the app. The problem is that libtool actually builds binary executables in a "hidden" location, and puts a script-wrapper in their place. As an example, after building K-3D, the main program "application/k3d-bin" is actually a libtool script, which links to the "real" binary executable "application/.libs/lt-k3d-bin". Thus, after a segfault, you have to give gdb the location to the "real" binary. There are two makefile targets to help. If you want to run K-3D in the debugger, do
$ make run-debug
... which will run gdb with all of the necessary arguments to run K-3D from the source tree. Just use the gdb "run" command to start the application.
If you've encountered a segfault while testing K-3D with "make test", a core file will be left behind in the top-level directory. To attach gdb to it and see what happened, do
$ make coredebug
... a good place to start troubleshooting here is with the gdb "bt" (backtrace) command, which will show the call stack at the time of the segfault.
While gdb is the bread-and-butter of debugging, there are some other useful utilities you can use to troubleshoot K-3D:
$ make strace $ make valgrind
... as you might have guessed, these run K-3D using the strace and valgrind utilities, respectively. strace traces operating system calls, which can be a handy for tracking a whole host of problems, particularly access problems with files (you can see every attempt to open a file). Valgrind is a powerful tool for detecting memory access problems - it has a big impact on performance, but it's worth its weight in gold when you're trying to find memory leaks and overruns.
See Makefile Targets for other handy items ...
