# fedabipkgdiff

## NAME



           fedabipkgdiff - compare ABIs of Fedora packages
    
           **fedabipkgdiff** compares the ABI of shared libraries in ]8;;https://getfedora.org\_Fedora_]8;;\
           packages.  It's a convenient way to do so without having to
           manually download packages from the ]8;;http://koji.fedoraproject.org/koji\_Fedora Build System_]8;;\.
    
           **fedabipkgdiff** knows how to talk with the ]8;;http://koji.fedoraproject.org/koji\_Fedora Build System_]8;;\ to
           find the right packages versions, their associated debug
           information and development packages, download them, compare their
           ABI locally, and report about the possible ABI changes.
    
           Note that by default, this tool reports ABI changes about types
           that are defined in public header files found in the development
           packages associated with the packages being compared.  It also
           reports ABI changes about functions and global variables whose
           symbols are defined and exported in the ELF binaries found in the
           packages being compared.
    


## INVOCATION



              fedabipkgdiff [option] <NVR> ...
    


## ENVIRONMENT



           fedabipkgdiff 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 fedabipkgdiff 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 fedabipkgdiff tries to load the
             suppression file $HOME/.abignore.  If that file is not present,
             then no default user suppression specification is loaded.
    


## OPTIONS



              • **--abipkgdiff** <path/to/abipkgdiff>
    
                Specify an alternative abipkgdiff instead of the one
                installed in system.
    
              • **--all-subpackages**
    
                Instructs the tool to also compare the ABI of the binaries in
                the sub-packages of the packages specified.
    
              • **--clean-cache**
    
                If you want to clean cache both before and after ABI
                comparison, **--clean-cache** is the convenient way for you to
                save typing of two options at same time.
    
              • **--clean-cache-after**
    
                Clean cache after ABI comparison.
    
              • **--clean-cache-before**
    
                Clean cache before ABI comparison.
    
              • **--debug**
    
                Emit debugging messages about the execution of the program.
                Details about each method invocation, including input
                parameters and returned values, are emitted.
    
              • **--dry-run**
    
                Don't actually perform the ABI comparison.  Details about
                what is going to be done are emitted on standard output.
    
              • **--dso-only**
    
                Compares the ABI of shared libraries only.  If this option is
                not provided, the tool compares the ABI of all ELF binaries
                found in the packages.
    
              • **--from** <distro>
    
                Specifies the name of the baseline ]8;;https://getfedora.org\_Fedora_]8;;\ distribution in
                which to find the first _build_ that is used for comparison.
                The **distro** value can be any valid value of the RPM macro
                **%{?dist}** for ]8;;https://getfedora.org\_Fedora_]8;;\, for example, **fc4** , **fc23** , **fc25**.
    
              • **--help | -h**
    
                Display a short help about the command and exit.
    
              • **--no-default-suppression**
    
                Do not load the _default suppression specification files_.
    
              • **--no-devel-pkg**
    
                Do not take associated development packages into account when
                performing the ABI comparison.  This makes the tool report
                ABI changes about all types that are reachable from functions
                and global variables which symbols are defined and publicly
                exported in the binaries being compared, even if those types
                are not defined in public header files available from the
                packages being compared.
    
              • **--private-dso**
    
                Compare the ABI of shared libraries that are private to the
                packages.  If this option is not provided, shared libraries
                that are private to the packages being considered are not
                compared.
    
              • **--server** <URL>
    
                Specifies the URL of the ]8;;https://fedoraproject.org/wiki/Koji\_Koji_]8;;\ XMLRPC service the tool talks
                to.  The default value of this option is ]8;;http://koji.fedoraproject.org/kojihub\‐
                _http://koji.fedoraproject.org/kojihub _]8;;\.
    
              • **--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.
    
              • **--suppressions** <_path-to-suppresions_ >
    
                Use a _suppression specification_ file located at
                _path-to-suppressions_.
    
              • **--to** <distro>
    
                Specifies the name of the ]8;;https://getfedora.org\_Fedora_]8;;\ distribution in which to
                find the _build_ that is compared against the baseline
                specified by option **--from**.  The **distro** value could be any
                valid value of the RPM macro **%{?dist}** for ]8;;https://getfedora.org\_Fedora_]8;;\, for
                example, **fc4** , **fc23**.
    
              • **--topurl** <URL>
    
                Specifies the URL of the package store the tool downloads
                RPMs from.  The default value of this option is ]8;;https://kojipkgs.fedoraproject.org\‐
                _https://kojipkgs.fedoraproject.org _]8;;\.
    
              • **--traceback**
    
                Show traceback when an exception raised. This is useful for
                developers of the tool itself to know more exceptional
                errors.
    
           Note that a build is a specific version and release of an RPM
           package.  It's specified by its the package name, version and
           release. These are specified by the ]8;;https://fedoraproject.org/wiki/Packaging:NamingGuidelines\_Fedora Naming Guidelines_]8;;\
    


## RETURN VALUE



           The exit code of the **abipkgdiff** command is either 0 if the ABI of
           the binaries compared are equivalent, 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_.
    


## USE CASES



           Below are some usage examples currently supported by
           **fedabipkgdiff**.
    
              1. Compare the ABI of binaries in a local package against the
                 ABI of the latest stable package in ]8;;https://getfedora.org\_Fedora_]8;;\ 23.
    
                 Suppose you have built just built the **httpd** package and you
                 want to compare the ABI of the binaries in this locally
                 built package against the ABI of the binaries in the latest
                 **http** build from ]8;;https://getfedora.org\_Fedora_]8;;\ 23.  The command line invocation
                 would be:
    
                     $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
    
              2. Compare the ABI of binaries in two local packages.
    
                 Suppose you have built two versions of package httpd, and
                 you want to see what ABI differences between these two
                 versions of RPM files. The command line invocation would be:
    
                     $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
    
                 All what fedabipkgdiff does happens on local machine without
                 the need of querying or downloading RPMs from Koji.
    
              3. Compare the ABI of binaries in the latest build of the **httpd**
                 package in **Fedora 23** against the ABI of the binaries in the
                 latest build of the same package in 24.
    
                 In this case, note that neither of the two packages are
                 available locally.  The tool is going to talk with the ]8;;http://koji.fedoraproject.org/koji\‐
                 _Fedora Build System_]8;;\, determine what the versions and
                 releases of the latest packages are, download them and
                 perform the comparison locally.  The command line invocation
                 would be:
    
                     $ fedabipkgdiff --from fc23 --to fc24 httpd
    
              4. Compare the ABI of binaries of two builds of the **httpd**
                 package, designated their versions and releases.
    
                 If we want to do perform the ABI comparison for all the
                 processor architectures supported by ]8;;https://getfedora.org\_Fedora_]8;;\ the command line
                 invocation would be:
    
                     $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
    
                 But if we want to perform the ABI comparison for a specific
                 architecture, say, x86_64, then the command line invocation
                 would be:
    
                     $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
    
              5. If the use wants to also compare the sub-packages of a given
                 package, she can use the --all-subpackages option.  The
                 first command of the previous example would thus look like:
    
                     $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
    


* * *