Add README

README.md

@@ -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`.