ITADN
osandov/drgn
代码 动态 Issues109 合并请求162 版本11
osandov/drgn · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

drgn

|pypi badge| |ci badge| |docs badge| |black badge|

.. |pypi badge| image:: https://img.shields.io/pypi/v/drgn :target: https://pypi.org/project/drgn/ :alt: PyPI

.. |ci badge| image:: https://github.com/osandov/drgn/workflows/CI/badge.svg :target: https://github.com/osandov/drgn/actions :alt: CI Status

.. |docs badge| image:: https://readthedocs.org/projects/drgn/badge/?version=latest :target: https://drgn.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black

.. start-introduction

drgn（发音为“dragon”）是一个强调可编程性的调试器。 drgn 暴露了程序中的类型和变量，以便在 Python 中进行轻松、富有表现力的 脚本编写。例如，你可以调试 Linux 内核：

.. code-block:: pycon

>>> from drgn.helpers.linux import list_for_each_entry
>>> for mod in list_for_each_entry('struct module',
...                                prog['modules'].address_of_(),
...                                'list'):
...    if mod.refcnt.counter > 10:
...        print(mod.name)
...
(char [56])"snd"
(char [56])"evdev"
(char [56])"i915"

虽然其他调试器如 GDB <https://www.gnu.org/software/gdb/>_ 也 支持脚本，但 drgn 旨在使脚本编写尽可能自然，从而 让调试感觉如同编码。这使得它非常适合内省大型程序中 复杂的、相互关联的状态。

此外，drgn 被设计为一个库，可用于构建调试 和内省工具；请参阅官方 tools <https://github.com/osandov/drgn/tree/main/tools>_。

drgn 是在 Meta <https://opensource.fb.com/>_ 开发的，用于调试 Linux 内核（作为 crash <https://crash-utility.github.io/>_ 工具的替代方案），但它也可以调试用 C 编写的用户空间 程序。C++ 支持正在开发中。

.. end-introduction

文档可在 drgn.readthedocs.io <https://drgn.readthedocs.io>_ 找到。

.. start-installation

安装

包管理器 ^^^^^^^^^^^^^^^

drgn 可以在某些 Linux 发行版上使用包管理器进行安装。

.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg?exclude_unsupported=1 :target: https://repology.org/project/drgn/versions :alt: Packaging Status

  • Fedora, RHEL/CentOS Stream >= 9

    .. code-block:: console

    $ sudo dnf install drgn

  • RHEL/CentOS < 9

    Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>_. 然后：

    .. code-block:: console

    $ sudo dnf install drgn

  • Oracle Linux >= 8

    启用 ol8_addons or ol9_addons 仓库。然后：

    .. code-block:: console

    $ sudo dnf config-manager --enable ol8_addons  # OR: ol9_addons
$ sudo dnf install drgn

drgn 也可用于应用程序流中的 Python 版本。例如，使用 dnf install python3.12-drgn 为 Python 3.12 安装 drgn。 请参阅 Oracle Linux 9 <https://docs.oracle.com/en/operating-systems/oracle-linux/9/drgn/how_to_install_drgn.html>_ 和 Oracle Linux 8 <https://docs.oracle.com/en/operating-systems/oracle-linux/8/drgn/how_to_install_drgn.html>_ 中关于 drgn 的文档以获取更多信息。

  • Debian >= 12 (Bookworm)/Ubuntu >= 24.04 (Noble Numbat)

    .. code-block:: console

    $ sudo apt install python3-drgn

    要在 Ubuntu 上获取最新版本，请先启用 michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>_。

  • Arch Linux

    .. code-block:: console

    $ sudo pacman -S drgn

  • Gentoo

    .. code-block:: console

    $ sudo emerge dev-debug/drgn

  • openSUSE

    .. code-block:: console

    $ sudo zypper install python3-drgn

pip ^^^

如果你的 Linux 发行版未打包 drgn 的最新版本，你可以使用 pip <https://pip.pypa.io/>_ 进行安装。

首先，安装 pip <https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers>_。 然后，运行：

.. code-block:: console

$ sudo pip3 install drgn

默认情况下，这将安装二进制 wheel。如果你遇到构建错误，则说明 pip 无法使用二进制 wheel。安装 以下 <#from-source>_ 列出的依赖项并重试。

