1####################
2Overview of the Abigail framework
3####################
4
5**ABIGAIL** stands for the Application Binary Interface Generic
6Analysis and Instrumentation Library.
7
8It's a framework which aims at helping developers and software
9distributors to spot some ABI-related issues like interface
10incompatibility in `ELF`_ shared libraries by performing a static
11analysis of the `ELF`_ binaries at hand.
12
13The type of interface incompatibilities that **Abigail** focuses on is
14related to changes on the exported ELF functions and variables
15symbols, as well as layout and size changes of data types of the
16functions and variables exported by shared libraries.
17
18In other words, if the return type of a function exported by a shared
19library changes in an incompatible way from one version of a given
20shared library to another, we want **Abigail** to help people catch
21that.
22
23In more concrete terms, the Abigail framwork provides a shared library
24named **libabigail** which exposes an API to parse a shared library in
25`ELF`_ format (accompanied with its associated debug information in
26`DWARF`_ format) build an internal representation of all the functions
27and variables it exports, along with their types.  **Libabigail** also
28builds an internal representation of the `ELF symbols`_ of these
29functions and variables.  That information about these exported
30functions and variables is roughly what we consider as being the ABI
31of the shared library, at least, in the scope of **Libabigail**.
32
33Aside of this internal representation, **libabigail** provides
34facilities to perform deep comparisons of two ABIs.  That is, it can
35compare the types of two sets of functions or variables and represents
36the result in a way that allows it to emit textual reports about the
37differences.
38
39This allows us to write tools like :doc:`abidiff` that can compare the
40ABI of two shared libraries and represent the result in a meaningful
41enough way to help us spot ABI incompatibilities.  There are several
42:doc:`other tools <libabigail-tools>` that are built using the
43``Abigail`` framwork.
44
45.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
46.. _DWARF: http://www.dwarfstd.org
47.. _ELF symbols: https://blogs.oracle.com/ali/entry/inside_elf_symbol_tables
48