\~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 | `{"x": 1, "y": 2}` | | \a PISet | `{3, 5}` | | \a PIPair | `{"k", 7}` | | \a PIVariant | `PIVariant(pivInt, 4 bytes)` | | \a PINetworkAddress | `192.168.1.10:8080` | Nested containers are printed recursively, e.g. `PIVector` 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 `/share/pip/gdb/pip_pp.py` and an auto-load stub `/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 \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 qtcreator Qt Creator Qt Creator's Variables/Expressions views do not use GDB pretty-printers; they run their own Python dumper. PIP provides the dumper module `tools/qtcreator/pip_types.py`, which covers the same types as `pip_pp.py`. To enable it: 1. Open the debugger settings (Qt Creator -> Settings -> Debugger). 2. Switch to the "Variables and expressions" tab. 3. In the "Extra dumper file" field (tooltip: "Path to a Python file containing additional data dumpers"), enter the path to the file: \code /path/to/pip/tools/qtcreator/pip_types.py \endcode After that PIString, PIVector, PIMap and the other types from the table above show their content in the Variables/Expressions views. No changes to the GDB setup (`.gdbinit`, auto-load stub) are needed for Qt Creator; those keep working for the command-line GDB. \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 | `{"x": 1, "y": 2}` | | \a PISet | `{3, 5}` | | \a PIPair | `{"k", 7}` | | \a PIVariant | `PIVariant(pivInt, 4 bytes)` | | \a PINetworkAddress | `192.168.1.10:8080` | Вложенные контейнеры выводятся рекурсивно, например `PIVector` выводится как `{"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 ставит скрипт в `/share/pip/gdb/pip_pp.py` и auto-load заглушку `/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 \endcode , где root_dir - это корневая директория, в рамках которой находятся библиотека и скрипт pip_pp.py. Заглушка устанавливается только для shared-сборок; для статических сборок используйте ручной `source`. \section qtcreator Qt Creator Окна Variables/Expressions в Qt Creator не используют pretty-printer'ы GDB — у них собственный Python-дампер. PIP предоставляет модуль дампера `tools/qtcreator/pip_types.py`, который покрывает те же типы, что и `pip_pp.py`. Для включения: 1. Откройте настройки отладчика (Qt Creator -> Настройки -> Отладчик). 2. Переключитесь на вкладку «Переменные и выражения». 3. В поле "Extra Debugging Helper" укажите путь к файлу: \code /path/to/pip/tools/qtcreator/pip_types.py \endcode После этого PIString, PIVector, PIMap и другие типы из таблицы выше будут показывать своё содержимое в окнах «Переменные» и «Выражения». Изменения в настройках GDB (`.gdbinit`, auto-load заглушка) для Qt Creator не нужны; они продолжают работать для GDB из командной строки. \section verifying Проверка установки Скрипт проверки собирает демо со всеми поддерживаемыми типами и сверяет ожидаемый вывод GDB: \code{.bash} tools/gdb/test/test_pp.sh build_linux \endcode