
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 through 9,
Redhat Linux 6.2, 7.3 and Debian GNU/Linux 2.2, 3.0.

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 and 9. 

On Linux only the GLIBC library package of ~20 are versioned.  Prior to
version 2.3, the GLIBC libraries do not contain the public/private
symbol classification, and so the heuristic of leading underscore "_"
is used to identify private symbols except for an "exclude list"
derived from the 2.3 GLIBC source base that abicheck currently carries
along with it (this is a bootstrap measure; in the long run abicheck
will not contain long exclude lists).

Here is an example run on Solaris 9:

# 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.

Here is an example run on Redhat 7.3:

# abicheck /usr/bin/gencat /bin/date
/usr/bin/gencat: PRIVATE: (libc.so.6:GLIBC_PRIVATE) __open_catalog
/bin/date: OK

which at first looks like a problem for /usr/bin/gencat, but remember
the gencat executable is part of the glibc package, so this binding is
actually OK.  A non-GLIBC application directly binding to the
__open_catalog interface would be a potential problem (since
__open_catalog may change incompatibly in a later GLIBC release).

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 copy the script to the
file "abicheck" and set the executable bit.  This file may 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.

