1.. _abidiff_label: 2 3======= 4abidiff 5======= 6 7abidiff compares the Application Binary Interfaces (ABI) of two shared 8libraries in `ELF`_ format. It emits a meaningful report describing the 9differences between the two ABIs. 10 11This tool can also compare the textual representations of the ABI of 12two ELF binaries (as emitted by ``abidw``) or an ELF binary against a 13textual representation of another ELF binary. 14 15For a comprehensive ABI change report between two input shared 16libraries that includes changes about function and variable sub-types, 17``abidiff`` uses by default, debug information in `DWARF`_ format, if 18present, otherwise it compares interfaces using debug information in 19`CTF`_ or `BTF`_ formats, if present. Finally, if no debug info in 20these formats is found, it only considers `ELF`_ symbols and report 21about their addition or removal. 22 23.. include:: tools-use-libabigail.txt 24 25.. _abidiff_invocation_label: 26 27Invocation 28========== 29 30:: 31 32 abidiff [options] <first-shared-library> <second-shared-library> 33 34 35Environment 36=========== 37 38.. _abidiff_default_supprs_label: 39 40abidiff loads two default :ref:`suppression specifications files 41<suppr_spec_label>`, merges their content and use it to filter out ABI 42change reports that might be considered as false positives to users. 43 44* Default system-wide suppression specification file 45 46 It's located by the optional environment variable 47 LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment 48 variable is not set, then abidiff tries to load the suppression file 49 $libdir/libabigail/libabigail-default.abignore. If that file is not 50 present, then no default system-wide suppression specification file 51 is loaded. 52 53* Default user suppression specification file. 54 55 It's located by the optional environment 56 LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. If that environment 57 variable is not set, then abidiff tries to load the suppression file 58 $HOME/.abignore. If that file is not present, then no default user 59 suppression specification is loaded. 60 61.. _abidiff_options_label: 62 63Options 64======= 65 66 * ``--help | -h`` 67 68 Display a short help about the command and exit. 69 70 * ``--debug-self-comparison`` 71 72 In this mode, error messages are emitted for types which fail type 73 canonicalization, in some circumstances, when comparing a binary 74 against itself. 75 76 When comparing a binary against itself, canonical types of the 77 second binary should be equal (as much as possible) to canonical 78 types of the first binary. When some discrepancies are detected 79 in this mode, an abort signal is emitted and execution is halted. 80 This option should be used while executing the tool in a debugger, 81 for troubleshooting purposes. 82 83 This is an optional debugging and sanity check option. To enable 84 it the libabigail package needs to be configured with 85 the --enable-debug-self-comparison configure option. 86 87 * ``--debug-tc`` 88 89 In this mode, the process of type canonicalization is put under 90 heavy scrutiny. Basically, during type canonicalization, each 91 type comparison is performed twice: once in a structural mode 92 (comparing every sub-type member-wise), and once using canonical 93 comparison. The two comparisons should yield the same result. 94 Otherwise, an abort signal is emitted and the process can be 95 debugged to understand why the two kinds of comparison yield 96 different results. 97 98 This is an optional debugging and sanity check option. To enable 99 it the libabigail package needs to be configured with 100 the --enable-debug-type-canonicalization configure option. 101 102 * ``--version | -v`` 103 104 Display the version of the program and exit. 105 106 * ``--debug-info-dir1 | --d1`` <*di-path1*> 107 108 For cases where the debug information for *first-shared-library* 109 is split out into a separate file, tells ``abidiff`` where to find 110 that separate debug information file. 111 112 Note that *di-path* must point to the root directory under which 113 the debug information is arranged in a tree-like manner. Under 114 Red Hat based systems, that directory is usually 115 ``<root>/usr/lib/debug``. 116 117 This option can be provided several times with different root 118 directories. In that case, ``abidiff`` will potentially look into 119 all those root directories to find the split debug info for 120 *first-shared-library*. 121 122 Note also that this option is not mandatory for split debug 123 information installed by your system's package manager because 124 then ``abidiff`` knows where to find it. 125 126 * ``--debug-info-dir2 | --d2`` <*di-path2*> 127 128 Like ``--debug-info-dir1``, this options tells ``abidiff`` where 129 to find the split debug information for the 130 *second-shared-library* file. 131 132 This option can be provided several times with different root 133 directories. In that case, ``abidiff`` will potentially look into 134 all those root directories to find the split debug info for 135 *second-shared-library*. 136 137 * ``--headers-dir1 | --hd1`` <headers-directory-path-1> 138 139 Specifies where to find the public headers of the first shared 140 library (or binary in general) that the tool has to consider. The 141 tool will thus filter out ABI changes on types that are not 142 defined in public headers. 143 144 Note that several public header directories can be specified for 145 the first shared library. In that case the ``--headers-dir1`` 146 option should be present several times on the command line, like 147 in the following example: :: 148 149 $ abidiff --headers-dir1 /some/path \ 150 --headers-dir1 /some/other/path \ 151 binary-version-1 binary-version-2 152 153 * ``--header-file1 | --hf1`` <header-file-path-1> 154 155 Specifies where to find one public header of the first shared 156 library that the tool has to consider. The tool will thus filter 157 out ABI changes on types that are not defined in public headers. 158 159 * ``--headers-dir2 | --hd2`` <headers-directory-path-2> 160 161 Specifies where to find the public headers of the second shared 162 library that the tool has to consider. The tool will thus filter 163 out ABI changes on types that are not defined in public headers. 164 165 Note that several public header directories can be specified for 166 the second shared library. In that case the ``--headers-dir2`` 167 option should be present several times like in the following 168 example: :: 169 170 $ abidiff --headers-dir2 /some/path \ 171 --headers-dir2 /some/other/path \ 172 binary-version-1 binary-version-2 173 174 * ``--header-file2 | --hf2`` <header-file-path-2> 175 176 Specifies where to find one public header of the second shared 177 library that the tool has to consider. The tool will thus filter 178 out ABI changes on types that are not defined in public headers. 179 180 * ``--add-binaries1`` <*bin1,bin2,bin3,..*> 181 182 For each of the comma-separated binaries given in argument to this 183 option, if the binary is found in the directory specified by the 184 ``--added-binaries-dir1`` option, then ``abidiff`` loads the ABI 185 corpus of the binary and adds it to a set of corpora (called an 186 ABI Corpus Group) that includes the first argument of ``abidiff``. 187 188 That ABI corpus group is then compared against the second corpus 189 group given in argument to ``abidiff``. 190 191 * ``--add-binaries2`` <*bin1,bin2,bin3,..*> 192 193 For each of the comma-separated binaries given in argument to this 194 option, if the binary is found in the directory specified by the 195 ``--added-binaries-dir2`` option, then ``abidiff`` loads the ABI 196 corpus of the binary and adds it to a set of corpora(called an ABI 197 Corpus Group) that includes the second argument of ``abidiff``. 198 199 That ABI corpus group is then compared against the first corpus 200 group given in argument to ``abidiff``. 201 202 * ``--follow-dependencies | --fdeps`` 203 204 For each dependency of the first argument of ``abidiff``, if it's 205 found in the directory specified by the ``--added-binaries-dir1`` 206 option, then construct an ABI corpus out of the dependency, add it 207 to a set of corpora (called an ABI Corpus Group) that includes the 208 first argument of ``abidiff``. 209 210 Similarly, for each dependency of the second argument of 211 ``abidiff``, if it's found in the directory specified by the 212 ``--added-binaries-dir2`` option, then construct an ABI corpus out 213 of the dependency, add it to an ABI corpus group that includes the 214 second argument of ``abidiff``. 215 216 These two ABI corpus groups are then compared against each other. 217 218 Said otherwise, this makes ``abidiff`` compare the set of its 219 first input and its dependencies against the set of its second 220 input and its dependencies. 221 222 * ``list-dependencies | --ldeps`` 223 224 This option lists all the dependencies of the input arguments of 225 ``abidiff`` that are found in the directories specified by the 226 options ``--added-binaries-dir1`` and ``--added-binaries-dir2`` 227 228 * ``--added-binaries-dir1 | --abd1`` <added-binaries-directory-1> 229 230 This option is to be used in conjunction with the 231 ``--add-binaries1``, ``--follow-dependencies`` and 232 ``--list-dependencies`` options. Binaries referred to by these 233 options, if found in the directory `added-binaries-directory-1`, 234 are loaded as ABI corpus and are added to the first ABI corpus group 235 that is to be used in the comparison. 236 237 * ``--added-binaries-dir2 | --abd2`` <added-binaries-directory-2> 238 239 This option is to be used in conjunction with the 240 ``--add-binaries2``, ``--follow-dependencies`` and 241 ``--list-dependencies`` options. Binaries referred to by these 242 options, if found in the directory `added-binaries-directory-2`, 243 are loaded as ABI corpus and are added to the second ABI corpus 244 group to be used in the comparison. 245 246 * ``--no-linux-kernel-mode`` 247 248 Without this option, if abidiff detects that the binaries it is 249 looking at are Linux Kernel binaries (either vmlinux or modules) 250 then it only considers functions and variables which ELF symbols 251 are listed in the __ksymtab and __ksymtab_gpl sections. 252 253 With this option, abidiff considers the binary as a non-special 254 ELF binary. It thus considers functions and variables which are 255 defined and exported in the ELF sense. 256 257 * ``--kmi-whitelist | -kaw`` <*path-to-whitelist*> 258 259 When analyzing a Linux kernel binary, this option points to the 260 white list of names of ELF symbols of functions and variables 261 which ABI must be considered. That white list is called a "Kernel 262 Module Interface white list". This is because for the Kernel, we 263 don't talk about ``ABI``; we rather talk about the interface 264 between the Kernel and its module. Hence the term ``KMI`` rather 265 than ``ABI``. 266 267 Any other function or variable which ELF symbol are not present in 268 that white list will not be considered by this tool. 269 270 If this option is not provided -- thus if no white list is 271 provided -- then the entire KMI, that is, the set of all publicly 272 defined and exported functions and global variables by the Linux 273 Kernel binaries, is considered. 274 275 * ``--drop-private-types`` 276 277 This option is to be used with the ``--headers-dir1``, 278 ``header-file1``, ``header-file2`` and ``--headers-dir2`` options. 279 With this option, types that are *NOT* defined in the headers are 280 entirely dropped from the internal representation build by 281 Libabigail to represent the ABI. They thus don't have to be 282 filtered out from the final ABI change report because they are not 283 even present in Libabigail's representation. 284 285 Without this option however, those private types are kept in the 286 internal representation and later filtered out from the report. 287 288 This options thus potentially makes Libabigail consume less 289 memory. It's meant to be mainly used to optimize the memory 290 consumption of the tool on binaries with a lot of publicly defined 291 and exported types. 292 293 * ``--exported-interfaces-only`` 294 295 By default, when looking at the debug information accompanying a 296 binary, this tool analyzes the descriptions of the types reachable 297 by the interfaces (functions and variables) that are visible 298 outside of their translation unit. Once that analysis is done, an 299 ABI corpus is constructed by only considering the subset of types 300 reachable from interfaces associated to `ELF`_ symbols that are 301 defined and exported by the binary. It's those final ABI Corpora 302 that are compared by this tool. 303 304 The problem with that approach however is that analyzing all the 305 interfaces that are visible from outside their translation unit 306 can amount to a lot of data, especially when those binaries are 307 applications, as opposed to shared libraries. One example of such 308 applications is the `Linux Kernel`_. Analyzing massive ABI 309 corpora like these can be extremely slow. 310 311 To mitigate that performance issue, this option allows libabigail 312 to only analyze types that are reachable from interfaces 313 associated with defined and exported `ELF`_ symbols. 314 315 Note that this option is turned on by default when analyzing the 316 `Linux Kernel`_. Otherwise, it's turned off by default. 317 318 * ``--allow-non-exported-interfaces`` 319 320 When looking at the debug information accompanying a binary, this 321 tool analyzes the descriptions of the types reachable by the 322 interfaces (functions and variables) that are visible outside of 323 their translation unit. Once that analysis is done, an ABI corpus 324 is constructed by only considering the subset of types reachable 325 from interfaces associated to `ELF`_ symbols that are defined and 326 exported by the binary. It's those final ABI Corpora that are 327 compared by this tool. 328 329 The problem with that approach however is that analyzing all the 330 interfaces that are visible from outside their translation unit 331 can amount to a lot of data, especially when those binaries are 332 applications, as opposed to shared libraries. One example of such 333 applications is the `Linux Kernel`_. Analyzing massive ABI 334 Corpora like these can be extremely slow. 335 336 In the presence of an "average sized" binary however one can 337 afford having libabigail analyze all interfaces that are visible 338 outside of their translation unit, using this option. 339 340 Note that this option is turned on by default, unless we are in 341 the presence of the `Linux Kernel`_. 342 343 * ``--stat`` 344 345 Rather than displaying the detailed ABI differences between 346 *first-shared-library* and *second-shared-library*, just display 347 some summary statistics about these differences. 348 349 * ``--symtabs`` 350 351 Only display the symbol tables of the *first-shared-library* and 352 *second-shared-library*. 353 354 * ``--deleted-fns`` 355 356 In the resulting report about the differences between 357 *first-shared-library* and *second-shared-library*, only display 358 the globally defined functions that got deleted from 359 *first-shared-library*. 360 361 * ``--changed-fns`` 362 363 In the resulting report about the differences between 364 *first-shared-library* and *second-shared-library*, only display 365 the changes in sub-types of the global functions defined in 366 *first-shared-library*. 367 368 * ``--added-fns`` 369 370 In the resulting report about the differences between 371 *first-shared-library* and *second-shared-library*, only display 372 the globally defined functions that were added to 373 *second-shared-library*. 374 375 * ``--deleted-vars`` 376 377 In the resulting report about the differences between 378 *first-shared-library* and *second-shared-library*, only display 379 the globally defined variables that were deleted from 380 *first-shared-library*. 381 382 * ``--changed-vars`` 383 384 In the resulting report about the differences between 385 *first-shared-library* and *second-shared-library*, only display 386 the changes in the sub-types of the global variables defined in 387 *first-shared-library* 388 389 * ``--added-vars`` 390 391 In the resulting report about the differences between 392 *first-shared-library* and *second-shared-library*, only display 393 the global variables that were added (defined) to 394 *second-shared-library*. 395 396 * ``--non-reachable-types|-t`` 397 398 Analyze and emit change reports for all the types of the binary, 399 including those that are not reachable from global functions and 400 variables. 401 402 This option might incur some serious performance degradation as 403 the number of types analyzed can be huge. However, if paired with 404 the ``--headers-dir{1,2}`` and/or ``header-file{1,2}`` options, 405 the additional non-reachable types analyzed are restricted to 406 those defined in public headers files, thus hopefully making the 407 performance hit acceptable. 408 409 Also, using this option alongside suppression specifications (by 410 also using the ``--suppressions`` option) might help keep the number of 411 analyzed types (and the potential performance degradation) in 412 control. 413 414 Note that without this option, only types that are reachable from 415 global functions and variables are analyzed, so the tool detects 416 and reports changes on these reachable types only. 417 418 * ``--no-added-syms`` 419 420 In the resulting report about the differences between 421 *first-shared-library* and *second-shared-library*, do not display 422 added functions or variables. Do not display added functions or 423 variables ELF symbols either. All other kinds of changes are 424 displayed unless they are explicitely forbidden by other options 425 on the command line. 426 427 * ``--no-linkage-name`` 428 429 In the resulting report, do not display the linkage names of 430 the added, removed, or changed functions or variables. 431 432 * ``--no-show-locs`` 433 434 Do not show information about where in the *second shared library* 435 the respective type was changed. 436 437 * ``--show-bytes`` 438 439 Show sizes and offsets in bytes, not bits. By default, sizes and 440 offsets are shown in bits. 441 442 * ``--show-bits`` 443 444 Show sizes and offsets in bits, not bytes. This option is 445 activated by default. 446 447 * ``--show-hex`` 448 449 Show sizes and offsets in hexadecimal base. 450 451 * ``--show-dec`` 452 453 Show sizes and offsets in decimal base. This option is activated 454 by default. 455 456 * ``--ignore-soname`` 457 458 Ignore differences in the SONAME when doing a comparison 459 460 * ``--no-show-relative-offset-changes`` 461 462 Without this option, when the offset of a data member changes, 463 the change report not only mentions the older and newer offset, 464 but it also mentions by how many bits the data member changes. 465 With this option, the latter is not shown. 466 467 * ``--no-unreferenced-symbols`` 468 469 In the resulting report, do not display change information about 470 function and variable symbols that are not referenced by any debug 471 information. Note that for these symbols not referenced by any 472 debug information, the change information displayed is either 473 added or removed symbols. 474 475 * ``--no-default-suppression`` 476 477 Do not load the :ref:`default suppression specification files 478 <abidiff_default_supprs_label>`. 479 480 * ``--suppressions | --suppr`` <*path-to-suppressions*> 481 482 Use a :ref:`suppression specification <suppr_spec_label>` file 483 located at *path-to-suppressions*. Note that this option can 484 appear multiple times on the command line. In that case, all of 485 the provided suppression specification files are taken into 486 account. 487 488 Please note that, by default, if this option is not provided, then 489 the :ref:`default suppression specification files 490 <abidiff_default_supprs_label>` are loaded . 491 492 * ``--drop`` <*regex*> 493 494 When reading the *first-shared-library* and 495 *second-shared-library* ELF input files, drop the globally defined 496 functions and variables which name match the regular expression 497 *regex*. As a result, no change involving these functions or 498 variables will be emitted in the diff report. 499 500 * ``--drop-fn`` <*regex*> 501 502 When reading the *first-shared-library* and 503 *second-shared-library* ELF input files, drop the globally defined 504 functions which name match the regular expression *regex*. As a 505 result, no change involving these functions will be emitted in the 506 diff report. 507 508 * ``--drop-var`` <*regex*> 509 510 When reading the *first-shared-library* and 511 *second-shared-library* ELF input files, drop the globally defined 512 variables matching a the regular expression *regex*. 513 514 * ``--keep`` <*regex*> 515 516 When reading the *first-shared-library* and 517 *second-shared-library* ELF input files, keep the globally defined 518 functions and variables which names match the regular expression 519 *regex*. All other functions and variables are dropped on the 520 floor and will thus not appear in the resulting diff report. 521 522 * ``--keep-fn`` <*regex*> 523 524 When reading the *first-shared-library* and 525 *second-shared-library* ELF input files, keep the globally defined 526 functions which name match the regular expression *regex*. All 527 other functions are dropped on the floor and will thus not appear 528 in the resulting diff report. 529 530 * ``--keep-var`` <*regex*> 531 532 When reading the *first-shared-library* and 533 *second-shared-library* ELF input files, keep the globally defined 534 which names match the regular expression *regex*. All other 535 variables are dropped on the floor and will thus not appear in the 536 resulting diff report. 537 538 * ``--harmless`` 539 540 In the diff report, display only the :ref:`harmless 541 <harmlesschangeconcept_label>` changes. By default, the harmless 542 changes are filtered out of the diff report keep the clutter to a 543 minimum and have a greater chance to spot real ABI issues. 544 545 * ``--no-harmful`` 546 547 In the diff report, do not display the :ref:`harmful 548 <harmfulchangeconcept_label>` changes. By default, only the 549 harmful changes are displayed in diff report. 550 551 * ``--redundant`` 552 553 In the diff report, do display redundant changes. A redundant 554 change is a change that has been displayed elsewhere in the 555 report. 556 557 * ``--no-redundant`` 558 559 In the diff report, do *NOT* display redundant changes. A 560 redundant change is a change that has been displayed elsewhere in 561 the report. This option is switched on by default. 562 563 * ``--no-architecture`` 564 565 Do not take architecture in account when comparing ABIs. 566 567 * ``--no-corpus-path`` 568 569 Do not emit the path attribute for the ABI corpus. 570 571 * ``--fail-no-debug-info`` 572 573 If no debug info was found, then this option makes the program to 574 fail. Otherwise, without this option, the program will attempt to 575 compare properties of the binaries that are not related to debug 576 info, like pure ELF properties. 577 578 * ``--leaf-changes-only|-l`` only show leaf changes, so don't show 579 impact analysis report. This option implies ``--redundant``. 580 581 The typical output of abidiff when comparing two binaries looks 582 like this :: 583 584 $ abidiff libtest-v0.so libtest-v1.so 585 Functions changes summary: 0 Removed, 1 Changed, 0 Added function 586 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 587 588 1 function with some indirect sub-type change: 589 590 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes: 591 parameter 1 of type 'C&' has sub-type changes: 592 in referenced type 'struct C' at test-v1.cc:7:1: 593 type size hasn't changed 594 1 data member change: 595 type of 'leaf* C::m0' changed: 596 in pointed to type 'struct leaf' at test-v1.cc:1:1: 597 type size changed from 32 to 64 bits 598 1 data member insertion: 599 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1 600 601 $ 602 603 So in that example the report emits information about how the data 604 member insertion change of "struct leaf" is reachable from 605 function "void fn(C&)". In other words, the report not only shows 606 the data member change on "struct leaf", but it also shows the 607 impact of that change on the function "void fn(C&)". 608 609 In abidiff parlance, the change on "struct leaf" is called a leaf 610 change. So the ``--leaf-changes-only --impacted-interfaces`` 611 options show, well, only the leaf change. And it goes like this: 612 :: 613 614 $ abidiff -l libtest-v0.so libtest-v1.so 615 'struct leaf' changed: 616 type size changed from 32 to 64 bits 617 1 data member insertion: 618 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1 619 620 one impacted interface: 621 function void fn(C&) 622 $ 623 624 Note how the report ends by showing the list of interfaces 625 impacted by the leaf change. 626 627 Now if you don't want to see that list of impacted interfaces, 628 then you can just avoid using the ``--impacted-interface`` option. 629 You can learn about that option below, in any case. 630 631 632 * ``--impacted-interfaces`` 633 634 When showing leaf changes, this option instructs abidiff to show 635 the list of impacted interfaces. This option is thus to be used 636 in addition the ``--leaf-changes-only`` option, otherwise, it's 637 ignored. 638 639 640 * ``--dump-diff-tree`` 641 642 After the diff report, emit a textual representation of the diff 643 nodes tree used by the comparison engine to represent the changed 644 functions and variables. That representation is emitted to the 645 error output for debugging purposes. Note that this diff tree is 646 relevant only to functions and variables that have some sub-type 647 changes. Added or removed functions and variables do not have any 648 diff nodes tree associated to them. 649 650 * ``--no-assume-odr-for-cplusplus`` 651 652 When analysing a binary originating from C++ code using `DWARF`_ 653 debug information, libabigail assumes the `One Definition Rule`_ 654 to speed-up the analysis. In that case, when several types have 655 the same name in the binary, they are assumed to all be equal. 656 657 This option disables that assumption and instructs libabigail to 658 actually actually compare the types to determine if they are 659 equal. 660 661 * ``--no-leverage-dwarf-factorization`` 662 663 When analysing a binary which `DWARF`_ debug information was 664 processed with the `DWZ`_ tool, the type information is supposed 665 to be already factorized. That context is used by libabigail to 666 perform some speed optimizations. 667 668 This option disables those optimizations. 669 670 * ``--no-change-categorization | -x`` 671 672 This option disables the categorization of changes into harmless 673 and harmful changes. Note that this categorization is a 674 pre-requisite for the filtering of changes so this option disables 675 that filtering. The goal of this option is to speed-up the 676 execution of the program for cases where the graph of changes is 677 huge and where the user is just interested in looking at, for 678 instance, leaf node changes without caring about their possible 679 impact on interfaces. In that case, this option would be used 680 along with the ``--leaf-changes-only`` one. 681 682 * ``--ctf`` 683 684 When comparing binaries, extract ABI information from `CTF`_ debug 685 information, if present. 686 687 * ``--btf`` 688 689 When comparing binaries, extract ABI information from `BTF`_ debug 690 information, if present. 691 692 * ``--stats`` 693 694 Emit statistics about various internal things. 695 696 * ``--verbose`` 697 698 Emit verbose logs about the progress of miscellaneous internal 699 things. 700 701.. _abidiff_return_value_label: 702 703Return values 704============= 705 706The exit code of the ``abidiff`` command is either 0 if the ABI of the 707binaries being compared are equal, or non-zero if they differ or if 708the tool encountered an error. 709 710In the later case, the exit code is a 8-bits-wide bit field in which 711each bit has a specific meaning. 712 713The first bit, of value 1, named ``ABIDIFF_ERROR`` means there was an 714error. 715 716The second bit, of value 2, named ``ABIDIFF_USAGE_ERROR`` means there 717was an error in the way the user invoked the tool. It might be set, 718for instance, if the user invoked the tool with an unknown command 719line switch, with a wrong number or argument, etc. If this bit is 720set, then the ``ABIDIFF_ERROR`` bit must be set as well. 721 722The third bit, of value 4, named ``ABIDIFF_ABI_CHANGE`` means the ABI 723of the binaries being compared are different. 724 725The fourth bit, of value 8, named ``ABIDIFF_ABI_INCOMPATIBLE_CHANGE`` 726means the ABI of the binaries compared are different in an 727incompatible way. If this bit is set, then the ``ABIDIFF_ABI_CHANGE`` 728bit must be set as well. If the ``ABIDIFF_ABI_CHANGE`` is set and the 729``ABIDIFF_INCOMPATIBLE_CHANGE`` is *NOT* set, then it means that the 730ABIs being compared might or might not be compatible. In that case, a 731human being needs to review the ABI changes to decide if they are 732compatible or not. 733 734Note that, at the moment, there are only a few kinds of ABI changes 735that would result in setting the flag ``ABIDIFF_ABI_INCOMPATIBLE_CHANGE``. 736Those ABI changes are either: 737 738 - the removal of the symbol of a function or variable that has been 739 defined and exported. 740 - the modification of the index of a member of a virtual function 741 table (for C++ programs and libraries). 742 743With time, when more ABI change patterns are found to *always* 744constitute incompatible ABI changes, we will adapt the code to 745recognize those cases and set the ``ABIDIFF_ABI_INCOMPATIBLE_CHANGE`` 746accordingly. So, if you find such patterns, please let us know. 747 748The remaining bits are not used for the moment. 749 750.. _abidiff_usage_example_label: 751 752Usage examples 753============== 754 755 1. Detecting a change in a sub-type of a function: :: 756 757 $ cat -n test-v0.cc 758 1 // Compile this with: 759 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 760 3 761 4 struct S0 762 5 { 763 6 int m0; 764 7 }; 765 8 766 9 void 767 10 foo(S0* /*parameter_name*/) 768 11 { 769 12 // do something with parameter_name. 770 13 } 771 $ 772 $ cat -n test-v1.cc 773 1 // Compile this with: 774 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 775 3 776 4 struct type_base 777 5 { 778 6 int inserted; 779 7 }; 780 8 781 9 struct S0 : public type_base 782 10 { 783 11 int m0; 784 12 }; 785 13 786 14 void 787 15 foo(S0* /*parameter_name*/) 788 16 { 789 17 // do something with parameter_name. 790 18 } 791 $ 792 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 793 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 794 $ 795 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so 796 Functions changes summary: 0 Removed, 1 Changed, 0 Added function 797 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 798 799 1 function with some indirect sub-type change: 800 801 [C]'function void foo(S0*)' has some indirect sub-type changes: 802 parameter 0 of type 'S0*' has sub-type changes: 803 in pointed to type 'struct S0': 804 size changed from 32 to 64 bits 805 1 base class insertion: 806 struct type_base 807 1 data member change: 808 'int S0::m0' offset changed from 0 to 32 809 $ 810 811 812 2. Detecting another change in a sub-type of a function: :: 813 814 $ cat -n test-v0.cc 815 1 // Compile this with: 816 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 817 3 818 4 struct S0 819 5 { 820 6 int m0; 821 7 }; 822 8 823 9 void 824 10 foo(S0& /*parameter_name*/) 825 11 { 826 12 // do something with parameter_name. 827 13 } 828 $ 829 $ cat -n test-v1.cc 830 1 // Compile this with: 831 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 832 3 833 4 struct S0 834 5 { 835 6 char inserted_member; 836 7 int m0; 837 8 }; 838 9 839 10 void 840 11 foo(S0& /*parameter_name*/) 841 12 { 842 13 // do something with parameter_name. 843 14 } 844 $ 845 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 846 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 847 $ 848 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so 849 Functions changes summary: 0 Removed, 1 Changed, 0 Added function 850 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 851 852 1 function with some indirect sub-type change: 853 854 [C]'function void foo(S0&)' has some indirect sub-type changes: 855 parameter 0 of type 'S0&' has sub-type changes: 856 in referenced type 'struct S0': 857 size changed from 32 to 64 bits 858 1 data member insertion: 859 'char S0::inserted_member', at offset 0 (in bits) 860 1 data member change: 861 'int S0::m0' offset changed from 0 to 32 862 863 864 $ 865 866 3. Detecting that functions got removed or added to a library: :: 867 868 $ cat -n test-v0.cc 869 1 // Compile this with: 870 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 871 3 872 4 struct S0 873 5 { 874 6 int m0; 875 7 }; 876 8 877 9 void 878 10 foo(S0& /*parameter_name*/) 879 11 { 880 12 // do something with parameter_name. 881 13 } 882 $ 883 $ cat -n test-v1.cc 884 1 // Compile this with: 885 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 886 3 887 4 struct S0 888 5 { 889 6 char inserted_member; 890 7 int m0; 891 8 }; 892 9 893 10 void 894 11 bar(S0& /*parameter_name*/) 895 12 { 896 13 // do something with parameter_name. 897 14 } 898 $ 899 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc 900 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc 901 $ 902 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so 903 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions 904 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable 905 906 1 Removed function: 907 'function void foo(S0&)' {_Z3fooR2S0} 908 909 1 Added function: 910 'function void bar(S0&)' {_Z3barR2S0} 911 912 $ 913 914 4. Comparing two sets of binaries that are passed on the command line: :: 915 916 $ abidiff --add-binaries1=file2-v1 \ 917 --add-binaries2=file2-v2,file2-v1 \ 918 --added-binaries-dir1 dir1 \ 919 --added-binaries-dir2 dir2 \ 920 file1-v1 file1-v2 921 922 Note that the files ``file2-v1``, and ``file2-v2`` are to be 923 found in ``dir1`` and ``dir2`` or in the current directory. 924 925 926 5. Compare two libraries and their dependencies: :: 927 928 $ abidiff --follow-dependencies \ 929 --added-binaries-dir1 /some/where \ 930 --added-binaries-dir2 /some/where/else \ 931 foo bar 932 933 This compares the set of binaries comprised by ``foo`` and its 934 dependencies against the set of binaries comprised by ``bar`` and 935 its dependencies. 936 937 938.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 939.. _DWARF: http://www.dwarfstd.org 940.. _CTF: https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf 941.. _BTF: https://docs.kernel.org/bpf/btf.html 942.. _ODR: https://en.wikipedia.org/wiki/One_Definition_Rule 943.. _One Definition Rule: https://en.wikipedia.org/wiki/One_Definition_Rule 944.. _DWZ: https://sourceware.org/dwz 945.. _Linux Kernel: https://kernel.org/ 946