Provided by: abigail-tools_2.3-1_amd64 bug

NAME

       abipkgdiff - compare ABIs of ELF files in software packages

       abipkgdiff  compares the Application Binary Interfaces (ABI) of the ELF binaries contained
       in two software packages.  The software package formats currently supported are Deb,  RPM,
       tar archives (either compressed or not) and plain directories that contain binaries.

       For  a  comprehensive  ABI change report that includes changes about function and variable
       sub-types, the two input  packages  must  be  accompanied  with  their  debug  information
       packages  that  contain  debug information either in DWARF, CTF or in BTF formats.  Please
       note however that some packages contain binaries that embed the debug information directly
       in  a  section of said binaries.  In those cases, obviously, no separate debug information
       package is needed as the tool will find the debug information inside the binaries.

       By default, abipkgdiff uses debug information in DWARF format, if  present,  otherwise  it
       compares binaries interfaces using debug information in CTF or in BTF formats, if present.
       Finally, if no debug info in these formats is found, it only  considers  ELF  symbols  and
       report about their addition or removal.

       This  tool  uses  the  libabigail  library to analyze the binary as well as its associated
       debug information.  Here is its general mode of operation.

       When instructed to do so, a binary and  its  associated  debug  information  is  read  and
       analyzed.   To  that  effect, libabigail analyzes by default the descriptions of the types
       reachable by the interfaces (functions and variables) that are visible  outside  of  their
       translation  unit.   Once that analysis is done, an Application Binary Interface Corpus is
       constructed by only considering the subset of types reachable from  interfaces  associated
       to  ELF  symbols  that are defined and exported by the binary.  It’s that final ABI corpus
       which libabigail considers as representing the ABI of the analyzed binary.

       Libabigail then has capabilities to  generate  textual  representations  of  ABI  Corpora,
       compare them, analyze their changes and report about them.

INVOCATION

          abipkgdiff [option] <package1> <package2>

       package1 and package2 are the packages that contain the binaries to be compared.

ENVIRONMENT

       abipkgdiff  loads  two  default suppression specifications files, merges their content and
       use it to filter out ABI change reports that might be considered  as  false  positives  to
       users.

       • Default system-wide suppression specification file

         It’s        located        by        the       optional       environment       variable
         LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE.  If that environment variable  is  not  set,
         then       abipkgdiff       tries       to      load      the      suppression      file
         $libdir/libabigail/libabigail-default.abignore.  If that file is not  present,  then  no
         default system-wide suppression specification file is loaded.

       • Default user suppression specification file.

         It’s  located  by the optional environment LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE.  If
         that environment variable is not set, then abipkgdiff tries to load the suppression file
         $HOME/.abignore.   If  that  file  is  not  present,  then  no  default user suppression
         specification is loaded.

       In addition to those default suppression specification files, abipkgdiff  will  also  look
       inside  the  packages  being  compared  and if it sees a file that ends with the extension
       .abignore, then it will consider it as a suppression specification and it will combine  it
       to the default suppression specification that might be already loaded.

       The user might as well use the --suppressions option (that is documented further below) to
       provide a suppression specification.

OPTIONS

