openbmc-tools/ipkdbg/README.md

1 # `ipkdbg`: Generate gdb environments from opkg package archives
3 `ipkdbg` automates the process of generating `gdb` environments for interactive
7 ## Use of `ipkdbg`
10 using `ipkdbg` requires minimal fuss.
14     ipkdbg [-q] RELEASE FILE CORE [PACKAGE...]
25 $ ipkdbg 2.11.0 - my-application.core
32 1. `ipkdbg` is the script
37 Note that for convenience `ipkdbg` automatically runs `bt` in the `gdb` session
41 the image package database is available. `ipkdbg` will perform a reverse-lookup
44 `ipkdbg` will identify the associated debug symbol and source packages and
47 If an image package database is not available then `ipkdbg` will require that
52 For use in scripting environments to automate backtrace extraction `ipkdbg` has
57 ipkdbg -q 2.11.0 - my-application.core
63 running instance of `/usr/bin/my-application` on the BMC. `ipkdbg` is then used
67 $ ipkdbg 2.11.0 /usr/bin/my-application -
74 1. `ipkdbg` is the script
80 the image package database is available. `ipkdbg` will perform a reverse-lookup
83 `ipkdbg` will identify the associated debug symbol and source packages and
86 If an image package database is not available then `ipkdbg` will require that
97 To save exiting the `gdb` session and re-invoking `ipkdbg` to add a package to
98 the rootfs environment, `ipkdbg` installs an `opkg` helper into the PATH of the
106 `ipkdbg` is intended to operate with minimal assumptions about its environment.
117 However, `ipkdbg` also relies on `opkg` to get its job done. As `opkg` is itself
119 managers. A conflicting requirement is that we want `ipkdbg` to be able to run
120 almost anywhere without fuss. To resolve these issues `ipkdbg` packages `opkg`
122 directory is the input script ([`ipkdbg.in`](ipkdbg.in)) and build
123 infrastructure ([`Makefile`](Makefile)) for generating an `ipkdbg` executable
126 `ipkdbg` supports multiple distros and architectures by defining a directory
128 using `tar` and `gzip`, and the archive embedded in the `ipkdbg` shell script by
154 final `ipkdbg` script. The output script can then be freely copied between
158 binaries under `bin/` to ensure that the build for your output `ipkdbg` script
163 For `ipkdbg` to do its job via `opkg` it must be possible for it to acquire an
166 where this configuration lives. `ipkdbg` will bootstrap by fetching this
179 Finally, `ipkdbg` works best when it has access to the image's installed package
191 `ipkdbg` assumes that the appropriate `opkg-database.tar.xz` can be fetched