1.. _fedabipkgdiff_label: 2 3============== 4fedabipkgdiff 5============== 6 7``fedabipkgdiff`` compares the ABI of shared libraries in `Fedora`_ 8packages. It's a convenient way to do so without having to manually 9download packages from the `Fedora Build System`_. 10 11``fedabipkgdiff`` knows how to talk with the `Fedora Build System`_ to 12find the right packages versions, their associated debug information 13and development packages, download them, compare their ABI locally, 14and report about the possible ABI changes. 15 16Note that by default, this tool reports ABI changes about types that 17are defined in public header files found in the development packages 18associated with the packages being compared. It also reports ABI 19changes about functions and global variables whose symbols are defined 20and exported in the ELF binaries found in the packages being compared. 21 22.. _fedabipkgdiff_invocation_label: 23 24Invocation 25========== 26 27:: 28 29 fedabipkgdiff [option] <NVR> ... 30 31Environment 32=========== 33 34.. _fedabipkgdiff_default_supprs_label: 35 36fedabipkgdiff loads two default :ref:`suppression specifications files 37<suppr_spec_label>`, merges their content and use it to filter out ABI 38change reports that might be considered as false positives to users. 39 40* Default system-wide suppression specification file 41 42 It's located by the optional environment variable 43 LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment 44 variable is not set, then fedabipkgdiff tries to load the 45 suppression file $libdir/libabigail/libabigail-default.abignore. If 46 that file is not present, then no default system-wide suppression 47 specification file is loaded. 48 49* Default user suppression specification file. 50 51 It's located by the optional environment 52 LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. If that environment 53 variable is not set, then fedabipkgdiff tries to load the 54 suppression file $HOME/.abignore. If that file is not present, then 55 no default user suppression specification is loaded. 56 57 58.. _fedabipkgdiff_options_label: 59 60Options 61======= 62 63 * ``--help | -h`` 64 65 Display a short help about the command and exit. 66 67 * ``--dry-run`` 68 69 Don't actually perform the ABI comparison. Details about what is 70 going to be done are emitted on standard output. 71 72 * ``--debug`` 73 74 Emit debugging messages about the execution of the program. 75 Details about each method invocation, including input parameters 76 and returned values, are emitted. 77 78 * ``--traceback`` 79 80 Show traceback when an exception raised. This is useful for 81 developers of the tool itself to know more exceptional errors. 82 83 * ``--server`` <URL> 84 85 Specifies the URL of the `Koji`_ XMLRPC service the tool talks to. 86 The default value of this option is http://koji.fedoraproject.org/kojihub. 87 88 * ``--topurl`` <URL> 89 90 Specifies the URL of the package store the tool downloads RPMs 91 from. The default value of this option is https://kojipkgs.fedoraproject.org. 92 93 * ``--from`` <distro> 94 95 Specifies the name of the baseline `Fedora`_ distribution in which to 96 find the first `build`_ that is used for comparison. The 97 ``distro`` value can be any valid value of the RPM macro 98 ``%{?dist}`` for `Fedora`_, for example, ``fc4``, ``fc23``, ``fc25``. 99 100 * ``--to`` <distro> 101 102 Specifies the name of the `Fedora`_ distribution in which to find 103 the `build`_ that is compared against the baseline specified by 104 option ``--from``. The ``distro`` value could be any valid value 105 of the RPM macro ``%{?dist}`` for `Fedora`_, for example, ``fc4``, 106 ``fc23``. 107 108 * ``--all-subpackages`` 109 110 Instructs the tool to also compare the ABI of the binaries in the 111 sub-packages of the packages specified. 112 113 * ``--dso-only`` 114 115 Compares the ABI of shared libraries only. If this option is not 116 provided, the tool compares the ABI of all ELF binaries found in 117 the packages. 118 119 * ``--suppressions`` <*path-to-suppresions*> 120 121 Use a :ref:`suppression specification <suppr_spec_label>` file 122 located at *path-to-suppressions*. 123 124 125 * ``--no-default-suppression`` 126 127 Do not load the :ref:`default suppression specification files 128 <fedabipkgdiff_default_supprs_label>`. 129 130 * ``--no-devel-pkg`` 131 132 Do not take associated development packages into account when 133 performing the ABI comparison. This makes the tool report ABI 134 changes about all types that are reachable from functions and 135 global variables which symbols are defined and publicly exported 136 in the binaries being compared, even if those types are not 137 defined in public header files available from the packages being 138 compared. 139 140 * ``--show-identical-binaries`` 141 142 Show the names of the all binaries compared, including the 143 binaries whose ABI compare equal. By default, when this option is 144 not provided, only binaries with ABI changes are mentionned in the 145 output. 146 147 * ``--abipkgdiff`` <path/to/abipkgdiff> 148 149 Specify an alternative abipkgdiff instead of the one installed in system. 150 151 * ``--clean-cache-before`` 152 153 Clean cache before ABI comparison. 154 155 * ``--clean-cache-after`` 156 157 Clean cache after ABI comparison. 158 159 * ``--clean-cache`` 160 161 If you want to clean cache both before and after ABI comparison, 162 ``--clean-cache`` is the convenient way for you to save typing of two 163 options at same time. 164 165.. _build: 166 167Note that a build is a specific version and release of an RPM package. 168It's specified by its the package name, version and release. These are specified 169by the `Fedora Naming Guidelines <https://fedoraproject.org/wiki/Packaging:NamingGuidelines>`_ 170 171 172.. _fedabipkgdiff_return_value_label: 173 174Return value 175============ 176 177The exit code of the ``abipkgdiff`` command is either 0 if the ABI of 178the binaries compared are equivalent, or non-zero if they differ or if 179the tool encountered an error. 180 181In the later case, the value of the exit code is the same as for the 182:ref:`abidiff tool <abidiff_return_value_label>`. 183 184.. _fedabipkgdiff_usage_example_label: 185 186 187Use cases 188========= 189 190Below are some usage examples currently supported by 191``fedabipkgdiff``. 192 193 1. Compare the ABI of binaries in a local package against the ABI of 194 the latest stable package in `Fedora`_ 23. 195 196 Suppose you have built just built the ``httpd`` package and you 197 want to compare the ABI of the binaries in this locally built 198 package against the ABI of the binaries in the latest ``http`` 199 build from `Fedora`_ 23. The command line invocation would be: :: 200 201 $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm 202 203 2. Compare the ABI of binaries in two local packages. 204 205 Suppose you have built two versions of package httpd, and you want to see 206 what ABI differences between these two versions of RPM files. The 207 command line invocation would be:: 208 209 $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm 210 211 All what fedabipkgdiff does happens on local machine without the need of 212 querying or downloading RPMs from Koji. 213 214 3. Compare the ABI of binaries in the latest build of the ``httpd`` 215 package in ``Fedora 23`` against the ABI of the binaries in the 216 latest build of the same package in 24. 217 218 In this case, note that neither of the two packages are available 219 locally. The tool is going to talk with the `Fedora Build 220 System`_, determine what the versions and releases of the latest 221 packages are, download them and perform the comparison locally. 222 The command line invocation would be: :: 223 224 $ fedabipkgdiff --from fc23 --to fc24 httpd 225 226 4. Compare the ABI of binaries of two builds of the ``httpd`` 227 package, designated their versions and releases. 228 229 If we want to do perform the ABI comparison for all the processor 230 architectures supported by `Fedora`_ the command line invocation 231 would be: :: 232 233 $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24 234 235 But if we want to perform the ABI comparison for a specific 236 architecture, say, x86_64, then the command line invocation would 237 be: :: 238 239 $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64 240 241 5. If the use wants to also compare the sub-packages of a given 242 package, she can use the --all-subpackages option. The first 243 command of the previous example would thus look like: :: 244 245 $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24 246 247.. _Fedora: https://getfedora.org 248.. _Fedora Build System: http://koji.fedoraproject.org/koji 249.. _Koji: https://fedoraproject.org/wiki/Koji 250