pylibdebuginfod


Namepylibdebuginfod JSON
Version 0.2 PyPI version JSON
download
home_pagehttps://github.com/rupran/pylibdebuginfod
SummaryPython bindings for libdebuginfod
upload_time2021-04-08 11:33:53
maintainer
docs_urlNone
authorAndreas Ziegler
requires_python
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <!--
SPDX-FileCopyrightText: 2021 Andreas Ziegler <andreas.ziegler@fau.de>

SPDX-License-Identifier: MIT
-->

# pylibdebuginfod
Python bindings for [libdebuginfod](https://sourceware.org/elfutils/Debuginfod.html).

This library provides a Python interface for the functions in the `libdebuginfod.so` library from [elfutils](https://sourceware.org/elfutils/). The `debuginfod` cilent/server infrastructure allows automatic distribution of debugging information (ELF symbol tables, DWARF and even source code) for binaries installed on the current system.

The debuginfod server is queried using a SHA-1 hash (the build ID) which is contained in a section `.note.gnu.build-id` in the stripped binary file.

# Prerequisites
The minimum Python version required is 3.5.

The bindings require an installation of `libdebuginfod.so` and the [pyelftools](https://github.com/eliben/pyelftools) library.

# Usage
This example was run under Debian Buster with the `libdebuginfod1`, `libelf1` and `libdw1` packages from `buster-backports`.

In order to make `libdebuginfod.so` aware of the servers to query, you can set the `DEBUGINFOD_URLS` environment variable. For example, to query the Debian server, you can run:

```bash
$ export DEBUGINFOD_URLS="https://debuginfod.debian.net"
```

If the `DEBUGINFOD_URLS` environment variable is not set, it is temporarily set to the `elfutils` server (`https://debuginfod.elfutils.org/`) which federates to all trusted servers (listed on the [elfutils](https://sourceware.org/elfutils/Debuginfod.html) website).

The other environment variables listed in the [manual page](https://manpages.debian.org/experimental/libdebuginfod-dev/debuginfod_find_debuginfo.3.en.html#ENVIRONMENT_VARIABLES) are also respected as they are handled by `libdebuginfod.so` itself.

You can extract the build ID information using the `readelf` tool like this:

```bash
$ readelf -n /lib/x86_64-linux-gnu/libc-2.28.so

Displaying notes found in: .note.gnu.build-id
  Owner                 Data size	Description
  GNU                  0x00000014	NT_GNU_BUILD_ID (unique build ID bitstring)
    Build ID: 18b9a9a8c523e5cfe5b5d946d605d09242f09798
```

With the prerequisites in place, you can use the `DebugInfoD` class as follows:

```python
  >>> from libdebuginfod import DebugInfoD
  >>> session = DebugInfoD()
  >>> session.begin() # optional, is also called from __init__ at the moment.
  >>> fd, path = session.find_debuginfo('18b9a9a8c523e5cfe5b5d946d605d09242f09798')
  >>> print((fd, path))
  (3, b'/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo')
  >>> session.end()
```

In a more pythonic way, `DebugInfoD` can also be used as a context manager where `begin()` and `end()` are called automatically.

```python
  >>> from libdebuginfod import DebugInfoD
  >>> with DebugInfoD() as d:
  ...     fd, path = d.find_debuginfo('18b9a9a8c523e5cfe5b5d946d605d09242f09798')
  ...     print((fd, path))
  ...
  (3, b'/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo')
```

The [scripts/debuginfod-find.py](https://github.com/rupran/pylibdebuginfod/blob/main/scripts/debuginfod-find.py) script supports three commands (`debuginfo`, `executable` and `source`) and accepts either a build ID or a path to a target file. If the filename matches the pattern `[0-9a-f]+`, please provide the path (e.g., `./e3`) to avoid misinterpretation of the input as a build ID. If the command is `source`, you need to provide the path or build ID as the first input parameter and an absolute path to the target source file (as present in the DWARF information) as the second input parameter.

Example usage:

```bash
$ ./scripts/debuginfod-find.py debuginfo /lib/x86_64-linux-gnu/libc-2.28.so
/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo
```

# License(s)
The bindings themselves are released under the [MIT](https://opensource.org/licenses/MIT) license. As the script at [scripts/debuginfod-find.py](https://github.com/rupran/pylibdebuginfod/blob/main/scripts/debuginfod-find.py) is a reimplementation of the `debuginfod-find` application from [elfutils](https://sourceware.org/elfutils/Debuginfod.html) (which is licensed under the GPLv3+ license), the script is also released under the [GPLv3+](https://www.gnu.org/licenses/gpl-3.0.en.html) license and not included in the packaged release of the bindings.



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/rupran/pylibdebuginfod",
    "name": "pylibdebuginfod",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Andreas Ziegler",
    "author_email": "andreas.ziegler@fau.de",
    "download_url": "https://files.pythonhosted.org/packages/5c/7f/946a0f6c7abbaae49a9b21fdc355225e4c1bf2cf047c5c8024fbefc364d2/pylibdebuginfod-0.2.tar.gz",
    "platform": "",
    "description": "<!--\nSPDX-FileCopyrightText: 2021 Andreas Ziegler <andreas.ziegler@fau.de>\n\nSPDX-License-Identifier: MIT\n-->\n\n# pylibdebuginfod\nPython bindings for [libdebuginfod](https://sourceware.org/elfutils/Debuginfod.html).\n\nThis library provides a Python interface for the functions in the `libdebuginfod.so` library from [elfutils](https://sourceware.org/elfutils/). The `debuginfod` cilent/server infrastructure allows automatic distribution of debugging information (ELF symbol tables, DWARF and even source code) for binaries installed on the current system.\n\nThe debuginfod server is queried using a SHA-1 hash (the build ID) which is contained in a section `.note.gnu.build-id` in the stripped binary file.\n\n# Prerequisites\nThe minimum Python version required is 3.5.\n\nThe bindings require an installation of `libdebuginfod.so` and the [pyelftools](https://github.com/eliben/pyelftools) library.\n\n# Usage\nThis example was run under Debian Buster with the `libdebuginfod1`, `libelf1` and `libdw1` packages from `buster-backports`.\n\nIn order to make `libdebuginfod.so` aware of the servers to query, you can set the `DEBUGINFOD_URLS` environment variable. For example, to query the Debian server, you can run:\n\n```bash\n$ export DEBUGINFOD_URLS=\"https://debuginfod.debian.net\"\n```\n\nIf the `DEBUGINFOD_URLS` environment variable is not set, it is temporarily set to the `elfutils` server (`https://debuginfod.elfutils.org/`) which federates to all trusted servers (listed on the [elfutils](https://sourceware.org/elfutils/Debuginfod.html) website).\n\nThe other environment variables listed in the [manual page](https://manpages.debian.org/experimental/libdebuginfod-dev/debuginfod_find_debuginfo.3.en.html#ENVIRONMENT_VARIABLES) are also respected as they are handled by `libdebuginfod.so` itself.\n\nYou can extract the build ID information using the `readelf` tool like this:\n\n```bash\n$ readelf -n /lib/x86_64-linux-gnu/libc-2.28.so\n\nDisplaying notes found in: .note.gnu.build-id\n  Owner                 Data size\tDescription\n  GNU                  0x00000014\tNT_GNU_BUILD_ID (unique build ID bitstring)\n    Build ID: 18b9a9a8c523e5cfe5b5d946d605d09242f09798\n```\n\nWith the prerequisites in place, you can use the `DebugInfoD` class as follows:\n\n```python\n  >>> from libdebuginfod import DebugInfoD\n  >>> session = DebugInfoD()\n  >>> session.begin() # optional, is also called from __init__ at the moment.\n  >>> fd, path = session.find_debuginfo('18b9a9a8c523e5cfe5b5d946d605d09242f09798')\n  >>> print((fd, path))\n  (3, b'/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo')\n  >>> session.end()\n```\n\nIn a more pythonic way, `DebugInfoD` can also be used as a context manager where `begin()` and `end()` are called automatically.\n\n```python\n  >>> from libdebuginfod import DebugInfoD\n  >>> with DebugInfoD() as d:\n  ...     fd, path = d.find_debuginfo('18b9a9a8c523e5cfe5b5d946d605d09242f09798')\n  ...     print((fd, path))\n  ...\n  (3, b'/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo')\n```\n\nThe [scripts/debuginfod-find.py](https://github.com/rupran/pylibdebuginfod/blob/main/scripts/debuginfod-find.py) script supports three commands (`debuginfo`, `executable` and `source`) and accepts either a build ID or a path to a target file. If the filename matches the pattern `[0-9a-f]+`, please provide the path (e.g., `./e3`) to avoid misinterpretation of the input as a build ID. If the command is `source`, you need to provide the path or build ID as the first input parameter and an absolute path to the target source file (as present in the DWARF information) as the second input parameter.\n\nExample usage:\n\n```bash\n$ ./scripts/debuginfod-find.py debuginfo /lib/x86_64-linux-gnu/libc-2.28.so\n/home/user/.cache/debuginfod_client/18b9a9a8c523e5cfe5b5d946d605d09242f09798/debuginfo\n```\n\n# License(s)\nThe bindings themselves are released under the [MIT](https://opensource.org/licenses/MIT) license. As the script at [scripts/debuginfod-find.py](https://github.com/rupran/pylibdebuginfod/blob/main/scripts/debuginfod-find.py) is a reimplementation of the `debuginfod-find` application from [elfutils](https://sourceware.org/elfutils/Debuginfod.html) (which is licensed under the GPLv3+ license), the script is also released under the [GPLv3+](https://www.gnu.org/licenses/gpl-3.0.en.html) license and not included in the packaged release of the bindings.\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python bindings for libdebuginfod",
    "version": "0.2",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "b833b2fb5104f2aac57f7072e561007b",
                "sha256": "8a909cdf5e0ccb3d819893a30f4ff72cfa8bbeef8090102de42cecd014309ec4"
            },
            "downloads": -1,
            "filename": "pylibdebuginfod-0.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b833b2fb5104f2aac57f7072e561007b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 8221,
            "upload_time": "2021-04-08T11:33:52",
            "upload_time_iso_8601": "2021-04-08T11:33:52.481966Z",
            "url": "https://files.pythonhosted.org/packages/55/2f/2181507003d93b1a649dcd64663e8be39a1d2f90338e2958627bbb7ad87a/pylibdebuginfod-0.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "d2e8f6d89fa7299260ca26032801a58d",
                "sha256": "ec37d6d8ae155d60c1845b56647acfa86a757df4eae76c919dec418cd21c9e4c"
            },
            "downloads": -1,
            "filename": "pylibdebuginfod-0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d2e8f6d89fa7299260ca26032801a58d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 6715,
            "upload_time": "2021-04-08T11:33:53",
            "upload_time_iso_8601": "2021-04-08T11:33:53.568565Z",
            "url": "https://files.pythonhosted.org/packages/5c/7f/946a0f6c7abbaae49a9b21fdc355225e4c1bf2cf047c5c8024fbefc364d2/pylibdebuginfod-0.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-04-08 11:33:53",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "rupran",
    "error": "Could not fetch GitHub repository",
    "lcname": "pylibdebuginfod"
}
        
Elapsed time: 0.42854s