5.8 KiB
~english \page debugging Debugging with GDB ~russian \page debugging Отладка в GDB
~english
PIP ships a GDB pretty-printer script, tools/gdb/pip_pp.py, that makes the basic types print their content instead of their raw internals:
| Type | Example output |
|---|---|
| \a PIString | "hello" |
| \a PIByteArray | {0x48, 0x65, 0x6c, 0x6c, 0x6f} |
| \a PIChar | 'a' or U+043c |
| \a PIVector | {1, 2, 3} |
| \a PIDeque | {1, 2, 3} |
| \a PIStringList | {"one", "two"} |
| \a PIMap<K,V> | {"x": 1, "y": 2} |
| \a PISet | {3, 5} |
| \a PIPair<K,V> | {"k", 7} |
| \a PIVariant | PIVariant(pivInt, 4 bytes) |
Nested containers are printed recursively, e.g. PIVector<PIString> prints as {"a", "bb"}.
Pointers to the covered types show the address and the content:
(PIString *) 0x7fffffffdac0 "hello".
Printers are read-only and defensive: on any error GDB falls back to the
default (raw) printing. Long containers are truncated, only the first
32 elements are printed by default (the tail is shown as
..., ... (N total)); the limit is the _MAX_ELEMENTS constant at the
top of pip_pp.py.
Requirements: the executable and the PIP library must be built with debug
information (-g).
\section loading Loading the pretty-printers
Manual (works with any build tree):
\code{.gdb} (gdb) source /path/to/pip/tools/gdb/pip_pp.py \endcode
Run it after the executable is loaded (in a session started as
gdb ./program, or after the file command).
Automatic: CMake install places the script at
<prefix>/share/pip/gdb/pip_pp.py and an auto-load stub
<prefix>/lib/libpip.so-gdb.py next to the library. GDB evaluates the stub
automatically when libpip.so is loaded (see GDB manual, "Auto-loading
extensions"). If the library is installed outside of GDB's default auto-load
safe path, add the directory once:
\code{.gdb} (gdb) add-auto-load-safe-path /your/prefix/lib \endcode
Or create /.gdbinit file and write to it next line \code add-auto-load-safe-path <root_dir> \endcode , where root_dir is top-level directory contains library and pip_pp.py script.
The stub is installed only for shared builds; for static builds
use the manual source command.
\section verifying Verifying the installation
A check script builds a demo with all covered types and asserts the expected GDB output:
\code{.bash} tools/gdb/test/test_pp.sh build_linux \endcode
~russian
Вместе с PIP поставляется скрипт pretty-printer'ов для GDB, tools/gdb/pip_pp.py,
который выводит содержимое базовых типов вместо их внутренних полей:
| Тип | Пример вывода |
|---|---|
| \a PIString | "hello" |
| \a PIByteArray | {0x48, 0x65, 0x6c, 0x6c, 0x6f} |
| \a PIChar | 'a' или U+043c |
| \a PIVector | {1, 2, 3} |
| \a PIDeque | {1, 2, 3} |
| \a PIStringList | {"one", "two"} |
| \a PIMap<K,V> | {"x": 1, "y": 2} |
| \a PISet | {3, 5} |
| \a PIPair<K,V> | {"k", 7} |
| \a PIVariant | PIVariant(pivInt, 4 bytes) |
Вложенные контейнеры выводятся рекурсивно, например PIVector<PIString>
выводится как {"a", "bb"}. Указатели на поддерживаемые типы показывают
адрес и содержимое: (PIString *) 0x7fffffffdac0 "hello".
Принтеры только читают память и защищены от ошибок: при любом сбое GDB
возвращается к стандартному (сырому) выводу. Длинные контейнеры обрезаются,
по умолчанию выводится первые 32 элемента (хвост показывается как
..., ... (N total)); ограничение задаётся константой _MAX_ELEMENTS
в начале файла pip_pp.py.
Требование: исполняемый файл и библиотека PIP должны быть собраны с
отладочной информацией (-g).
\section loading Загрузка принтеров
Вручную (работает с любым деревом сборки):
\code{.gdb} (gdb) source /path/to/pip/tools/gdb/pip_pp.py \endcode
Выполнять после загрузки исполняемого файла (в сессии, запущенной как
gdb ./program, или после команды file).
Автоматически: CMake install ставит скрипт в
<prefix>/share/pip/gdb/pip_pp.py и auto-load заглушку
<prefix>/lib/libpip.so-gdb.py рядом с библиотекой. GDB выполняет заглушку
автоматически при загрузке libpip.so (см. руководство GDB, "Auto-loading
extensions"). Если библиотека установлена вне стандартного auto-load safe path
GDB, добавьте каталог один раз:
\code{.gdb} (gdb) add-auto-load-safe-path /your/prefix/lib \endcode
Или создайте /.gdbinit файл и запишите туда строку \code add-auto-load-safe-path <root_dir> \endcode , где root_dir - это корневая директория, в рамках которой находятся библиотека и скрипт pip_pp.py.
Заглушка устанавливается только для shared-сборок; для статических сборок
используйте ручной source.
\section verifying Проверка установки
Скрипт проверки собирает демо со всеми поддерживаемыми типами и сверяет ожидаемый вывод GDB:
\code{.bash} tools/gdb/test/test_pp.sh build_linux \endcode