This is the README for the ABI checking tool "abicheck". For background
information on library versioning, public/private classification, and
other useful information please read the INTRO file that accompanies
the source.

abicheck is a tool that checks application binary executables and
shared libraries for conformance to the (or an) ABI (Application Binary
Interface). It requires the libraries making up the ABI to have the
library versioning public/private symbol information recorded in the them.
See the INTRO and references (especially the "Solaris Linker and Libraries
Guide" at http://docs.sun.com/ab2/coll.45.13).

With that public/private symbol information in place in the libraries,
abicheck performs the following steps:

     1) runs ldd(1) with the -r switch and environment variable
	LD_DEBUG=files,bindings to extract all of the symbol binding
	information for each binary to be checked.

     2) The ABI symbols directly called by a binary are checked if they
	are in a library's private symbol set (that is, the set of library
	package internal symbols). If so, a warning in printed out.

     3) Static linking of system library archives are checked for using
	objdump(1) or elfdump(1) to extract the list of .text symbols
	from the application binary and then applying heuristics to detect
	static linking of basic system libraries (libc, libsocket, libnsl)

The details of 2) depend on the system (on Linux the ldd(1) output
contains the information, while on Solaris pvs(1) is consulted to link
symbols to version set names)

abicheck currently works on Linux (GLIBC package 2.1 or higher), and
Solaris (2.6 or higher). It has been tested on Solaris 2.6-8, Redhat
Linux 6.2 and Debian GNU/Linux 2.2

The more libraries that have the public/private symbol information
in place the more useful is abicheck in checking conformance. Many of
the system libraries in Solaris 2.6 are versioned that way, and nearly
all are in Solaris 8. On Linux only the GLIBC library package of ~20
are versioned. The GLIBC libraries do not contain the public/private
symbol classification, and so the heuristic of leading underscore "_"
is used to identify private symbols.

Here is an example run on Solaris:

# abicheck ./reader ./date
./reader: PRIVATE: (libc.so.1:SUNWprivate_1.1) _select
./date: OK

The application binary "reader" calls the private symbol "_select"
in libc.so.1 and a warning is printed out. The application "date"
makes no private calls and so is OK. See the INTRO file for more 
information on the what is being checked.

Running "abicheck -h" provides additional help and information about
the format of the output and command line options.

Regarding building and installation, there is not much to say since it is
a simple stand-alone script. "make" will just set the executable bit, and
the file "abicheck" can be installed anywhere. The user's PATH must be set
to find perl (usually /usr/bin/perl). abicheck is meant as a demonstration
tool of an ABI conformance using versioning information in ABI shared
libraries, and additional heuristic checks for binary stability.