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)