NAME
icheck - C interface ABI/API checker
SYNOPSIS
icheck --canonify [[--baseline FILE] ...] [OPTIONS] [GCC_OPTIONS] [--]
files
icheck --compare [OPTIONS] old_file new_file
DESCRIPTION
A tool for statically checking C interfaces for API and ABI changes.
All changes to type declarations that can cause ABI changes should be
detected, along with most API changes.
icheck is intended for use with libraries, as a method of preventing
ABI drift.
COMMANDS
Reduce a set of source files to a canonical interface file with
--canonify, then compare two such interface files with --compare. If
there are interface changes between them, icheck will describe the
changes and fail.
--canonify [[--baseline FILE] ...] [OPTIONS] [GCC_OPTIONS] [--] files
Canonify the source code files (typically .h headers) to be
compared later with --compare. Usually used with the -o option
to save the summary to a file.
--compare [OPTIONS] old_file new_file
Reads two canonical interface files generated with --canonify
and compares the structure of the source code to the changes in
the Application Public Interface (the developer interface or
API) and the Application Binary Interface (ABI) used to link
against other programs or libraries.
OPTIONS
ICHECK OPTIONS
-o, --output FILE
Emit output to FILE, rather than stdout.
--debug N
Dump debugging information.
--only THING
Only process the given THING.
--skip-from FILE
Skip unnecessary things from FILE.
--skip-from-re regexp
Skip unnecessary things from files matching the regular
expression.
--only-from FILE
Only take things from FILE.
--only-from-re regexp
Only take things from files matching the regular expression.
GCC_OPTIONS
GCC_OPTIONS are passed through to gcc -E
HELP OPTIONS
--help
Display the help synopsis for icheck.
EXAMPLES
All source files are preprocessed with gcc, so canonify needs the same
include information as the source code - follow the syntax from the
Makefile to include -I options to cpp (or gcc) so that all necessary
headers can be located. icheck will abort if any required headers
cannot be found. The source must be compileable; icheck cannot process
files which cannot be directly compiled. If a header is missing
#include statements, or otherwise requires being used in a special way,
then it cannot be directly processed with icheck. Instead, write a stub
C file that sets things up appropriately and then #includes the header.
icheck --canonify -o ~/icheck/oldversion -I/usr/include/foo-2.0
/usr/src/bar/src/foobar.h
Prepare a text summary of the foobar.h file and all files it includes.
The summary is written out to ~/icheck/oldversion. Repeat for
/usr/src/bar1/src/foobar.h - the same file in the newer source
directory, outputting to a new file, e.g. ~/icheck/newversion.
icheck --compare -o ~/icheck/results.txt ~/icheck/oldversion
~/icheck/newversion
Writes the report of the comparison of the two summary files. The
report indicates all the changes in the ABI and/or API found during the
comparison.
icheck --canonify -o debian/icheck.canonical -Idebian/foo-
dev/usr/include debian/foo-dev/usr/include/foobar.h
icheck --compare debian/icheck.manifest debian/icheck.canonical
These two statements, included in a debian/rules file, will cause the
package build to fail if the API or ABI has changed in unexpected ways,
where icheck.manifest is a copy of the expected interface, included in
the package.
Note that the arguments to --compare are themselves valid C files which
are preprocessed, so icheck.manifest can contain C preprocessor logic.
This can be useful when a package exports different interfaces
depending on the host architecture. In this case, you can’t replace it
with a new copy of icheck.canonical when the interface changes and you
need to update the manifest. Rather than updating the entire manifest
by hand, put the hand-written interface descriptions in one file
(icheck.static-manifest) and then use:
icheck --canonify --baseline debian/icheck.static-manifest -o
debian/icheck.dynamic-manifest
Lastly, create icheck.manifest containing:
#include "icheck.static-manifest"
#include "icheck.dynamic-manifest"
This allows you to update some parts of the manifest by hand, while
still automatically generating the rest.
OUTPUT
icheck generates a lengthly description of every possible API or ABI
change, based on type information. It does not investigate the actual
program code, and so it is possible that some type changes it detects
are not actual ABI or API changes. However, this normally only happens
when the program code was explicitly written for it. If in doubt,
assume it’s changed.
At the end, icheck provides a summary of the changes. Note that the
directions here are dependent on the order of the arguments to
--compare: the older interface must come first, or the directions will
be the other way around. The meanings of the various terms are as
follows:
ABI The ABI is compatible if things compiled against one
version of the interface will work when run using the
other version.
API The API is compatible if things compiled against one
version of the interface can be compiled against the
other.
forwards-compatible
An interface is forwards-compatible if things compiled
against the old version will work with the new. This is
the important feature for soname changes.
backwards-compatible
An interface is backwards-compatible if things compiled
against the new version will work with the old. This is
the important feature for shlibs version changes. If you
aren’t building Debian packages, you probably don’t care
about changes which aren’t backwards-compatible.
AUTHOR
icheck was written by Andrew Suffield <asuffield@debian.org>.
This manual page was written by Neil Williams <linux@codehelp.co.uk>
and Andrew Suffield <asuffield@debian.org>.
icheck(1)