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/endstone-insider/dwarf2cpp.git
cd dwarf2cpp
pip install .

After installation, run the tool with:

python -m dwarf2cpp

Prebuilt Wheels

For convenience, prebuilt wheels are available from the GitHub Actions pages of this repository. These wheels include the required C++ extension, so you do not need to have LLVM or a compiler toolchain installed locally.

1. Visit the Actions tab on GitHub.

2. Select the latest successful build for your platform (Windows, Linux, or macOS).

3. Download the wheel artifact and install it with:

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

This is the recommended option if you only want to use dwarf2cpp without setting up a compiler or LLVM.

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.

Contributing

Contributions are welcome! If you encounter issues or have suggestions for improvements, please open an issue or a pull request on GitHub.

License

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