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)