--help | -h

            Display a short help about the command and exit.

          • –version | -v

            Display the version of the program and exit.

          • --debug-info-pkg1 | --d1 <path>

            For cases where the debug information for package1 is split out into a separate file,
            tells abipkgdiff where to find that separate debug information package.

            Note  that  the  debug  info  for package1 can have been split into several different
            debug info packages.  In  that  case,  several  instances  of  this  options  can  be
            provided, along with those several different debug info packages.

          • --debug-info-pkg2 | --d2 <path>

            For cases where the debug information for package2 is split out into a separate file,
            tells abipkgdiff where to find that separate debug information package.

            Note that the debug info for package2 can have  been  split  into  several  different
            debug  info  packages.   In  that  case,  several  instances  of  this options can be
            provided, along with those several different debug info packages.

          • --devel-pkg1 | --devel1 <path>

            Specifies where to find the Development Package associated with the first package  to
            be  compared.   That Development Package at path should at least contain header files
            in which public types exposed by the libraries (of the first package to be  compared)
            are  defined.   When  this option is provided, the tool filters out reports about ABI
            changes to types that are NOT defined in these header files.

          • --devel-pkg2 | --devel2 <path>

            Specifies where to find the Development Package associated with the second package to
            be  compared.  That Development Package at path should at least contains header files
            in which public types exposed by the libraries (of the second package to be compared)
            are  defined.   When  this option is provided, the tool filters out reports about ABI
            changes to types that are NOT defined in these header files.

          • --drop-private-types

            This option is to be used with the --devel-pkg1 and --devel-pkg2 options.  With  this
            option,  types  that  are  NOT  defined  in the headers are entirely dropped from the
            internal representation build by Libabigail to represent the ABI.   They  thus  don’t
            have  to  be  filtered out from the final ABI change report because they are not even
            present in Libabigail’s representation.

            Without  this  option  however,  those  private  types  are  kept  in  the   internal
            representation and later filtered out from the report.

            This options thus potentially makes Libabigail consume less memory.  It’s meant to be
            mainly used to optimize the memory consumption of the tool on binaries with a lot  of
            publicly defined and exported types.

          • --dso-only

            Compare  ELF files that are shared libraries, only.  Do not compare executable files,
            for instance.

          • --private-dso

            By default, abipkgdiff does not compare DSOs that are private to the RPM package.   A
            private DSO is a DSO which SONAME is NOT advertised in the “provides” property of the
            RPM.

            This option instructs abipkgdiff to also compare DSOs that are NOT advertised in  the
            “provides” property of the RPM.

            Please note that the fact that (by default) abipkgdiff skips private DSO is a feature
            that is available only for RPMs, at the moment.   We  would  happily  accept  patches
            adding that feature for other package formats.

          • --leaf-changes-only|-l  only show leaf changes, so don’t show impact analysis report.
            This option implies --redundant

            The typical output of abipkgdiff and abidiff when comparing  two  binaries,  that  we
            shall call full impact report, looks like this

                $ abidiff libtest-v0.so libtest-v1.so
                Functions changes summary: 0 Removed, 1 Changed, 0 Added function
                Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

                1 function with some indirect sub-type change:

                  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
                    parameter 1 of type 'C&' has sub-type changes:
                      in referenced type 'struct C' at test-v1.cc:7:1:
                        type size hasn't changed
                        1 data member change:
                         type of 'leaf* C::m0' changed:
                           in pointed to type 'struct leaf' at test-v1.cc:1:1:
                             type size changed from 32 to 64 bits
                             1 data member insertion:
                               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

                $

            So  in  that example the report emits information about how the data member insertion
            change of “struct leaf” is reachable from function “void fn(C&)”.   In  other  words,
            the  report not only shows the data member change on “struct leaf”, but it also shows
            the impact of that change on the function “void fn(C&)”.

            In abidiff (and abipkgdiff) parlance, the change on “struct leaf” is  called  a  leaf
            change.   So  the  --leaf-changes-only --impacted-interfaces options show, well, only
            the leaf change.  And it goes like this:

                $ abidiff -l libtest-v0.so libtest-v1.so
                'struct leaf' changed:
                  type size changed from 32 to 64 bits
                  1 data member insertion:
                    'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

                  one impacted interface:
                    function void fn(C&)
                $

            Note how the report ends up by showing the list of interfaces impacted  by  the  leaf
            change.  That’s the effect of the additional --impacted-interfaces option.

            Now  if  you  don’t  want  to see that list of impacted interfaces, then you can just
            avoid using the --impacted-interface option.  You can learn about that option  below,
            in any case.

            Please  note  that  when  comparing two Linux Kernel packages, it’s this leaf changes
            report that is emitted, by default.  The normal so-called full impact report  can  be
            emitted with the option --full-impact which is documented later below.

          • --impacted-interfaces

            When  showing  leaf  changes,  this  option  instructs abipkgdiff to show the list of
            impacted  interfaces.   This  option  is  thus  to  be  used  in  addition   to   the
            --leaf-changes-only option, or, when comparing two Linux Kernel packages.  Otherwise,
            it’s simply ignored.

          • --full-impact|-f

            When comparing two Linux Kernel packages, this function instructs abipkgdiff to  emit
            the  so-called  full  impact  report, which is the default report kind emitted by the
            abidiff tool:

                $ abidiff libtest-v0.so libtest-v1.so
                Functions changes summary: 0 Removed, 1 Changed, 0 Added function
                Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

                1 function with some indirect sub-type change:

                  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
                    parameter 1 of type 'C&' has sub-type changes:
                      in referenced type 'struct C' at test-v1.cc:7:1:
                        type size hasn't changed
                        1 data member change:
                         type of 'leaf* C::m0' changed:
                           in pointed to type 'struct leaf' at test-v1.cc:1:1:
                             type size changed from 32 to 64 bits
                             1 data member insertion:
                               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

                $

          • --non-reachable-types|-t

            Analyze and emit change reports for all the types of the binary, including those that
            are not reachable from global functions and variables.

            This  option  might incur some serious performance degradation as the number of types
            analyzed can be huge.  However, if paired  with  the  --devel-pkg{1,2}  options,  the
            additional non-reachable types analyzed are restricted to those defined in the public
            headers files carried by the referenced development packages, thus  hopefully  making
            the performance hit acceptable.

            Also,  using  this  option  alongside  suppression  specifications (by also using the
            --suppressions option) might  help  keep  the  number  of  analyzed  types  (and  the
            potential performance degradation) in control.

            Note  that  without  this option, only types that are reachable from global functions
            and variables are analyzed,  so  the  tool  detects  and  reports  changes  on  these
            reachable types only.

          • --exported-interfaces-only

            By  default,  when  looking at the debug information accompanying a binary, this tool
            analyzes the descriptions of the types reachable by  the  interfaces  (functions  and
            variables) that are visible outside of their translation unit.  Once that analysis is
            done, an ABI corpus is constructed by only considering the subset of types  reachable
            from  interfaces  associated  to  ELF  symbols  that  are defined and exported by the
            binary.  It’s those final ABI Corpora that are compared by this tool.

            The problem with that approach however is that analyzing all the interfaces that  are
            visible  from  outside their translation unit can amount to a lot of data, especially
            when those binaries are applications, as opposed to shared libraries.  One example of
            such  applications is the Linux Kernel.  Analyzing massive ABI corpora like these can
            be extremely slow.

            To mitigate that performance issue, this option allows  libabigail  to  only  analyze
            types  that  are  reachable  from interfaces associated with defined and exported ELF
            symbols.

            Note that this option is turned on  by  default  when  analyzing  the  Linux  Kernel.
            Otherwise, it’s turned off by default.

          • --allow-non-exported-interfaces

            When  looking  at the debug information accompanying a binary, this tool analyzes the
            descriptions of the types reachable by the interfaces (functions and variables)  that
            are  visible  outside  of their translation unit.  Once that analysis is done, an ABI
            corpus is constructed  by  only  considering  the  subset  of  types  reachable  from
            interfaces  associated  to  ELF  symbols that are defined and exported by the binary.
            It’s those final ABI Corpora that are compared by this tool.

            The problem with that approach however is that analyzing all the interfaces that  are
            visible  from  outside their translation unit can amount to a lot of data, especially
            when those binaries are applications, as opposed to shared libraries.  One example of
            such  applications is the Linux Kernel.  Analyzing massive ABI Corpora like these can
            be extremely slow.

            In the presence of an “average sized” binary however one can afford having libabigail
            analyze all interfaces that are visible outside of their translation unit, using this
            option.

            Note that this option is turned on by default, unless we are in the presence  of  the
            Linux Kernel.

          • --redundant
              In  the diff reports, do display redundant changes.  A redundant change is a change
              that has been displayed elsewhere in a given report.

          • --harmless

            In the diff report, display only the harmless  changes.   By  default,  the  harmless
            changes  are filtered out of the diff report keep the clutter to a minimum and have a
            greater chance to spot real ABI issues.

          • --no-linkage-name

            In the resulting report, do not display the linkage names of the added,  removed,  or
            changed functions or variables.

          • --no-added-syms

            Do not show the list of functions, variables, or any symbol that was added.

          • --no-added-binaries

            Do not show the list of binaries that got added to the second package.

            Please  note  that  the presence of such added binaries is not considered like an ABI
            change by this tool; as such, it doesn’t have any impact on  the  exit  code  of  the
            tool.   It  does  only  have  an informational value.  Removed binaries are, however,
            considered as an ABI change.

          • --no-abignore

            Do not search the package for the presence of suppression files.

          • --no-parallel

            By default, abipkgdiff will use all  the  processors  it  has  available  to  execute
            concurrently.   This  option  tells  it not to extract packages or run comparisons in
            parallel.

          • --no-default-suppression

            Do not load the default suppression specification files.

          • --suppressions | --suppr <path-to-suppressions>

            Use a suppression specification file located at path-to-suppressions.  Note that this
            option  can  appear  multiple  times  on  the command line.  In that case, all of the
            suppression specification files are taken into account.

            Please note that, by default, if this  option  is  not  provided,  then  the  default
            suppression specification files are loaded .

          • --linux-kernel-abi-whitelist | -w <path-to-whitelist>

            When comparing two Linux kernel RPM packages, this option points to the white list of
            names of ELF symbols of functions  and  variables  that  must  be  compared  for  ABI
            changes.  That white list is called a “Linux kernel ABI white list”.

            Any  other  function  or variable which ELF symbol are not present in that white list
            will not be considered by the ABI comparison process.

            If this option is not provided – thus if no white list is provided – then the ABI  of
            all  publicly defined and exported functions and global variables by the Linux Kernel
            binaries are compared.

            Please note that if a white list package is given in parameter, this  option  handles
            it just fine, like if the –wp option was used.

          • --wp <path-to-whitelist-package>

            When  comparing  two  Linux  kernel  RPM  packages, this option points an RPM package
            containining several white lists of names of ELF symbols of functions  and  variables
            that  must  be  compared for ABI changes.  Those white lists are called “Linux kernel
            ABI white lists”.

            From the  content  of  that  white  list  package,  this  program  then  chooses  the
            appropriate  Linux  kernel ABI white list to consider when comparing the ABI of Linux
            kernel binaries contained in the Linux kernel packages provided on the command line.

            That choosen Linux kernel ABI white list contains the list of names of ELF symbols of
            functions and variables that must be compared for ABI changes.

            Any  other  function  or variable which ELF symbol are not present in that white list
            will not be considered by the ABI comparison process.

            Note that this option can be provided twice (not  mor  than  twice),  specifying  one
            white  list  package  for  each  Linux Kernel package that is provided on the command
            line.

            If this option is not provided – thus if no white list is provided – then the ABI  of
            all  publicly defined and exported functions and global variables by the Linux Kernel
            binaries are compared.

          • --no-unreferenced-symbols

            In the resulting report,  do  not  display  change  information  about  function  and
            variable  symbols  that  are  not referenced by any debug information.  Note that for
            these symbols not  referenced  by  any  debug  information,  the  change  information
            displayed is either added or removed symbols.

          • --no-show-locs
              Do  not  show  information  about where in the second shared library the respective
              type was changed.

          • --show-bytes

            Show sizes and offsets in bytes, not bits.  By default, sizes and offsets  are  shown
            in bits.

          • --show-bits

            Show sizes and offsets in bits, not bytes.  This option is activated by default.

          • --show-hex

            Show sizes and offsets in hexadecimal base.

          • --show-dec

            Show sizes and offsets in decimal base.  This option is activated by default.

          • --no-show-relative-offset-changes

            Without  this option, when the offset of a data member changes, the change report not
            only mentions the older and newer offset, but it also mentions by how many  bits  the
            data member changes.  With this option, the latter is not shown.

          • --show-identical-binaries
              Show  the  names  of  the  all  binaries compared, including the binaries whose ABI
              compare equal.  By default, when this option is not provided,  only  binaries  with
              ABI changes are mentionned in the output.

          • --fail-no-dbg

            Make  the  program  fail  and return a non-zero exit code if couldn’t read any of the
            debug information that comes from the debug info packages  that  were  given  on  the
            command  line.   If no debug info package were provided on the command line then this
            option is not active.

            Note that the non-zero exit code returned by the program as a result of  this  option
            is  the constant ABIDIFF_ERROR.  To know the numerical value of that constant, please
            refer to the exit code documentation.

          • --keep-tmp-files

            Do not erase the temporary directory files that are created during the  execution  of
            the tool.

          • --verbose

            Emit verbose progress messages.

          • --self-check

            This  is  used  to test the underlying Libabigail library.  When in used, the command
            expects only on input package, along with its associated debug  info  packages.   The
            command  then  compares  each  binary  inside  the  package  against  its  own ABIXML
            representation. The result of the comparison should yield the empty set if Libabigail
            behaves  correctly.   Otherwise,  it  means there is an issue that ought to be fixed.
            This option is used by people interested in  Libabigail  development  for  regression
            testing purposes.  Here is an example of the use of this option:

                $ abipkgdiff --self-check --d1 mesa-libGLU-debuginfo-9.0.1-3.fc33.x86_64.rpm  mesa-libGLU-9.0.1-3.fc33.x86_64.rpm
                 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
                $

          • --no-assume-odr-for-cplusplus

            When  analysing  a  binary  originating  from C++ code using DWARF debug information,
            libabigail assumes the One Definition Rule to speed-up the analysis.  In  that  case,
            when  several  types  have  the  same  name in the binary, they are assumed to all be
            equal.

            This option disables that assumption and instructs libabigail  to  actually  actually
            compare the types to determine if they are equal.

          • --no-leverage-dwarf-factorization

            When  analysing  a  binary  which  DWARF debug information was processed with the DWZ
            tool, the type information is supposed to be already  factorized.   That  context  is
            used by libabigail to perform some speed optimizations.

            This option disables those optimizations.

          • --ctf
                This is used to compare packages with CTF debug information, if present.

          • --btf
                This is used to compare packages with BTF debug information, if present.

RETURN VALUE

       The  exit  code  of the abipkgdiff command is either 0 if the ABI of the binaries compared
       are equal, or non-zero if they differ or if the tool encountered an error.

       In the later case, the value of the exit code is the same as for the abidiff tool.

AUTHOR

       Dodji Seketeli

COPYRIGHT

       2014-2023, Red Hat, Inc.

                                           Jun 11, 2023                             ABIPKGDIFF(1)