1.. _abipkgdiff_label: 2 3=========== 4abipkgdiff 5=========== 6 7``abipkgdiff`` compares the Application Binary Interfaces (ABI) of the 8`ELF`_ binaries contained in two software packages. The software 9package formats currently supported are `Deb`_, `RPM`_, `tar`_ 10archives (either compressed or not) and plain directories that contain 11binaries. 12 13For a comprehensive ABI change report that includes changes about 14function and variable sub-types, the two input packages must be 15accompanied with their debug information packages that contain debug 16information in `DWARF`_ format. 17 18 19.. _abipkgdiff_invocation_label: 20 21Invocation 22========== 23 24:: 25 26 abipkgdiff [option] <package1> <package2> 27 28``package1`` and ``package2`` are the packages that contain the 29binaries to be compared. 30 31 32Environment 33=========== 34 35.. _abipkgdiff_default_supprs_label: 36 37abipkgdiff loads two default :ref:`suppression specifications files 38<suppr_spec_label>`, merges their content and use it to filter out ABI 39change reports that might be considered as false positives to users. 40 41* Default system-wide suppression specification file 42 43 It's located by the optional environment variable 44 LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment 45 variable is not set, then abipkgdiff tries to load the suppression file 46 $libdir/libabigail/libabigail-default.abignore. If that file is not 47 present, then no default system-wide suppression specification file 48 is loaded. 49 50* Default user suppression specification file. 51 52 It's located by the optional environment 53 LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. If that environment 54 variable is not set, then abipkgdiff tries to load the suppression file 55 $HOME/.abignore. If that file is not present, then no default user 56 suppression specification is loaded. 57 58In addition to those default suppression specification files, 59abipkgdiff will also look inside the packages being compared and if it 60sees a file that ends with the extension ``.abignore``, then it will 61consider it as a suppression specification and it will combine it to the 62default suppression specification that might be already loaded. 63 64The user might as well use the ``--suppressions`` option (that is 65documented further below) to provide a suppression specification. 66 67.. _abipkgdiff_options_label: 68 69Options 70======= 71 72 * ``--help | -h`` 73 74 Display a short help about the command and exit. 75 76 * `--version | -v` 77 78 Display the version of the program and exit. 79 80 * ``--debug-info-pkg1 | --d1`` <path> 81 82 For cases where the debug information for *package1* is split out 83 into a separate file, tells ``abipkgdiff`` where to find that 84 separate debug information package. 85 86 Note that the debug info for *package1* can have been split into 87 several different debug info packages. In that case, several 88 instances of this options can be provided, along with those 89 several different debug info packages. 90 91 * ``--debug-info-pkg2 | --d2`` <path> 92 93 For cases where the debug information for *package2* is split out 94 into a separate file, tells ``abipkgdiff`` where to find that 95 separate debug information package. 96 97 Note that the debug info for *package2* can have been split into 98 several different debug info packages. In that case, several 99 instances of this options can be provided, along with those 100 several different debug info packages. 101 102 * ``--devel-pkg1 | --devel1`` <path> 103 104 Specifies where to find the `Development Package`_ associated with 105 the first package to be compared. That `Development Package`_ at 106 ``path`` should at least contain header files in which public 107 types exposed by the libraries (of the first package to be 108 compared) are defined. When this option is provided, the tool 109 filters out reports about ABI changes to types that are *NOT* 110 defined in these header files. 111 112 * ``--devel-pkg2 | --devel2`` <path> 113 114 Specifies where to find the `Development Package`_ associated with 115 the second package to be compared. That `Development Package`_ at 116 ``path`` should at least contains header files in which public 117 types exposed by the libraries (of the second package to be 118 compared) are defined. When this option is provided, the tool 119 filters out reports about ABI changes to types that are *NOT* 120 defined in these header files. 121 122 * ``--drop-private-types`` 123 124 This option is to be used with the ``--devel-pkg1`` and 125 ``--devel-pkg2`` options. With this option, types that are *NOT* 126 defined in the headers are entirely dropped from the internal 127 representation build by Libabigail to represent the ABI. They 128 thus don't have to be filtered out from the final ABI change 129 report because they are not even present in Libabigail's 130 representation. 131 132 Without this option however, those private types are kept in the 133 internal representation and later filtered out from the report. 134 135 This options thus potentially makes Libabigail consume less 136 memory. It's meant to be mainly used to optimize the memory 137 consumption of the tool on binaries with a lot of publicly defined 138 and exported types. 139 140 * ``--dso-only`` 141 142 Compare ELF files that are shared libraries, only. Do not compare 143 executable files, for instance. 144 145 * ``--private-dso`` 146 147 By default, ``abipkgdiff`` does not compare DSOs that are private 148 to the RPM package. A private DSO is a DSO which SONAME is *NOT* 149 advertised in the "provides" property of the RPM. 150 151 This option instructs ``abipkgdiff`` to *also* compare DSOs that 152 are *NOT* advertised in the "provides" property of the RPM. 153 154 Please note that the fact that (by default) ``abipkgdiff`` skips 155 private DSO is a feature that is available only for RPMs, at the 156 moment. We would happily accept patches adding that feature for 157 other package formats. 158 159 * ``--leaf-changes-only|-l`` only show leaf changes, so don't show 160 impact analysis report. This option implies ``--redundant`` 161 162 The typical output of ``abipkgdiff`` and ``abidiff`` when 163 comparing two binaries, that we shall call ``full impact report``, 164 looks like this :: 165 166 $ abidiff libtest-v0.so libtest-v1.so 167 Functions changes summary: 0 Removed, 1 Changed, 0 Added function 168 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 169 170 1 function with some indirect sub-type change: 171 172 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes: 173 parameter 1 of type 'C&' has sub-type changes: 174 in referenced type 'struct C' at test-v1.cc:7:1: 175 type size hasn't changed 176 1 data member change: 177 type of 'leaf* C::m0' changed: 178 in pointed to type 'struct leaf' at test-v1.cc:1:1: 179 type size changed from 32 to 64 bits 180 1 data member insertion: 181 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1 182 183 $ 184 185 So in that example the report emits information about how the data 186 member insertion change of "struct leaf" is reachable from 187 function "void fn(C&)". In other words, the report not only shows 188 the data member change on "struct leaf", but it also shows the 189 impact of that change on the function "void fn(C&)". 190 191 In abidiff (and abipkgdiff) parlance, the change on "struct leaf" 192 is called a leaf change. So the ``--leaf-changes-only 193 --impacted-interfaces`` options show, well, only the leaf change. 194 And it goes like this: :: 195 196 $ abidiff -l libtest-v0.so libtest-v1.so 197 'struct leaf' changed: 198 type size changed from 32 to 64 bits 199 1 data member insertion: 200 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1 201 202 one impacted interface: 203 function void fn(C&) 204 $ 205 206 Note how the report ends up by showing the list of interfaces 207 impacted by the leaf change. That's the effect of the additional 208 ``--impacted-interfaces`` option. 209 210 Now if you don't want to see that list of impacted interfaces, 211 then you can just avoid using the ``--impacted-interface`` option. 212 You can learn about that option below, in any case. 213 214 Please note that when comparing two Linux Kernel packages, it's 215 this ``leaf changes report`` that is emitted, by default. The 216 normal so-called ``full impact report`` can be emitted with the 217 option ``--full-impact`` which is documented later below. 218 219 220 * ``--impacted-interfaces`` 221 222 When showing leaf changes, this option instructs abipkgdiff to 223 show the list of impacted interfaces. This option is thus to be 224 used in addition to the ``--leaf-changes-only`` option, or, when 225 comparing two Linux Kernel packages. Otherwise, it's simply 226 ignored. 227 228 * ``--full-impact|-f`` 229 230 When comparing two Linux Kernel packages, this function instructs 231 ``abipkgdiff`` to emit the so-called ``full impact report``, which 232 is the default report kind emitted by the ``abidiff`` tool: :: 233 234 $ abidiff libtest-v0.so libtest-v1.so 235 Functions changes summary: 0 Removed, 1 Changed, 0 Added function 236 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 237 238 1 function with some indirect sub-type change: 239 240 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes: 241 parameter 1 of type 'C&' has sub-type changes: 242 in referenced type 'struct C' at test-v1.cc:7:1: 243 type size hasn't changed 244 1 data member change: 245 type of 'leaf* C::m0' changed: 246 in pointed to type 'struct leaf' at test-v1.cc:1:1: 247 type size changed from 32 to 64 bits 248 1 data member insertion: 249 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1 250 251 $ 252 253 254 * ``--non-reachable-types|-t`` 255 256 Analyze and emit change reports for all the types of the binary, 257 including those that are not reachable from global functions and 258 variables. 259 260 This option might incur some serious performance degradation as 261 the number of types analyzed can be huge. However, if paired with 262 the ``--devel-pkg{1,2}`` options, the additional non-reachable 263 types analyzed are restricted to those defined in the public 264 headers files carried by the referenced development packages, thus 265 hopefully making the performance hit acceptable. 266 267 Also, using this option alongside suppression specifications (by 268 also using the ``--suppressions`` option) might help keep the number of 269 analyzed types (and the potential performance degradation) in 270 control. 271 272 Note that without this option, only types that are reachable from 273 global functions and variables are analyzed, so the tool detects 274 and reports changes on these reachable types only. 275 276 * ``--redundant`` 277 278 In the diff reports, do display redundant changes. A redundant 279 change is a change that has been displayed elsewhere in a given 280 report. 281 282 * ``--harmless`` 283 284 In the diff report, display only the :ref:`harmless 285 <harmlesschangeconcept_label>` changes. By default, the harmless 286 changes are filtered out of the diff report keep the clutter to a 287 minimum and have a greater chance to spot real ABI issues. 288 289 * ``--no-linkage-name`` 290 291 In the resulting report, do not display the linkage names of 292 the added, removed, or changed functions or variables. 293 294 * ``--no-added-syms`` 295 296 Do not show the list of functions, variables, or any symbol that 297 was added. 298 299 * ``--no-added-binaries`` 300 301 Do not show the list of binaries that got added to the second 302 package. 303 304 Please note that the presence of such added binaries is not 305 considered like an ABI change by this tool; as such, it doesn't 306 have any impact on the exit code of the tool. It does only have 307 an informational value. Removed binaries are, however, considered 308 as an ABI change. 309 310 * ``--no-abignore`` 311 312 Do not search the package for the presence of suppression files. 313 314 * ``--no-parallel`` 315 316 By default, ``abipkgdiff`` will use all the processors it has available to 317 execute concurrently. This option tells it not to extract packages or run 318 comparisons in parallel. 319 320 * ``--no-default-suppression`` 321 322 Do not load the :ref:`default suppression specification files 323 <abipkgdiff_default_supprs_label>`. 324 325 * ``--suppressions | --suppr`` <*path-to-suppressions*> 326 327 Use a :ref:`suppression specification <suppr_spec_label>` file 328 located at *path-to-suppressions*. Note that this option can 329 appear multiple times on the command line. In that case, all of 330 the suppression specification files are taken into account. 331 332 Please note that, by default, if this option is not provided, then 333 the :ref:`default suppression specification files 334 <abipkgdiff_default_supprs_label>` are loaded . 335 336 * ``--linux-kernel-abi-whitelist | -w`` <*path-to-whitelist*> 337 338 When comparing two Linux kernel RPM packages, this option points 339 to the white list of names of ELF symbols of functions and 340 variables that must be compared for ABI changes. That white list 341 is called a "Linux kernel ABI white list". 342 343 Any other function or variable which ELF symbol are not present in 344 that white list will not be considered by the ABI comparison 345 process. 346 347 If this option is not provided -- thus if no white list is 348 provided -- then the ABI of all publicly defined and exported 349 functions and global variables by the Linux Kernel binaries are 350 compared. 351 352 Please note that if a white list package is given in parameter, 353 this option handles it just fine, like if the --wp option was 354 used. 355 356 * ``--wp`` <*path-to-whitelist-package*> 357 358 When comparing two Linux kernel RPM packages, this option points 359 an RPM package containining several white lists of names of ELF 360 symbols of functions and variables that must be compared for ABI 361 changes. Those white lists are called "Linux kernel ABI white 362 lists". 363 364 From the content of that white list package, this program then 365 chooses the appropriate Linux kernel ABI white list to consider 366 when comparing the ABI of Linux kernel binaries contained in the 367 Linux kernel packages provided on the command line. 368 369 That choosen Linux kernel ABI white list contains the list of 370 names of ELF symbols of functions and variables that must be 371 compared for ABI changes. 372 373 Any other function or variable which ELF symbol are not present in 374 that white list will not be considered by the ABI comparison 375 process. 376 377 Note that this option can be provided twice (not mor than twice), 378 specifying one white list package for each Linux Kernel package 379 that is provided on the command line. 380 381 If this option is not provided -- thus if no white list is 382 provided -- then the ABI of all publicly defined and exported 383 functions and global variables by the Linux Kernel binaries are 384 compared. 385 386 * ``--no-unreferenced-symbols`` 387 388 In the resulting report, do not display change information about 389 function and variable symbols that are not referenced by any debug 390 information. Note that for these symbols not referenced by any 391 debug information, the change information displayed is either 392 added or removed symbols. 393 394 * ``--no-show-locs`` 395 396 Do not show information about where in the *second shared library* 397 the respective type was changed. 398 399 * ``--show-bytes`` 400 401 Show sizes and offsets in bytes, not bits. By default, sizes and 402 offsets are shown in bits. 403 404 * ``--show-bits`` 405 406 Show sizes and offsets in bits, not bytes. This option is 407 activated by default. 408 409 * ``--show-hex`` 410 411 Show sizes and offsets in hexadecimal base. 412 413 * ``--show-dec`` 414 415 Show sizes and offsets in decimal base. This option is activated 416 by default. 417 418 * ``--no-show-relative-offset-changes`` 419 420 Without this option, when the offset of a data member changes, 421 the change report not only mentions the older and newer offset, 422 but it also mentions by how many bits the data member changes. 423 With this option, the latter is not shown. 424 425 * ``--show-identical-binaries`` 426 427 Show the names of the all binaries compared, including the 428 binaries whose ABI compare equal. By default, when this option is 429 not provided, only binaries with ABI changes are mentionned in the 430 output. 431 432 * ``--fail-no-dbg`` 433 434 Make the program fail and return a non-zero exit code if couldn't 435 read any of the debug information that comes from the debug info 436 packages that were given on the command line. If no debug info 437 package were provided on the command line then this option is not 438 active. 439 440 Note that the non-zero exit code returned by the program as a 441 result of this option is the constant ``ABIDIFF_ERROR``. To know 442 the numerical value of that constant, please refer to the 443 :ref:`exit code documentation <abidiff_return_value_label>`. 444 445 * ``--keep-tmp-files`` 446 447 Do not erase the temporary directory files that are created during 448 the execution of the tool. 449 450 * ``--verbose`` 451 452 Emit verbose progress messages. 453 454 455 * ``self-check`` 456 457 This is used to test the underlying Libabigail library. When in 458 used, the command expects only on input package, along with its 459 associated debug info packages. The command then compares each 460 binary inside the package against its own ABIXML 461 representation. The result of the comparison should yield the 462 empty set if Libabigail behaves correctly. Otherwise, it means 463 there is an issue that ought to be fixed. This option is used by 464 people interested in Libabigail development for regression testing 465 purposes. Here is an example of the use of this option: :: 466 467 $ 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 468 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ==== 469 $ 470 471.. _abipkgdiff_return_value_label: 472 473Return value 474============ 475 476The exit code of the ``abipkgdiff`` command is either 0 if the ABI of 477the binaries compared are equal, or non-zero if they differ or if the 478tool encountered an error. 479 480In the later case, the value of the exit code is the same as for the 481:ref:`abidiff tool <abidiff_return_value_label>`. 482 483 484.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 485.. _RPM: https://en.wikipedia.org/wiki/RPM_Package_Manager 486.. _Deb: https://en.wikipedia.org/wiki/Deb_%28file_format%29 487.. _tar: https://en.wikipedia.org/wiki/Tar_%28computing%29 488.. _DWARF: http://www.dwarfstd.org 489.. _Development Package: https://fedoraproject.org/wiki/Packaging:Guidelines?rd=Packaging/Guidelines#Devel_Packages 490