
maemo-debug-scripts
-------------------

This is intended as a convenience package for Maemo developers
needing to debug their programs.  It will:

* Post-install a symlink required by Gdb/Valgrind/Oprofile to find
  the debug symbol files in Scratchbox.  The files are installed
  to /usr/lib/debug/<library path>, but in Scratchbox the library
  realpaths are /targets/<target name>/<library path>.

* Depends from libc6-dbg.  Without libc6-dbg threads cannot be
  debugged with Gdb and Valgrind reports redundant errors for the
  dynamic loader (its error suppressions for /lib/ld functions can
  match them only with the debug symbol file as stripped binary
  doesn't contain static function names)

* Depend from target native Gdb.  The Scratchbox host version of Gdb
  (cross-gdb) doesn't know how to load the correct thread library
  (even on x86) and it cannot debug ARM core-dumps.  Native one can.

* Install a few helper scripts:

  + native-gdb
    - runs the target native Gdb (by default Scratchbox runs
      the host binarary if it exists, the script overrides that)

  + debug-dep-install
    - installs debug symbols for given binaries and their dependencies
      listed by "ldd"

  + debug-pkg-check
    - checks the correctness of a debug package for a given package

  + list-mmapped-libs
    - lists all packages containing libs and binaries that given process
      uses.  It can be used to find out the libraries mmap()ed through
      dlopen that "ldd" (used by debug-deb-install script) doesn't find

  + run-with-valgrind
    - helper script for running a binary with Valgrind memcheck plugin
      (memory access errors, leaks etc) so that all suitable options
      are set for it

  + run-with-callgrind
    - helper script for running a binary with Valgrind callgrind plugin
      (performance profiling) so that all suitable options are set for it

  + run-with-helgrind
    - helper cript for running a binary with Valgrind helgrind plugin
      (thread error detector) so that all suitable options are set for it

  + run-with-massif
    - helper script for running a binary with Valgrind massif plugin
      (memory usage visualization) so that all suitable options
      are set for it

  + run-with-strace
    - helper script for running a binary with strace.  Like above
      helper scripts, handles maemo-launched binaries automatically

-- Eero Tamminen
