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