README.rst

   1 ==========
   2 pyelftools
   3 ==========
   4
   5 .. image:: https://github.com/eliben/pyelftools/workflows/pyelftools-tests/badge.svg
   6   :align: center
   7   :target: https://github.com/eliben/pyelftools/actions
   8
   9 **pyelftools** is a pure-Python library for parsing and analyzing ELF files
  10 and DWARF debugging information. See the
  11 `User's guide <https://github.com/eliben/pyelftools/wiki/User's-guide>`_
  12 for more details.
  13
  14 Pre-requisites
  15 --------------
  16
  17 As a user of **pyelftools**, one only needs Python 3 to run. While there is no
  18 reason for the library to not work on earlier versions of Python 3, our CI
  19 tests are based on the officual
  20 `Status of Python versions <https://devguide.python.org/versions/>`__.
  21
  22 Installing
  23 ----------
  24
  25 **pyelftools** can be installed from PyPI (Python package index)::
  26
  27     > pip install pyelftools
  28
  29 Alternatively, you can download the source distribution for the most recent and
  30 historic versions from the *Downloads* tab on the `pyelftools project page
  31 <https://github.com/eliben/pyelftools>`_ (by going to *Tags*). Then, you can
  32 install from source, as usual::
  33
  34     > python setup.py install
  35
  36 Since **pyelftools** is a work in progress, it's recommended to have the most
  37 recent version of the code. This can be done by downloading the `master zip
  38 file <https://github.com/eliben/pyelftools/archive/master.zip>`_ or just
  39 cloning the Git repository.
  40
  41 Since **pyelftools** has no external dependencies, it's also easy to use it
  42 without installing, by locally adjusting ``PYTHONPATH``.
  43
  44 How to use it?
  45 --------------
  46
  47 **pyelftools** is a regular Python library: you import and invoke it from your
  48 own code. For a detailed usage guide and links to examples, please consult the
  49 `user's guide <https://github.com/eliben/pyelftools/wiki/User's-guide>`_.
  50
  51 Contributing
  52 ------------
  53
  54 See the `Hacking Guide <https://github.com/eliben/pyelftools/wiki/Hacking-guide>`__.
  55
  56 License
  57 -------
  58
  59 **pyelftools** is open source software. Its code is in the public domain. See
  60 the ``LICENSE`` file for more details.