####################
Overview of the Abigail framework
####################

**ABIGAIL** stands for the Application Binary Interface Generic
Analysis and Instrumentation Library.

It's a framework which aims at helping developers and software
distributors to spot some ABI-related issues like interface
incompatibility in `ELF`_ shared libraries by performing a static
analysis of the `ELF`_ binaries at hand.

The type of interface incompatibilities that **Abigail** focuses on is
related to changes on the exported ELF functions and variables
symbols, as well as layout and size changes of data types of the
functions and variables exported by shared libraries.

In other words, if the return type of a function exported by a shared
library changes in an incompatible way from one version of a given
shared library to another, we want **Abigail** to help people catch
that.

In more concrete terms, the Abigail framwork provides a shared library
named **libabigail** which exposes an API to parse a shared library in
`ELF`_ format (accompanied with its associated debug information in
`DWARF`_ format) build an internal representation of all the functions
and variables it exports, along with their types.  **Libabigail** also
builds an internal representation of the `ELF symbols`_ of these
functions and variables.  That information about these exported
functions and variables is roughly what we consider as being the ABI
of the shared library, at least, in the scope of **Libabigail**.

Aside of this internal representation, **libabigail** provides
facilities to perform deep comparisons of two ABIs.  That is, it can
compare the types of two sets of functions or variables and represents
the result in a way that allows it to emit textual reports about the
differences.

This allows us to write tools like :doc:`abidiff` that can compare the
ABI of two shared libraries and represent the result in a meaningful
enough way to help us spot ABI incompatibilities.  There are several
:doc:`other tools <libabigail-tools>` that are built using the
``Abigail`` framwork.

.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
.. _DWARF: http://www.dwarfstd.org
.. _ELF symbols: https://blogs.oracle.com/ali/entry/inside_elf_symbol_tables