请注意，RHEL/CentOS 7、Debian 10 ("buster") 和 Ubuntu 18.04 ("Bionic Beaver")（及更早版本）附带的 Python 版本过旧。必须安装 Python 3.8 或更高版本。

.. _installation-from-source:

From Source ^^^^^^^^^^^

要获取 drgn 的开发版本，你需要从源代码构建它。 首先，安装依赖项：

  • Fedora, RHEL/CentOS Stream >= 9

    .. code-block:: console

    $ sudo dnf install autoconf automake check-devel elfutils-debuginfod-client-devel elfutils-devel gcc git json-c-devel libkdumpfile-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

  • RHEL/CentOS < 9, Oracle Linux

    .. code-block:: console

    $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git json-c-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

    可选地，在 RHEL/CentOS >= 8 上从 EPEL 安装 libkdumpfile-devel，或者 从源代码安装 libkdumpfile <https://github.com/ptesarik/libkdumpfile>_ 以支持 makedumpfile 格式。对于 Oracle Linux >= 7， 可以直接从相应的 addons 仓库安装 libkdumpfile-devel （例如 ol9_addons）。

    对于 RHEL/CentOS/Oracle Linux < 8，请将 dnf with yum 替换为。

    在 RHEL/CentOS/Oracle Linux < 8 上构建时，你可能需要使用更新版本的 GCC，例如使用 devtoolset-12 开发者工具集。 请查阅你的发行版文档以获取安装和使用这些新工具链的信息。

  • Debian/Ubuntu

    .. code-block:: console

$ sudo apt install autoconf automake check gcc git libdebuginfod-dev libjson-c-dev libkdumpfile-dev liblzma-dev libelf-dev libdw-dev libpcre2-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

在 Debian <= 11 (Bullseye) 和 Ubuntu <= 22.04 (Jammy Jellyfish) 上， libkdumpfile-dev 不可用，因此如果您需要支持 makedumpfile 格式， 必须从源代码安装 libkdumpfile。

  • Arch Linux

    .. code-block:: console

    $ sudo pacman -S --needed autoconf automake check gcc git json-c libelf libkdumpfile libtool make pcre2 pkgconf python python-pip python-setuptools xz

  • Gentoo

    .. code-block:: console

    $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils dev-libs/json-c dev-libs/libpcre2 sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools app-arch/xz-utils

  • openSUSE

    .. code-block:: console

    $ sudo zypper install autoconf automake check-devel gcc git libdebuginfod-devel libdw-devel libelf-devel libjson-c-devel libkdumpfile-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

然后，运行：

.. code-block:: console

$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install

.. end-installation

有关更多选项，请参阅 安装文档 <https://drgn.readthedocs.io/en/latest/installation.html>_。

快速入门

.. start-quick-start

drgn 默认调试正在运行的内核；只需运行 drgn。要调试正在运行的程序，请运行 drgn -p $PID。要调试核心转储（内核 vmcore 或用户空间核心转储），请运行 drgn -c $PATH. Make sure to 安装 调试符号 <https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>_， 针对你要调试的对象。

然后，你可以使用 prog["name"] 访问程序中的变量，并使用 . 访问结构体成员：

.. code-block:: pycon

$ drgn
>>> prog["init_task"].comm
(char [16])"swapper/0"

你可以使用各种预定义的辅助函数：

.. code-block:: pycon

>>> len(list(bpf_prog_for_each()))
11
>>> task = find_task(115)
>>> cmdline(task)
[b'findmnt', b'-p']

你可以使用 stack_trace() 获取堆栈跟踪，并使用 trace["name"] 访问参数或局部 变量：

.. code-block:: pycon

>>> trace = stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]["list"]
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'

.. end-quick-start

有关更多详细信息和功能，请参阅 user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>_。

.. start-for-index

获取帮助

  • GitHub issue tracker <https://github.com/osandov/drgn/issues>_ 是 报告问题的首选方式。
  • 此外，还有一个 Linux Kernel Debuggers Matrix 房间 <https://matrix.to/#/#linux-debuggers:matrix.org>_ and a linux-debuggers 邮件列表 <https://lore.kernel.org/linux-debuggers/>_ on vger <https://subspace.kernel.org/vger.kernel.org.html>_。

许可证

Copyright (c) Meta Platforms, Inc. and affiliates.

drgn 在 LGPLv2.1 <https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>_ 或更高版本许可证下授权。

.. end-for-index