mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-22 17:23:06 +00:00
4c5c5f3842
We currently bundle a version of elfutils with patches to export additional stack tracing functionality. This has a few drawbacks: - Most of drgn's build time is actually building elfutils. - Distributions don't like packages that bundle verions of other packages. - elfutils, and thus drgn, can't be built with clang. Now that we've replaced the elfutils DWARF unwinder with our own, we don't need the patches, so we can drop the bundled elfutils and fix these issues. Signed-off-by: Omar Sandoval <osandov@osandov.com>
140 lines
4.1 KiB
ReStructuredText
140 lines
4.1 KiB
ReStructuredText
drgn
|
|
====
|
|
|
|
.. image:: https://img.shields.io/pypi/v/drgn
|
|
:target: https://pypi.org/project/drgn/
|
|
:alt: PyPI
|
|
|
|
.. image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
|
|
:target: https://github.com/osandov/drgn/actions
|
|
:alt: CI Status
|
|
|
|
.. image:: https://readthedocs.org/projects/drgn/badge/?version=latest
|
|
:target: https://drgn.readthedocs.io/en/latest/?badge=latest
|
|
:alt: Documentation Status
|
|
|
|
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
|
:target: https://github.com/psf/black
|
|
|
|
.. start-introduction
|
|
|
|
drgn (pronounced "dragon") is a debugger with an emphasis on programmability.
|
|
drgn exposes the types and variables in a program for easy, expressive
|
|
scripting in Python. For example, you can debug the Linux kernel:
|
|
|
|
.. 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"
|
|
|
|
Although other debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ have
|
|
scripting support, drgn aims to make scripting as natural as possible so that
|
|
debugging feels like coding. This makes it well-suited for introspecting the
|
|
complex, inter-connected state in large programs. It is also designed as a
|
|
library that can be used to build debugging and introspection tools; see the
|
|
official `tools <https://github.com/osandov/drgn/tree/master/tools>`_.
|
|
|
|
drgn was developed for debugging the Linux kernel (as an alternative to the
|
|
`crash <http://people.redhat.com/anderson/>`_ utility), but it can also debug
|
|
userspace programs written in C. C++ support is in progress.
|
|
|
|
.. end-introduction
|
|
|
|
Documentation can be found at `drgn.readthedocs.io
|
|
<https://drgn.readthedocs.io>`_.
|
|
|
|
Installation
|
|
------------
|
|
|
|
.. start-install-dependencies
|
|
|
|
Install dependencies:
|
|
|
|
Arch Linux:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo pacman -S --needed autoconf automake gawk gcc libelf libtool make pkgconf python python-setuptools
|
|
|
|
Debian/Ubuntu:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo apt-get install autoconf automake gawk gcc libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-setuptools
|
|
|
|
Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship
|
|
Python and elfutils versions which are too old. Python 3.6 and elfutils 0.176
|
|
or newer must be installed manually.
|
|
|
|
Fedora:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo dnf install autoconf automake elfutils-devel gawk gcc libtool make pkgconf python3 python3-devel python3-setuptools
|
|
|
|
Optionally, install:
|
|
|
|
* `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ if you want
|
|
support for kdump-compressed kernel core dumps
|
|
|
|
.. end-install-dependencies
|
|
|
|
Then, run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo pip3 install drgn
|
|
|
|
See the `installation documentation
|
|
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more options.
|
|
|
|
Quick Start
|
|
-----------
|
|
|
|
.. start-quick-start
|
|
|
|
drgn debugs the running kernel by default; run ``sudo drgn``. To debug a
|
|
running program, run ``sudo drgn -p $PID``. To debug a core dump (either a
|
|
kernel vmcore or a userspace core dump), run ``drgn -c $PATH``. The program
|
|
must have debugging symbols available.
|
|
|
|
Then, you can access variables in the program with ``prog['name']``, access
|
|
structure members with ``.``, use various predefined helpers, and more:
|
|
|
|
.. code-block:: pycon
|
|
|
|
$ sudo drgn
|
|
>>> prog['init_task'].comm
|
|
(char [16])"swapper/0"
|
|
>>> d_path(fget(find_task(prog, 1), 0).f_path.address_of_())
|
|
b'/dev/null'
|
|
>>> max(task.stime for task in for_each_task(prog))
|
|
(u64)4192109975952
|
|
>>> sum(disk.gendisk.part0.nr_sects for disk in for_each_disk(prog))
|
|
(sector_t)999705952
|
|
|
|
.. end-quick-start
|
|
|
|
See the `user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>`_
|
|
for more information.
|
|
|
|
License
|
|
-------
|
|
|
|
.. start-license
|
|
|
|
Copyright (c) Facebook, Inc. and its affiliates.
|
|
|
|
drgn is licensed under the `GPLv3
|
|
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.
|
|
|
|
.. end-license
|