DWARF Compilation
			  =================

This package aims to be as standalone as possible, and include
everything that is needed to compile DWARF unwind table into x86-64
assembly, then use the generated binaries for unwinding using a
patched version of libunwind called libunwind-eh_elf.

This bundle attempts to be easy to setup, and it will install its
dependencies locally inside this directory.  In some cases,
e.g. building larger projects on top of this code, performing a
system-wide install might be preferable.


		  Component 1: Dwarf Unwind Assembly
		  ==================================

A compiler from DWARF unwinding data to native x86_64 binaries.

This repository also contains various experiments, tools, benchmarking
scripts, stats scripts, etc. to work on this compiler.

Dependencies
------------

As of now, this project relies on the following libraries:

-   libelf
-   libdwarf
-   libdwarfpp, itself depending on
    -   libcxxfileno
    -   libsrk31cxx

These libraries are expected to be installed somewhere your compiler
can find them. If you are using Archlinux, you can check these
PKGBUILDs.

Scripts and directories
-----------------------

- ./generate_eh_elf.py: generate .eh_elf.so files for a binary (and
    its dependencies if required)

- ./compare_sizes.py: compare the sizes of the .eh_frame of a binary
    (and its dependencies) with the sizes of the .text of the
    generated ELFs.

- ./extract_pc.py: extracts a list of valid program counters of an ELF
    and produce a file as read by dwarf-assembly, deprecated.

- benching: all about benchmarking

- env: environment variables manager to ease the use of various
    eh_elfs in parallel, for experiments.

- shared: code shared between various subprojects

- src: the compiler code itself

- stack_walker: a primitive stack walker using eh_elfs

- stack_walker_libunwind: a primitive stack walker using vanilla
    libunwind

- stats: a statistics gathering module

- tests: some tests regarding eh_elfs, deprecated.

How to use
----------

To compile eh_elfs for a given ELF file, say foo.bin, it is
recommended to use generate_eh_elf.py. Help can be obtained with
--help. A standard command is

  $ ./generate_eh_elf.py --deps --enable-deref-arg --global-switch -o eh_elfs foo.bin

This will compile foo.bin and all the shared objects it relies on into
eh_elfs, in the directory ./eh_elfs, using a dereferencing argument
(which is necessary for perf-eh_elfs).

Generate the intermediary C file
--------------------------------

If you're curious about the intermediary C file generated for a given
ELF file foo.bin, you must call dwarf-assembly directly. A parameter
--help can be passed; a standard command is

  $ ./dwarf-assembly --global-switch --enable-deref-arg foo.bin

Beware, this will generate the C code on the standard output.


		    Component 2: libunwind-eh_elf
		    =============================

The libunwind-eh_elf directory contains a modified distributin of
libunwind that supports the precompiled eh_elf sections.  Please refer
to the documentation in the libunwid-eh_elf directory.