Metadata-Version: 2.1
Name: drgn
Version: 0.0.29
Summary: Programmable debugger
Home-page: https://github.com/osandov/drgn
Author: Omar Sandoval
Author-email: osandov@osandov.com
License: LGPL-2.1-or-later
Project-URL: Bug Tracker, https://github.com/osandov/drgn/issues
Project-URL: Documentation, https://drgn.readthedocs.io
Description: 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 (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.
        
        Additionally, drgn is designed as a library that can be used to build debugging
        and introspection tools; see the official `tools
        <https://github.com/osandov/drgn/tree/main/tools>`_.
        
        drgn was developed at `Meta <https://opensource.fb.com/>`_ for debugging the
        Linux kernel (as an alternative to the `crash
        <https://crash-utility.github.io/>`_ 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>`_.
        
        .. start-installation
        
        Installation
        ------------
        
        Package Manager
        ^^^^^^^^^^^^^^^
        
        drgn can be installed using the package manager on some Linux distributions.
        
        .. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
            :target: https://repology.org/project/drgn/versions
            :alt: Packaging Status
        
        * Fedora >= 32
        
          .. code-block:: console
        
              $ sudo dnf install drgn
        
        * RHEL/CentOS >= 8
        
          `Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_. Then:
        
          .. code-block:: console
        
              $ sudo dnf install drgn
        
        * Arch Linux
        
          Install the `drgn <https://aur.archlinux.org/packages/drgn/>`_ package from
          the `AUR <https://wiki.archlinux.org/title/Arch_User_Repository>`_.
        
        * Debian >= 12 (Bookworm)
        
          .. code-block:: console
        
            $ sudo apt install python3-drgn
        
        * Gentoo
        
          .. code-block:: console
        
              $ sudo emerge dev-debug/drgn
        
        * openSUSE
        
          .. code-block:: console
        
              $ sudo zypper install python3-drgn
        
        * Ubuntu
        
          Enable the `michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_.
          Then:
        
          .. code-block:: console
        
              $ sudo apt install python3-drgn
        
        pip
        ^^^
        
        If your Linux distribution doesn't package the latest release of drgn, you can
        install it with `pip <https://pip.pypa.io/>`_.
        
        First, `install pip
        <https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers>`_.
        Then, run:
        
        .. code-block:: console
        
            $ sudo pip3 install drgn
        
        This will install a binary wheel by default. If you get a build error, then pip
        wasn't able to use the binary wheel. Install the dependencies listed `below
        <#from-source>`_ and try again.
        
        Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and
        older) ship Python versions which are too old. Python 3.6 or newer must be
        installed.
        
        From Source
        ^^^^^^^^^^^
        
        To get the development version of drgn, you will need to build it from source.
        First, install dependencies:
        
        * Fedora
        
          .. code-block:: console
        
              $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
        
        * RHEL/CentOS
        
          .. code-block:: console
        
              $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
        
          Optionally, install ``libkdumpfile-devel`` from EPEL on RHEL/CentOS >= 8 or
          install `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ from
          source if you want support for the makedumpfile format.
        
          Replace ``dnf`` with ``yum`` for RHEL/CentOS < 8.
        
        * Debian/Ubuntu
        
          .. code-block:: console
        
              $ sudo apt install autoconf automake check gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
        
          Optionally, install libkdumpfile from source if you want support for the
          makedumpfile format.
        
        * Arch Linux
        
          .. code-block:: console
        
              $ sudo pacman -S --needed autoconf automake check gcc git libelf libtool make pkgconf python python-pip python-setuptools
        
          Optionally, install `libkdumpfile
          <https://aur.archlinux.org/packages/libkdumpfile/>`__ from the AUR or from
          source if you want support for the makedumpfile format.
        
        * Gentoo
        
          .. code-block:: console
        
              $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils 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
        
        * openSUSE
        
          .. code-block:: console
        
              $ sudo zypper install autoconf automake check-devel gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
        
        Then, run:
        
        .. code-block:: console
        
            $ git clone https://github.com/osandov/drgn.git
            $ cd drgn
            $ python3 setup.py build
            $ sudo python3 setup.py install
        
        .. end-installation
        
        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``. Make sure to
        `install debugging symbols
        <https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>`_ for
        whatever you are debugging.
        
        Then, you can access variables in the program with ``prog['name']`` and access
        structure members with ``.``:
        
        .. code-block:: pycon
        
            $ sudo drgn
            >>> prog['init_task'].comm
            (char [16])"swapper/0"
        
        You can use various predefined helpers:
        
        .. code-block:: pycon
        
            >>> len(list(bpf_prog_for_each()))
            11
            >>> task = find_task(115)
            >>> cmdline(task)
            [b'findmnt', b'-p']
        
        You can get stack traces with ``stack_trace()`` and access parameters or local
        variables with ``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
        
        See the `user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>`_
        for more details and features.
        
        .. start-for-index
        
        Getting Help
        ------------
        
        * The `GitHub issue tracker <https://github.com/osandov/drgn/issues>`_ is the
          preferred method to report issues.
        * There is also a `Linux Kernel Debuggers Matrix room
          <https://matrix.to/#/#linux-debuggers:matrix.org>`_.
        
        License
        -------
        
        Copyright (c) Meta Platforms, Inc. and affiliates.
        
        drgn is licensed under the `LGPLv2.1
        <https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>`_ or later.
        
        .. end-for-index
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Operating System Kernels :: Linux
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: COPYING
