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