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
988e9e7190
drgn/README.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

140 lines
4.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
====
Document PyPI package and installation with pip
2020-01-23 23:14:58 +00:00
.. image:: https://img.shields.io/pypi/v/drgn
:target: https://pypi.org/project/drgn/
:alt: PyPI
README: update Travis CI badge to travis-ci.com Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-12-04 22:38:15 +00:00
.. image:: https://travis-ci.com/osandov/drgn.svg?branch=master
:target: https://travis-ci.com/osandov/drgn
Configure Travis CI
2019-04-11 21:16:48 +01:00
: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
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
Add support for kdump-compressed core dumps with libkdumpfile
2019-08-02 08:00:59 +01:00
:target: https://github.com/psf/black
Format Python code with Black I'm not a fan of 100% of the Black coding style, but I've spent too much time manually formatting Python code, so let's just pull the trigger.
2020-01-14 19:43:58 +00:00
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
.. start-introduction
Tweak README introduction
2020-01-11 00:38:51 +00:00
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:
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"
Tweak README introduction
2020-01-11 00:38:51 +00:00
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
docs: mention tools directory This will need to be fleshed out in the future, but at least mention it to start.
2020-04-18 00:15:35 +01:00
library that can be used to build debugging and introspection tools; see the
official `tools <https://github.com/osandov/drgn/tree/master/tools>`_.
Tweak README introduction
2020-01-11 00:38:51 +00:00
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 was developed for debugging the Linux kernel (as an alternative to the
`crash <http://people.redhat.com/anderson/>`_ utility), but it can also debug
Update README to note that C++ support is in progress
2020-04-04 00:58:30 +01:00
userspace programs written in C. C++ support is in progress.
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
.. end-introduction
Documentation can be found at `drgn.readthedocs.io
<https://drgn.readthedocs.io>`_.
Installation
------------
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
.. start-install-dependencies
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
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
Install dependencies:
README: use code-block instead of highlight PyPI's RST parser apparently doesn't know the highlight directive, which snuck into the README in commit 4de147e478cc ("Add CONTRIBUTING.rst"). Use code-block instead. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-28 07:28:23 +01:00
Arch Linux:
.. code-block:: console
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
$ sudo pacman -S --needed autoconf automake bison bzip2 flex gawk gcc libtool make pkgconf python python-setuptools xz zlib
README: use code-block instead of highlight PyPI's RST parser apparently doesn't know the highlight directive, which snuck into the README in commit 4de147e478cc ("Add CONTRIBUTING.rst"). Use code-block instead. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-28 07:28:23 +01:00
Debian/Ubuntu:
.. code-block:: console
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
$ sudo apt-get install autoconf automake bison flex gawk gcc libbz2-dev liblzma-dev libtool make pkgconf python3 python3-dev python3-setuptools zlib1g-dev
Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship
Python versions which are too old. Python 3.6 or newer must be installed
manually.
README: use code-block instead of highlight PyPI's RST parser apparently doesn't know the highlight directive, which snuck into the README in commit 4de147e478cc ("Add CONTRIBUTING.rst"). Use code-block instead. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-28 07:28:23 +01:00
Fedora:
.. code-block:: console
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
$ sudo dnf install autoconf automake bison bzip2-devel flex gawk gcc libtool make pkgconf python3 python3-devel python3-setuptools xz-devel zlib-devel
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
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
libdrgn: build with bundled elfutils Now that we have the bundled version of elfutils, build it from libdrgn and link to it. We can also get rid of the elfutils version checks from the libdrgn code.
2019-09-04 22:40:47 +01:00
.. end-install-dependencies
README: use code-block instead of highlight PyPI's RST parser apparently doesn't know the highlight directive, which snuck into the README in commit 4de147e478cc ("Add CONTRIBUTING.rst"). Use code-block instead. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-28 07:28:23 +01:00
Then, run:
.. code-block:: console
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
Document PyPI package and installation with pip
2020-01-23 23:14:58 +00:00
$ sudo pip3 install 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
See the `installation documentation
Document PyPI package and installation with pip
2020-01-23 23:14:58 +00:00
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more options.
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
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
Update copyright headers to Facebook and add missing headers drgn was originally my side project, but for awhile now it's also been my work project. Update the copyright headers to reflect this, and add a copyright header to various files that were missing it.
2020-05-15 23:13:02 +01:00
Copyright (c) Facebook, Inc. and its affiliates.
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 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