JakeHillion/drgn
1
0
Fork 0
mirror of https://github.com/JakeHillion/drgn.git synced 2024-12-23 17:53:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
1cedca8ff4
drgn/README.rst

109 lines
3.1 KiB
ReStructuredText
Raw Normal View History

Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
drgn
====
Configure Travis CI
2019-04-11 21:16:48 +01:00
.. image:: https://travis-ci.org/osandov/drgn.svg?branch=master
:target: https://travis-ci.org/osandov/drgn
:alt: Build Status
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. image:: https://readthedocs.org/projects/drgn/badge/?version=latest
:target: https://drgn.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. start-introduction
Add pronunciation to README
2019-04-17 09:18:44 +01:00
drgn (pronounced "dragon") is a debugger-as-a-library. In contrast to existing
debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ which focus on
breakpoint-based debugging, drgn excels in live introspection. drgn exposes the
types and variables in a program for easy, expressive scripting in Python. For
example, you can debug the Linux kernel:
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. 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"
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 planned.
.. end-introduction
Documentation can be found at `drgn.readthedocs.io
<https://drgn.readthedocs.io>`_.
Installation
------------
Install the following dependencies:
* Python 3.6 or newer
* elfutils development libraries (libelf and libdw)
* GNU autotools (autoconf, automake, and libtool) and pkgconf
Add support for kdump-compressed core dumps with libkdumpfile
2019-08-02 08:00:59 +01:00
Optionally, install:
* `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ if you want
support for kdump-compressed kernel core dumps
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
Then, run:
.. code-block:: console
$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install
See the `installation documentation
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more details.
Quick Start
-----------
.. start-quick-start
Clarify that --kernel is the default in a couple more places Update the README to reflect that --kernel is the default, and clarify it a bit in argparse.
2019-06-28 22:04:15 +01:00
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.
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
Then, you can access variables in the program with ``prog['name']``, access
structure members with ``.``, use various predefined helpers, and more:
.. code-block:: pycon
Clarify that --kernel is the default in a couple more places Update the README to reflect that --kernel is the default, and clarify it a bit in argparse.
2019-06-28 22:04:15 +01:00
$ sudo drgn
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
>>> 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 2018-2019 Omar Sandoval
drgn is licensed under the `GPLv3
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.
.. end-license
Reference in New Issue Copy Permalink