dwarf2cpp

Generate C++ headers from DWARF Debugging Information Format (DWARF).

Warning

This tool requires binaries that contain DWARF debug information in order to generate headers. Make sure your input binary includes DWARF debug info, which is often not publicly available in proprietary software.

Installation

Build from Source

Since dwarf2cpp uses pybind11 to access LLVM's DWARF DebugInfo module from Python, you need a working C++ toolchain to build it:

• On Windows: MSVC (Visual Studio Build Tools)
• On Linux: GCC (g++)
• On macOS: Apple Clang (Xcode Command Line Tools)

git clone https://github.com/EndstoneMC/dwarf2cpp.git
cd dwarf2cpp
pip install .

After installation, run the tool with:

python -m dwarf2cpp

Prebuilt Wheels

Prebuilt wheels are attached to each GitHub Release. These include the compiled C++ extension, so you do not need LLVM or a compiler toolchain.

1. Download the .whl for your platform from the latest release

2. Install it:

   pip install dwarf2cpp-<version>-<platform>.whl
   

Usage

Usage: python -m dwarf2cpp [OPTIONS] PATH

Options:
  --base-dir TEXT         Base directory used during compilation.  [required]
  -o, --output-path PATH  Output directory for generated files. Defaults to
                          'out' inside the input file's directory.
  --help                  Show this message and exit.

The PATH argument must point to a binary containing DWARF debug information.

• --base-dir should point to the root directory used during compilation. This helps resolve relative include paths when reconstructing headers.
• --output-path controls where the generated headers are stored. If not specified, the tool creates an out/ folder next to the input file.

Examples

Extract from libminecraftpe.so

python -m dwarf2cpp path/to/libminecraftpe.so --base-dir D:/a/_work/1/s

Extract from bedrock_server (Linux)

python -m dwarf2cpp path/to/bedrock_server --base-dir /mnt/vss/_work/1/s

Motivation / Purpose

Typical use cases include:

• Analysing the internals of proprietary software.
• Supporting the development of plugin frameworks such as Endstone.
• Research on automated source reconstruction from DWARF.

Limitations

• Generated headers may not compile out-of-the-box. Manual adjustments may be required.
• Templates, inline functions, and macros cannot always be reconstructed accurately.
• Only works with binaries compiled with DWARF debug info. Stripped binaries will not work.
• Only trivially tested. It may fail with certain binaries.

Acknowledgements

This project makes use of the following open-source technologies:

• LLVM Project - DWARF DebugInfo parser.
• pybind11 - C++/Python bindings.
• click - Command-line interface framework.

Security / Legal Disclaimer

Important

This tool is provided for research and educational purposes only. It is not affiliated with Mojang or Microsoft.

Warning

Do not redistribute or publish headers generated from proprietary binaries without proper rights. Respect the terms of service and licensing agreements of any binaries you analyse.

Releasing

1. Add changes under ## [Unreleased] in CHANGELOG.md
2. Go to Actions > Release > Run workflow
3. Enter the version (e.g. 0.2.0) and run

The workflow validates the version, updates pyproject.toml and CHANGELOG.md, creates a git tag and GitHub release, builds wheels on all platforms, and attaches them to the release.

Use dry run to preview without making changes.

Contributing

Contributions are welcome. Open an issue or pull request on GitHub.

License

This project is distributed under the MIT License. See the LICENSE file for more details.