Add README

This commit is contained in:
Théophile Bastian 2018-08-17 19:55:37 +02:00
commit fc21036aec

80
README.md Normal file
View file

@ -0,0 +1,80 @@
# General considerations about this internship
The goal of this internship was to investigate and implement a compiler from
DWARF unwinding data to native assembly code. The various repositories listed
on [the git summary page](https://git.tobast.fr/m2-internship) are the various
components of the project, plus some off-topic (at various degrees) code I
wrote during the internship.
Each repository includes a `README.md` file with detailed information about
what it does, how it is supposed to be used, etc.
## List of repositories
* `abstract`: this repository, provides a description/summary of the projects,
and gives insights of how they interact with each other.
* `report`: the internship report repository, including `.tex` files, images,
source codes, etc.
* `libunwind-eh_elf`: a fork of [libunwind](http://www.nongnu.org/libunwind/)
working with eh\_elfs, with only a slight interface change (an additional
parameter to an initialisation function).
* `dwarf-assembly`: the compiler itself, along with benchmarking, stats and
various helper scripts.
* `dwarf-semantics`: a subset of `report` that describes the semantics of the
compiled DWARF. **Outdated**.
* `pkgbuilds`: contains `PKGBUILD` files for various uncommon libraries on
which `dwarf-assembly` depends. A `PKGBUILD` is a package building script
made for Archlinux.
* `perf-eh_elf`: a fork of
[perf](https://perf.wiki.kernel.org/index.php/Main_Page) working with
`libunwind-eh_elf`. Since `perf` is originally developed within the Linux
kernel source tree, this repository was rerooted to only include
`tools/perf`. However, to be compiled, `perf` needs the other files from the
Linux source tree. See this repository's `README.md` for more details.
* `dwarfinterpret`: a first project, providing features close to `libunwind`.
This was made as an exercise with DWARF, to better understand how it works,
at the beginning of the internship.
* `frame-machine`: a fork of [Stephen Kell](https://www.cl.cam.ac.uk/~srk31/)'s
`frame-machine.c`. This was also made to better understand DWARF, and is a
C++ template-based unwinder.
* `libdwarfpp-tests`: some more training codes regarding DWARF. These codes use
`libdwarfpp`, a library by [Stephen Kell](https://www.cl.cam.ac.uk/~srk31/)
that acts as a C++ wrapper for
[libdwarf](https://sourceforge.net/projects/libdwarf/).
* `eh_frame_check_setup`: a collection of scripts to automate and ease the use
of
[`eh_frame_check`](https://github.com/francesco-zappa-nardelli/eh_frame_check),
a tool developed by
[Francesco Zappa-Nardelli](https://www.di.ens.fr/~zappa/), my advisor, to
check the consistency and correctness of the DWARF unwinding data of
arbitrary binaries. **Outdated**, as the up-to-date version can be found in
the above-mentioned Github repository.
## Steps to setup the DWARF to assembly compiler
* If you use Archlinux, install the three `PKGBUILD`s from `pkgbuilds`. If not,
install the three libraries `libsrk31cxx`, `libcxxfileno` and `libdwarfpp`,
all three by Stephen Kell. This can be tricky.
* Clone the repository `dwarf-assembly` and run `make`. If the libraries from
the previous step are installed and available in standard directories, this
step should work without any particular problem.
* From now on, you can compile `ELF`s to `eh_elf`. Follow the instructions from
`dwarf-assembly`'s `README.md`.
* To use those `eh_elf`s, clone and build `libunwind-eh_elf`. Follow the
instructions from the `README.md`.
* To also use `perf`, clone and build `perf-eh_elf` and follow the instructions
from the `README.md`.