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
82824c0e5f
drgn/README.rst

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

140 lines
4.0 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
Migrate to GitHub Actions Travis CI is no longer offering free open source CI, so migrate to GitHub Actions. The only downside is that GitHub Actions doesn't support nested virtualization, but we can work around that by falling back to slow emulation. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-12-31 10:26:15 +00:00
.. image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
:target: https://github.com/osandov/drgn/actions
:alt: CI Status
Configure Travis CI
2019-04-11 21:16:48 +01: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
.. 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
docs: update links to main branch The master branch was renamed to main. GitHub redirects links to the old branch, but we might as well update them explicitly. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-05-05 01:25:33 +01:00
official `tools <https://github.com/osandov/drgn/tree/main/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
Include full libdrgn distribution in drgn sdist Building drgn from an sdist currently requires autotools and gawk because libdrgn in the sdist is more or less a git checkout. It's more user-friendly to include the autotools output and generated code. Do this by extending the sdist command to include a full libdrgn distribution with `make distdir`. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-03-31 07:02:09 +01:00
$ sudo pacman -S --needed gcc libelf make pkgconf python python-pip python-setuptools
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
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
Include full libdrgn distribution in drgn sdist Building drgn from an sdist currently requires autotools and gawk because libdrgn in the sdist is more or less a git checkout. It's more user-friendly to include the autotools output and generated code. Do this by extending the sdist command to include a full libdrgn distribution with `make distdir`. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-03-31 07:02:09 +01:00
$ sudo apt-get install gcc liblzma-dev libelf-dev libdw-dev make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
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
Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship
libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165 The oldest LTS version of Ubuntu, 16.04, has elfutils 0.165. This version is missing some ELF and DWARF definitions used by drgn. Add copies of elf.h from glibc 2.33 and dwarf.h and elfutils/known-dwarf.h from elfutils 0.183 to get the latest definitions and drop the minimum required version of elfutils further to 0.165. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-03-22 06:05:45 +00:00
Python versions which are too old. Python 3.6 or newer must be installed
manually.
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
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
Include full libdrgn distribution in drgn sdist Building drgn from an sdist currently requires autotools and gawk because libdrgn in the sdist is more or less a git checkout. It's more user-friendly to include the autotools output and generated code. Do this by extending the sdist command to include a full libdrgn distribution with `make distdir`. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-03-31 07:02:09 +01:00
$ sudo dnf install elfutils-devel gcc make pkgconf python3 python3-devel python3-pip python3-setuptools
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