DWARF Explorer
==============
A cross-platform GUI utility for visualizing the DWARF
debugging information in executable files, built on top of [pyelftools](https://github.com/eliben/pyelftools) and [filebytes](https://github.com/sashs/filebytes). Runs on Windows, MacOS X, and Linux. Supports parsing the following file types for DWARF data:
- ELF (Linux, Android)
- Mach-O (MacOS X, iOS)
- PE (Windows, Cygwin)
- WASM (aka WebAssembly)
- ar (.a files, Linux/Unix/MacOS X static libraries)
This project came from my desire to see and navigate the DWARF tree of compiled Android and iOS binaries. Seeing the DIEs is easy enough with utilities like `readelf` or `dwarfdump`. However, chasing inter-DIE references back and forth is not straightforward with those.
The utility might be of use for anyone who is building DWARF parsers for one or another reason, especially if their preferred parsing library is `pyelftools`.
Note that regular Windows executables (EXE/DLL files) are PE files but don't, as a rule, contain DWARF information. The Microsoft toolchains (Visual Studio and the like) produce debugging information in Microsoft's own format, Program Database (PDB). There are, though, a couple of toolchains that produce PE files with DWARF debug info in them - notably GCC under Cygwin. DWARF Explorer is compatible with those.
The pyelftools library that dwex is based on supports DWARF versions 2-5, and so does dwex. DWARFv5 support might be unstable. DWARF v1 is supported experimentally, in ELF files only.
There is a known issue with incorrect parsing of DWARF in .o files and static libraries that contain them. See [eliben/pyelftools#564](https://github.com/eliben/pyelftools/issues/564). Mach-O fat binary object files inside static libraries are not supported.
Requirements and Dependencies
------------
- Python 3.6.1+
- PyQt6
- filebytes 0.10.1+
- pyelftools 0.30+
Installation
-------------
If necessary, install [the latest Python](https://www.python.org/downloads/) in the way that's appropriate for your OS. Run `pip install dwex` from the command line, under `sudo` or elevated command line if necessary.
On Windows, if `pip` and/or Python is not in PATH, use `c:\Python39\python -m pip install dwex`, substituting your own path to Python 3.
Alternatively, get the dwex source tree from Github, and run `python setup.py install` in the root folder of the package. In this scenario, you'd have to install the dependencies separately - with `pip install pyqt6 filebytes pyelftools`.
On Linux, sometimes the `python` command defaults to Python 2 while Python 3 is installed side by side. In this case, use `python3` and `pip3`, respectively. Use `python -V` to check.
Once you install it, there will be a `dwex` command. On Windows, there will be a `dwex.exe` in the `Scripts` folder under the Python folder, and also a start menu item "DWARF Explorer". On Linux, there
will be a "DWARF Explorer" in the app menu (tested under GNOME).
In January 2022, the utility was migrated from PyQt5 to PyQt6, and the major version was bumped to 2. That cut off support for Python 3.5. The 1.x version that is compatible with Python 3.5 is still out in the repository, and pip should resolve it.
If it does not, install by running `pip install "dwex<2"`.
Usage
-----
Click Open in the File menu, choose your executable, and eyeball the DWARF tree. Alternatively, drag and drop an executable onto the main window. You can open by dropping a dSYM bundle folder, too.
On the most basic level, the debug information in a compiled file is an array of *compilation units* (CUs). Each CU contains a tree of data items called *Debugging Information Entries* (DIEs). Each DIE has a title called *tag*, and contains a name-value dictionary called *attributes*. Each CU has exactly one root DIE, and the rest of the DIEs are in its subtree.
The UI of DWARF Explorer was meant for eyeballing that data structure:
The left hand tree displays the DIEs, with CU root DIEs on the top level. Expand the tree and click on DIEs to see their attributes. DIE attributes that have a substructure or point at larger data structures are clickable.
DIEs generally correspond to source level entities in the program - variables, functions, classes, members, methods, etc. The DIE tag tells you which one is it. The exact way the compiler builds a DIE tree to describe the program varies between source languages, compiler versions, target platforms and architectures. The official home of the DWARF spec is at [dwarfstd.org](http://dwarfstd.org/), but there's considerable leeway for implementations to improvise upon. On top of that, the DWARF spec contains explicit extension points for compiler vendors to tap into.
DIE attribute values are relatively small scalars - integers, strings, sometimes short byte arrays. However, they sometimes refer at larger data structures. Physically, it's an integer, but logically, it's a pointer to some data elsewhere. Also, DIE attribute values may contain references to other DIEs - for example, a DIE for a variable would contain a reference to a DIE that describes its datatype. DIE attributes that contain references to other DIEs are rendered in blue; the link can be followed by a double-click or a Ctrl+Enter. To come back to the original DIE, use Navigate/Back, the Back mouse button, or an appropriate keyboard shortcut (Alt-Left on Windows and Linux, Ctrl-[ on Mac).
In DWARF, tag and attribute names are prefixed with `DW_TAG_` and `DW_AT_`, respectively. DWARF Explorer elides those by default to reduce visual clutter. Use `View/DWARF prefix` in the menu to bring them back.
Help DWEX get better
--------------------
Compilers and toolchains out there are a diverse bunch, compiled binaries even more so. **If you see DWARF Explorer crash, or misbehave, or complain about parsing errors - please don't hesitate to submit tickets at [github.com/sevaa/dwex/issues](https://github.com/sevaa/dwex/issues).** Ideally, attach the offending binary.
Disclaimer
----------
This project is unrelated to [ragundo/DwarfExplorer](https://github.com/ragundo/DwarfExplorer). That one deals with a different kind of dwarves. Although, interestingly enough, they also use the Qt library for their GUI.
Prior art
---------
There is also a GUI DWARF visualizer at [simark/dwarftree](https://github.com/simark/dwarftree). Also based on pyelftools,
with gtk based UI. It's been inactive since 2015. I didn't know about it when I started.
Pairs well with
---------------
For a free general purpose GUI ELF file visualizer, see [horsicq/XELFViewer](https://github.com/horsicq/XELFViewer).
Raw data
{
"_id": null,
"home_page": "https://github.com/sevaa/dwex/",
"name": "dwex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.1",
"maintainer_email": null,
"keywords": "dwarf, debug, debugging, symbols, viewer, view, browser, browse, tree",
"author": "Seva Alekseyev",
"author_email": "sevaa@sprynet.com",
"download_url": "https://files.pythonhosted.org/packages/d0/8a/8dc61cb73ab06a811af4b7925c27730939fba6aeb634130567e453ab7b00/dwex-4.23.tar.gz",
"platform": "any",
"description": "DWARF Explorer\r\n==============\r\n\r\nA cross-platform GUI utility for visualizing the DWARF\r\ndebugging information in executable files, built on top of [pyelftools](https://github.com/eliben/pyelftools) and [filebytes](https://github.com/sashs/filebytes). Runs on Windows, MacOS X, and Linux. Supports parsing the following file types for DWARF data:\r\n - ELF (Linux, Android)\r\n - Mach-O (MacOS X, iOS)\r\n - PE (Windows, Cygwin)\r\n - WASM (aka WebAssembly)\r\n - ar (.a files, Linux/Unix/MacOS X static libraries)\r\n\r\nThis project came from my desire to see and navigate the DWARF tree of compiled Android and iOS binaries. Seeing the DIEs is easy enough with utilities like `readelf` or `dwarfdump`. However, chasing inter-DIE references back and forth is not straightforward with those.\r\n\r\nThe utility might be of use for anyone who is building DWARF parsers for one or another reason, especially if their preferred parsing library is `pyelftools`.\r\n\r\nNote that regular Windows executables (EXE/DLL files) are PE files but don't, as a rule, contain DWARF information. The Microsoft toolchains (Visual Studio and the like) produce debugging information in Microsoft's own format, Program Database (PDB). There are, though, a couple of toolchains that produce PE files with DWARF debug info in them - notably GCC under Cygwin. DWARF Explorer is compatible with those.\r\n\r\nThe pyelftools library that dwex is based on supports DWARF versions 2-5, and so does dwex. DWARFv5 support might be unstable. DWARF v1 is supported experimentally, in ELF files only.\r\n\r\nThere is a known issue with incorrect parsing of DWARF in .o files and static libraries that contain them. See [eliben/pyelftools#564](https://github.com/eliben/pyelftools/issues/564). Mach-O fat binary object files inside static libraries are not supported.\r\n\r\nRequirements and Dependencies\r\n------------\r\n - Python 3.6.1+\r\n - PyQt6\r\n - filebytes 0.10.1+\r\n - pyelftools 0.30+\r\n\r\nInstallation\r\n-------------\r\n\r\nIf necessary, install [the latest Python](https://www.python.org/downloads/) in the way that's appropriate for your OS. Run `pip install dwex` from the command line, under `sudo` or elevated command line if necessary.\r\n\r\nOn Windows, if `pip` and/or Python is not in PATH, use `c:\\Python39\\python -m pip install dwex`, substituting your own path to Python 3.\r\n\r\nAlternatively, get the dwex source tree from Github, and run `python setup.py install` in the root folder of the package. In this scenario, you'd have to install the dependencies separately - with `pip install pyqt6 filebytes pyelftools`.\r\n\r\nOn Linux, sometimes the `python` command defaults to Python 2 while Python 3 is installed side by side. In this case, use `python3` and `pip3`, respectively. Use `python -V` to check.\r\n\r\nOnce you install it, there will be a `dwex` command. On Windows, there will be a `dwex.exe` in the `Scripts` folder under the Python folder, and also a start menu item \"DWARF Explorer\". On Linux, there\r\nwill be a \"DWARF Explorer\" in the app menu (tested under GNOME).\r\n\r\nIn January 2022, the utility was migrated from PyQt5 to PyQt6, and the major version was bumped to 2. That cut off support for Python 3.5. The 1.x version that is compatible with Python 3.5 is still out in the repository, and pip should resolve it. \r\nIf it does not, install by running `pip install \"dwex<2\"`.\r\n\r\nUsage\r\n-----\r\n\r\nClick Open in the File menu, choose your executable, and eyeball the DWARF tree. Alternatively, drag and drop an executable onto the main window. You can open by dropping a dSYM bundle folder, too.\r\n\r\nOn the most basic level, the debug information in a compiled file is an array of *compilation units* (CUs). Each CU contains a tree of data items called *Debugging Information Entries* (DIEs). Each DIE has a title called *tag*, and contains a name-value dictionary called *attributes*. Each CU has exactly one root DIE, and the rest of the DIEs are in its subtree.\r\n\r\nThe UI of DWARF Explorer was meant for eyeballing that data structure:\r\n\r\n\r\n\r\nThe left hand tree displays the DIEs, with CU root DIEs on the top level. Expand the tree and click on DIEs to see their attributes. DIE attributes that have a substructure or point at larger data structures are clickable.\r\n\r\nDIEs generally correspond to source level entities in the program - variables, functions, classes, members, methods, etc. The DIE tag tells you which one is it. The exact way the compiler builds a DIE tree to describe the program varies between source languages, compiler versions, target platforms and architectures. The official home of the DWARF spec is at [dwarfstd.org](http://dwarfstd.org/), but there's considerable leeway for implementations to improvise upon. On top of that, the DWARF spec contains explicit extension points for compiler vendors to tap into.\r\n\r\nDIE attribute values are relatively small scalars - integers, strings, sometimes short byte arrays. However, they sometimes refer at larger data structures. Physically, it's an integer, but logically, it's a pointer to some data elsewhere. Also, DIE attribute values may contain references to other DIEs - for example, a DIE for a variable would contain a reference to a DIE that describes its datatype. DIE attributes that contain references to other DIEs are rendered in blue; the link can be followed by a double-click or a Ctrl+Enter. To come back to the original DIE, use Navigate/Back, the Back mouse button, or an appropriate keyboard shortcut (Alt-Left on Windows and Linux, Ctrl-[ on Mac).\r\n\r\nIn DWARF, tag and attribute names are prefixed with `DW_TAG_` and `DW_AT_`, respectively. DWARF Explorer elides those by default to reduce visual clutter. Use `View/DWARF prefix` in the menu to bring them back.\r\n\r\nHelp DWEX get better\r\n--------------------\r\n\r\nCompilers and toolchains out there are a diverse bunch, compiled binaries even more so. **If you see DWARF Explorer crash, or misbehave, or complain about parsing errors - please don't hesitate to submit tickets at [github.com/sevaa/dwex/issues](https://github.com/sevaa/dwex/issues).** Ideally, attach the offending binary.\r\n\r\n\r\nDisclaimer\r\n----------\r\n\r\nThis project is unrelated to [ragundo/DwarfExplorer](https://github.com/ragundo/DwarfExplorer). That one deals with a different kind of dwarves. Although, interestingly enough, they also use the Qt library for their GUI.\r\n\r\nPrior art\r\n---------\r\n\r\nThere is also a GUI DWARF visualizer at [simark/dwarftree](https://github.com/simark/dwarftree). Also based on pyelftools,\r\nwith gtk based UI. It's been inactive since 2015. I didn't know about it when I started.\r\n\r\nPairs well with\r\n---------------\r\n\r\nFor a free general purpose GUI ELF file visualizer, see [horsicq/XELFViewer](https://github.com/horsicq/XELFViewer).\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "GUI viewer for DWARF debug information",
"version": "4.23",
"project_urls": {
"Homepage": "https://github.com/sevaa/dwex/"
},
"split_keywords": [
"dwarf",
" debug",
" debugging",
" symbols",
" viewer",
" view",
" browser",
" browse",
" tree"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d08a8dc61cb73ab06a811af4b7925c27730939fba6aeb634130567e453ab7b00",
"md5": "1932f524088e5113c952b2fe9c0ec180",
"sha256": "c734a2910f5e7df833a118c2f262bf066484b7d10bac49a55e72e04a4260d18a"
},
"downloads": -1,
"filename": "dwex-4.23.tar.gz",
"has_sig": false,
"md5_digest": "1932f524088e5113c952b2fe9c0ec180",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.1",
"size": 73127,
"upload_time": "2024-10-01T16:35:56",
"upload_time_iso_8601": "2024-10-01T16:35:56.132713Z",
"url": "https://files.pythonhosted.org/packages/d0/8a/8dc61cb73ab06a811af4b7925c27730939fba6aeb634130567e453ab7b00/dwex-4.23.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-01 16:35:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sevaa",
"github_project": "dwex",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dwex"
}
JSON
