1LIBABIGAIL(7) Libabigail LIBABIGAIL(7)
2
6 libabigail - Library to analyze and compare ELF ABIs
7
9 ABIGAIL stands for the Application Binary Interface Generic Analysis
10 and Instrumentation Library.
11 It’s a framework which aims at helping developers and software distrib‐
13 utors to spot some ABI-related issues like interface incompatibility in
14 ELF shared libraries by performing a static analysis of the ELF bina‐
15 ries at hand.
16 The type of interface incompatibilities that Abigail focuses on is re‐
18 lated to changes on the exported ELF functions and variables symbols,
19 as well as layout and size changes of data types of the functions and
20 variables exported by shared libraries.
21 In other words, if the return type of a function exported by a shared
23 library changes in an incompatible way from one version of a given
24 shared library to another, we want Abigail to help people catch that.
25 In more concrete terms, the Abigail framwork provides a shared library
27 named libabigail which exposes an API to parse a shared library in ELF
28 format (accompanied with its associated debug information in DWARF for‐
29 mat) build an internal representation of all the functions and vari‐
30 ables it exports, along with their types. Libabigail also builds an
31 internal representation of the ELF symbols of these functions and vari‐
32 ables. That information about these exported functions and variables
33 is roughly what we consider as being the ABI of the shared library, at
34 least, in the scope of Libabigail.
35 Aside of this internal representation, libabigail provides facilities
37 to perform deep comparisons of two ABIs. That is, it can compare the
38 types of two sets of functions or variables and represents the result
39 in a way that allows it to emit textual reports about the differences.
40 This allows us to write tools like abidiff that can compare the ABI of
42 two shared libraries and represent the result in a meaningful enough
43 way to help us spot ABI incompatibilities. There are several other
44 tools that are built using the Abigail framwork.
45
47 Overview
48 The upstream code repository of Libabigail contains several tools writ‐
49 ten using the library. They are maintained and released as part of the
50 project. All tools come with a bash-completion script.
51 Tools manuals
53 abidiff
54 abidiff compares the Application Binary Interfaces (ABI) of two shared
55 libraries in ELF format. It emits a meaningful report describing the
56 differences between the two ABIs.
57 This tool can also compare the textual representations of the ABI of
59 two ELF binaries (as emitted by abidw) or an ELF binary against a tex‐
60 tual representation of another ELF binary.
61 For a comprehensive ABI change report that includes changes about func‐
63 tion and variable sub-types, the two input shared libraries must be ac‐
64 companied with their debug information in DWARF format. Otherwise,
65 only ELF symbols that were added or removed are reported.
66 Invocation
68 abidiff [options] <first-shared-library> <second-shared-library>
69 Environment
71 abidiff loads two default suppression specifications files, merges
72 their content and use it to filter out ABI change reports that might be
73 considered as false positives to users.
74 • Default system-wide suppression specification file
76 It’s located by the optional environment variable LIBABIGAIL_DE‐
78 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
79 set, then abidiff tries to load the suppression file $libdir/libabi‐
80 gail/libabigail-default.abignore. If that file is not present, then
81 no default system-wide suppression specification file is loaded.
82 • Default user suppression specification file.
84 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
86 PRESSION_FILE. If that environment variable is not set, then abidiff
87 tries to load the suppression file $HOME/.abignore. If that file is
88 not present, then no default user suppression specification is
89 loaded.
90 Options
92 • --help | -h
93 Display a short help about the command and exit.
95 • --debug
97 In this mode, error messages are emitted for types which fail type
99 canonicalization.
100 This is an optional ebugging and sanity check option. To enable
102 it the libabigail package needs to be configured with the –en‐
103 able-debug-self-comparison option.
104 • --version | -v
106 Display the version of the program and exit.
108 • --debug-info-dir1 | --d1 <di-path1>
110 For cases where the debug information for first-shared-library is
112 split out into a separate file, tells abidiff where to find that
113 separate debug information file.
114 Note that di-path must point to the root directory under which the
116 debug information is arranged in a tree-like manner. Under Red
117 Hat based systems, that directory is usually <root>/usr/lib/debug.
118 This option can be provided several times with different root di‐
120 rectories. In that case, abidiff will potentially look into all
121 those root directories to find the split debug info for
122 first-shared-library.
123 Note also that this option is not mandatory for split debug infor‐
125 mation installed by your system’s package manager because then
126 abidiff knows where to find it.
127 • --debug-info-dir2 | --d2 <di-path2>
129 Like --debug-info-dir1, this options tells abidiff where to find
131 the split debug information for the second-shared-library file.
132 This option can be provided several times with different root di‐
134 rectories. In that case, abidiff will potentially look into all
135 those root directories to find the split debug info for sec‐
136 ond-shared-library.
137 • --headers-dir1 | --hd1 <headers-directory-path-1>
139 Specifies where to find the public headers of the first shared li‐
141 brary (or binary in general) that the tool has to consider. The
142 tool will thus filter out ABI changes on types that are not de‐
143 fined in public headers.
144 Note that several public header directories can be specified for
146 the first shared library. In that case the --headers-dir1 option
147 should be present several times on the command line, like in the
148 following example:
149 $ abidiff --headers-dir1 /some/path \
151 --headers-dir1 /some/other/path \
152 binary-version-1 binary-version-2
153 • --header-file1 | --hf1 <header-file-path-1>
155 Specifies where to find one public header of the first shared li‐
157 brary that the tool has to consider. The tool will thus filter
158 out ABI changes on types that are not defined in public headers.
159 • --headers-dir2 | --hd2 <headers-directory-path-1>
161 Specifies where to find the public headers of the second shared
163 library that the tool has to consider. The tool will thus filter
164 out ABI changes on types that are not defined in public headers.
165 Note that several public header directories can be specified for
167 the second shared library. In that case the --headers-dir2 option
168 should be present several times like in the following example:
169 $ abidiff --headers-dir2 /some/path \
171 --headers-dir2 /some/other/path \
172 binary-version-1 binary-version-2
173 • --header-file2 | --hf2 <header-file-path-2>
175 Specifies where to find one public header of the second shared li‐
177 brary 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 • --no-linux-kernel-mode
181 Without this option, if abidiff detects that the binaries it is
183 looking at are Linux Kernel binaries (either vmlinux or modules)
184 then it only considers functions and variables which ELF symbols
185 are listed in the __ksymtab and __ksymtab_gpl sections.
186 With this option, abidiff considers the binary as a non-special
188 ELF binary. It thus considers functions and variables which are
189 defined and exported in the ELF sense.
190 • --kmi-whitelist | -kaw <path-to-whitelist>
192 When analyzing a Linux kernel binary, this option points to the
194 white list of names of ELF symbols of functions and variables
195 which ABI must be considered. That white list is called a “Kernel
196 Module Interface white list”. This is because for the Kernel, we
197 don’t talk about ABI; we rather talk about the interface between
198 the Kernel and its module. Hence the term KMI rather than ABI.
199 Any other function or variable which ELF symbol are not present in
201 that white list will not be considered by this tool.
202 If this option is not provided – thus if no white list is provided
204 – then the entire KMI, that is, the set of all publicly defined
205 and exported functions and global variables by the Linux Kernel
206 binaries, is considered.
207 • --drop-private-types
209 This option is to be used with the --headers-dir1, header-file1,
211 header-file2 and --headers-dir2 options. With this option, types
212 that are NOT defined in the headers are entirely dropped from the
213 internal representation build by Libabigail to represent the ABI.
214 They thus don’t have to be filtered out from the final ABI change
215 report because they are not even present in Libabigail’s represen‐
216 tation.
217 Without this option however, those private types are kept in the
219 internal representation and later filtered out from the report.
220 This options thus potentially makes Libabigail consume less mem‐
222 ory. It’s meant to be mainly used to optimize the memory consump‐
223 tion of the tool on binaries with a lot of publicly defined and
224 exported types.
225 • --stat
227 Rather than displaying the detailed ABI differences between
229 first-shared-library and second-shared-library, just display some
230 summary statistics about these differences.
231 • --symtabs
233 Only display the symbol tables of the first-shared-library and
235 second-shared-library.
236 • --deleted-fns
238 In the resulting report about the differences between
240 first-shared-library and second-shared-library, only display the
241 globally defined functions that got deleted from first-shared-li‐
242 brary.
243 • --changed-fns
245 In the resulting report about the differences between
247 first-shared-library and second-shared-library, only display the
248 changes in sub-types of the global functions defined in
249 first-shared-library.
250 • --added-fns
252 In the resulting report about the differences between
254 first-shared-library and second-shared-library, only display the
255 globally defined functions that were added to second-shared-li‐
256 brary.
257 • --deleted-vars
259 In the resulting report about the differences between
261 first-shared-library and second-shared-library, only display the
262 globally defined variables that were deleted from first-shared-li‐
263 brary.
264 • --changed-vars
266 In the resulting report about the differences between
268 first-shared-library and second-shared-library, only display the
269 changes in the sub-types of the global variables defined in
270 first-shared-library
271 • --added-vars
273 In the resulting report about the differences between
275 first-shared-library and second-shared-library, only display the
276 global variables that were added (defined) to second-shared-li‐
277 brary.
278 • --non-reachable-types|-t
280 Analyze and emit change reports for all the types of the binary,
282 including those that are not reachable from global functions and
283 variables.
284 This option might incur some serious performance degradation as
286 the number of types analyzed can be huge. However, if paired with
287 the --headers-dir{1,2} and/or header-file{1,2} options, the addi‐
288 tional non-reachable types analyzed are restricted to those de‐
289 fined in public headers files, thus hopefully making the perfor‐
290 mance hit acceptable.
291 Also, using this option alongside suppression specifications (by
293 also using the --suppressions option) might help keep the number
294 of analyzed types (and the potential performance degradation) in
295 control.
296 Note that without this option, only types that are reachable from
298 global functions and variables are analyzed, so the tool detects
299 and reports changes on these reachable types only.
300 • --no-added-syms
302 In the resulting report about the differences between
304 first-shared-library and second-shared-library, do not display
305 added functions or variables. Do not display added functions or
306 variables ELF symbols either. All other kinds of changes are dis‐
307 played unless they are explicitely forbidden by other options on
308 the command line.
309 • --no-linkage-name
311 In the resulting report, do not display the linkage names of the
313 added, removed, or changed functions or variables.
314 • --no-show-locs
316 Do not show information about where in the second shared library
317 the respective type was changed.
318 • --show-bytes
320 Show sizes and offsets in bytes, not bits. By default, sizes and
322 offsets are shown in bits.
323 • --show-bits
325 Show sizes and offsets in bits, not bytes. This option is acti‐
327 vated by default.
328 • --show-hex
330 Show sizes and offsets in hexadecimal base.
332 • --show-dec
334 Show sizes and offsets in decimal base. This option is activated
336 by default.
337 • --no-show-relative-offset-changes
339 Without this option, when the offset of a data member changes, the
341 change report not only mentions the older and newer offset, but it
342 also mentions by how many bits the data member changes. With this
343 option, the latter is not shown.
344 • --no-unreferenced-symbols
346 In the resulting report, do not display change information about
348 function and variable symbols that are not referenced by any debug
349 information. Note that for these symbols not referenced by any
350 debug information, the change information displayed is either
351 added or removed symbols.
352 • --no-default-suppression
354 Do not load the default suppression specification files.
356 • --suppressions | --suppr <path-to-suppressions>
358 Use a suppression specification file located at path-to-suppres‐
360 sions. Note that this option can appear multiple times on the
361 command line. In that case, all of the provided suppression spec‐
362 ification files are taken into account.
363 Please note that, by default, if this option is not provided, then
365 the default suppression specification files are loaded .
366 • --drop <regex>
368 When reading the first-shared-library and second-shared-library
370 ELF input files, drop the globally defined functions and variables
371 which name match the regular expression regex. As a result, no
372 change involving these functions or variables will be emitted in
373 the diff report.
374 • --drop-fn <regex>
376 When reading the first-shared-library and second-shared-library
378 ELF input files, drop the globally defined functions which name
379 match the regular expression regex. As a result, no change in‐
380 volving these functions will be emitted in the diff report.
381 • --drop-var <regex>
383 When reading the first-shared-library and second-shared-library
385 ELF input files, drop the globally defined variables matching a
386 the regular expression regex.
387 • --keep <regex>
389 When reading the first-shared-library and second-shared-library
391 ELF input files, keep the globally defined functions and variables
392 which names match the regular expression regex. All other func‐
393 tions and variables are dropped on the floor and will thus not ap‐
394 pear in the resulting diff report.
395 • --keep-fn <regex>
397 When reading the first-shared-library and second-shared-library
399 ELF input files, keep the globally defined functions which name
400 match the regular expression regex. All other functions are
401 dropped on the floor and will thus not appear in the resulting
402 diff report.
403 • --keep-var <regex>
405 When reading the first-shared-library and second-shared-library
407 ELF input files, keep the globally defined which names match the
408 regular expression regex. All other variables are dropped on the
409 floor and will thus not appear in the resulting diff report.
410 • --harmless
412 In the diff report, display only the harmless changes. By de‐
414 fault, the harmless changes are filtered out of the diff report
415 keep the clutter to a minimum and have a greater chance to spot
416 real ABI issues.
417 • --no-harmful
419 In the diff report, do not display the harmful changes. By de‐
421 fault, only the harmful changes are displayed in diff report.
422 • --redundant
424 In the diff report, do display redundant changes. A redundant
426 change is a change that has been displayed elsewhere in the re‐
427 port.
428 • --no-redundant
430 In the diff report, do NOT display redundant changes. A redundant
432 change is a change that has been displayed elsewhere in the re‐
433 port. This option is switched on by default.
434 • --no-architecture
436 Do not take architecture in account when comparing ABIs.
438 • --no-corpus-path
440 Do not emit the path attribute for the ABI corpus.
442 • --fail-no-debug-info
444 If no debug info was found, then this option makes the program to
446 fail. Otherwise, without this option, the program will attempt to
447 compare properties of the binaries that are not related to debug
448 info, like pure ELF properties.
449 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
451 pact analysis report. This option implies --redundant.
452 The typical output of abidiff when comparing two binaries looks
454 like this
455 $ abidiff libtest-v0.so libtest-v1.so
457 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
458 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
459 1 function with some indirect sub-type change:
461 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
463 parameter 1 of type 'C&' has sub-type changes:
464 in referenced type 'struct C' at test-v1.cc:7:1:
465 type size hasn't changed
466 1 data member change:
467 type of 'leaf* C::m0' changed:
468 in pointed to type 'struct leaf' at test-v1.cc:1:1:
469 type size changed from 32 to 64 bits
470 1 data member insertion:
471 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
472 $
474 So in that example the report emits information about how the data
476 member insertion change of “struct leaf” is reachable from func‐
477 tion “void fn(C&)”. In other words, the report not only shows the
478 data member change on “struct leaf”, but it also shows the impact
479 of that change on the function “void fn(C&)”.
480 In abidiff parlance, the change on “struct leaf” is called a leaf
482 change. So the --leaf-changes-only --impacted-interfaces options
483 show, well, only the leaf change. And it goes like this:
484 $ abidiff -l libtest-v0.so libtest-v1.so
486 'struct leaf' changed:
487 type size changed from 32 to 64 bits
488 1 data member insertion:
489 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
490 one impacted interface:
492 function void fn(C&)
493 $
494 Note how the report ends by showing the list of interfaces im‐
496 pacted by the leaf change.
497 Now if you don’t want to see that list of impacted interfaces,
499 then you can just avoid using the --impacted-interface option.
500 You can learn about that option below, in any case.
501 • --impacted-interfaces
503 When showing leaf changes, this option instructs abidiff to show
505 the list of impacted interfaces. This option is thus to be used
506 in addition the --leaf-changes-only option, otherwise, it’s ig‐
507 nored.
508 • --dump-diff-tree
510 After the diff report, emit a textual representation of the diff
511 nodes tree used by the comparison engine to represent the
512 changed functions and variables. That representation is emitted
513 to the error output for debugging purposes. Note that this diff
514 tree is relevant only to functions and variables that have some
515 sub-type changes. Added or removed functions and variables do
516 not have any diff nodes tree associated to them.
517 • --stats
519 Emit statistics about various internal things.
521 • --verbose
523 Emit verbose logs about the progress of miscellaneous internal
525 things.
526 Return values
528 The exit code of the abidiff command is either 0 if the ABI of the bi‐
529 naries being compared are equal, or non-zero if they differ or if the
530 tool encountered an error.
531 In the later case, the exit code is a 8-bits-wide bit field in which
533 each bit has a specific meaning.
534 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
536 ror.
537 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
539 an error in the way the user invoked the tool. It might be set, for
540 instance, if the user invoked the tool with an unknown command line
541 switch, with a wrong number or argument, etc. If this bit is set, then
542 the ABIDIFF_ERROR bit must be set as well.
543 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
545 the binaries being compared are different.
546 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
548 the ABI of the binaries compared are different in an incompatible way.
549 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
550 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
551 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
552 or might not be compatible. In that case, a human being needs to re‐
553 view the ABI changes to decide if they are compatible or not.
554 Note that, at the moment, there are only a few kinds of ABI changes
556 that would result in setting the flag ABIDIFF_ABI_INCOMPATIBLE_CHANGE.
557 Those ABI changes are either:
558 • the removal of the symbol of a function or variable that has been
560 defined and exported.
561 • the modification of the index of a member of a virtual function
563 table (for C++ programs and libraries).
564 With time, when more ABI change patterns are found to always constitute
566 incompatible ABI changes, we will adapt the code to recognize those
567 cases and set the ABIDIFF_ABI_INCOMPATIBLE_CHANGE accordingly. So, if
568 you find such patterns, please let us know.
569 The remaining bits are not used for the moment.
571 Usage examples
573 1. Detecting a change in a sub-type of a function:
574 $ cat -n test-v0.cc
576 1 // Compile this with:
577 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
578 3
579 4 struct S0
580 5 {
581 6 int m0;
582 7 };
583 8
584 9 void
585 10 foo(S0* /*parameter_name*/)
586 11 {
587 12 // do something with parameter_name.
588 13 }
589 $
590 $ cat -n test-v1.cc
591 1 // Compile this with:
592 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
593 3
594 4 struct type_base
595 5 {
596 6 int inserted;
597 7 };
598 8
599 9 struct S0 : public type_base
600 10 {
601 11 int m0;
602 12 };
603 13
604 14 void
605 15 foo(S0* /*parameter_name*/)
606 16 {
607 17 // do something with parameter_name.
608 18 }
609 $
610 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
611 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
612 $
613 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
614 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
615 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
616 1 function with some indirect sub-type change:
618 [C]'function void foo(S0*)' has some indirect sub-type changes:
620 parameter 0 of type 'S0*' has sub-type changes:
621 in pointed to type 'struct S0':
622 size changed from 32 to 64 bits
623 1 base class insertion:
624 struct type_base
625 1 data member change:
626 'int S0::m0' offset changed from 0 to 32
627 $
628 2. Detecting another change in a sub-type of a function:
630 $ cat -n test-v0.cc
632 1 // Compile this with:
633 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
634 3
635 4 struct S0
636 5 {
637 6 int m0;
638 7 };
639 8
640 9 void
641 10 foo(S0& /*parameter_name*/)
642 11 {
643 12 // do something with parameter_name.
644 13 }
645 $
646 $ cat -n test-v1.cc
647 1 // Compile this with:
648 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
649 3
650 4 struct S0
651 5 {
652 6 char inserted_member;
653 7 int m0;
654 8 };
655 9
656 10 void
657 11 foo(S0& /*parameter_name*/)
658 12 {
659 13 // do something with parameter_name.
660 14 }
661 $
662 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
663 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
664 $
665 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
666 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
667 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
668 1 function with some indirect sub-type change:
670 [C]'function void foo(S0&)' has some indirect sub-type changes:
672 parameter 0 of type 'S0&' has sub-type changes:
673 in referenced type 'struct S0':
674 size changed from 32 to 64 bits
675 1 data member insertion:
676 'char S0::inserted_member', at offset 0 (in bits)
677 1 data member change:
678 'int S0::m0' offset changed from 0 to 32
679 $
682 3. Detecting that functions got removed or added to a library:
684 $ cat -n test-v0.cc
686 1 // Compile this with:
687 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
688 3
689 4 struct S0
690 5 {
691 6 int m0;
692 7 };
693 8
694 9 void
695 10 foo(S0& /*parameter_name*/)
696 11 {
697 12 // do something with parameter_name.
698 13 }
699 $
700 $ cat -n test-v1.cc
701 1 // Compile this with:
702 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
703 3
704 4 struct S0
705 5 {
706 6 char inserted_member;
707 7 int m0;
708 8 };
709 9
710 10 void
711 11 bar(S0& /*parameter_name*/)
712 12 {
713 13 // do something with parameter_name.
714 14 }
715 $
716 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
717 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
718 $
719 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
720 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
721 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
722 1 Removed function:
724 'function void foo(S0&)' {_Z3fooR2S0}
725 1 Added function:
727 'function void bar(S0&)' {_Z3barR2S0}
728 $
730 abipkgdiff
732 abipkgdiff compares the Application Binary Interfaces (ABI) of the ELF
733 binaries contained in two software packages. The software package for‐
734 mats currently supported are Deb, RPM, tar archives (either compressed
735 or not) and plain directories that contain binaries.
736 For a comprehensive ABI change report that includes changes about func‐
738 tion and variable sub-types, the two input packages must be accompanied
739 with their debug information packages that contain debug information in
740 DWARF format.
741 Invocation
743 abipkgdiff [option] <package1> <package2>
744 package1 and package2 are the packages that contain the binaries to be
746 compared.
747 Environment
749 abipkgdiff loads two default suppression specifications files, merges
750 their content and use it to filter out ABI change reports that might be
751 considered as false positives to users.
752 • Default system-wide suppression specification file
754 It’s located by the optional environment variable LIBABIGAIL_DE‐
756 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
757 set, then abipkgdiff tries to load the suppression file $lib‐
758 dir/libabigail/libabigail-default.abignore. If that file is not
759 present, then no default system-wide suppression specification file
760 is loaded.
761 • Default user suppression specification file.
763 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
765 PRESSION_FILE. If that environment variable is not set, then abip‐
766 kgdiff tries to load the suppression file $HOME/.abignore. If that
767 file is not present, then no default user suppression specification
768 is loaded.
769 In addition to those default suppression specification files, abip‐
771 kgdiff will also look inside the packages being compared and if it sees
772 a file that ends with the extension .abignore, then it will consider it
773 as a suppression specification and it will combine it to the default
774 suppression specification that might be already loaded.
775 The user might as well use the --suppressions option (that is docu‐
777 mented further below) to provide a suppression specification.
778 Options
780 • --help | -h
781 Display a short help about the command and exit.
783 • –version | -v
785 Display the version of the program and exit.
787 • --debug-info-pkg1 | --d1 <path>
789 For cases where the debug information for package1 is split out
791 into a separate file, tells abipkgdiff where to find that separate
792 debug information package.
793 Note that the debug info for package1 can have been split into
795 several different debug info packages. In that case, several in‐
796 stances of this options can be provided, along with those several
797 different debug info packages.
798 • --debug-info-pkg2 | --d2 <path>
800 For cases where the debug information for package2 is split out
802 into a separate file, tells abipkgdiff where to find that separate
803 debug information package.
804 Note that the debug info for package2 can have been split into
806 several different debug info packages. In that case, several in‐
807 stances of this options can be provided, along with those several
808 different debug info packages.
809 • --devel-pkg1 | --devel1 <path>
811 Specifies where to find the Development Package associated with
813 the first package to be compared. That Development Package at
814 path should at least contain header files in which public types
815 exposed by the libraries (of the first package to be compared) are
816 defined. When this option is provided, the tool filters out re‐
817 ports about ABI changes to types that are NOT defined in these
818 header files.
819 • --devel-pkg2 | --devel2 <path>
821 Specifies where to find the Development Package associated with
823 the second package to be compared. That Development Package at
824 path should at least contains header files in which public types
825 exposed by the libraries (of the second package to be compared)
826 are defined. When this option is provided, the tool filters out
827 reports about ABI changes to types that are NOT defined in these
828 header files.
829 • --drop-private-types
831 This option is to be used with the --devel-pkg1 and --devel-pkg2
833 options. With this option, types that are NOT defined in the
834 headers are entirely dropped from the internal representation
835 build by Libabigail to represent the ABI. They thus don’t have to
836 be filtered out from the final ABI change report because they are
837 not even present in Libabigail’s representation.
838 Without this option however, those private types are kept in the
840 internal representation and later filtered out from the report.
841 This options thus potentially makes Libabigail consume less mem‐
843 ory. It’s meant to be mainly used to optimize the memory consump‐
844 tion of the tool on binaries with a lot of publicly defined and
845 exported types.
846 • --dso-only
848 Compare ELF files that are shared libraries, only. Do not compare
850 executable files, for instance.
851 • --private-dso
853 By default, abipkgdiff does not compare DSOs that are private to
855 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
856 vertised in the “provides” property of the RPM.
857 This option instructs abipkgdiff to also compare DSOs that are NOT
859 advertised in the “provides” property of the RPM.
860 Please note that the fact that (by default) abipkgdiff skips pri‐
862 vate DSO is a feature that is available only for RPMs, at the mo‐
863 ment. We would happily accept patches adding that feature for
864 other package formats.
865 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
867 pact analysis report. This option implies --redundant
868 The typical output of abipkgdiff and abidiff when comparing two
870 binaries, that we shall call full impact report, looks like this
871 $ abidiff libtest-v0.so libtest-v1.so
873 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
874 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
875 1 function with some indirect sub-type change:
877 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
879 parameter 1 of type 'C&' has sub-type changes:
880 in referenced type 'struct C' at test-v1.cc:7:1:
881 type size hasn't changed
882 1 data member change:
883 type of 'leaf* C::m0' changed:
884 in pointed to type 'struct leaf' at test-v1.cc:1:1:
885 type size changed from 32 to 64 bits
886 1 data member insertion:
887 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
888 $
890 So in that example the report emits information about how the data
892 member insertion change of “struct leaf” is reachable from func‐
893 tion “void fn(C&)”. In other words, the report not only shows the
894 data member change on “struct leaf”, but it also shows the impact
895 of that change on the function “void fn(C&)”.
896 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
898 is called a leaf change. So the --leaf-changes-only --im‐
899 pacted-interfaces options show, well, only the leaf change. And
900 it goes like this:
901 $ abidiff -l libtest-v0.so libtest-v1.so
903 'struct leaf' changed:
904 type size changed from 32 to 64 bits
905 1 data member insertion:
906 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
907 one impacted interface:
909 function void fn(C&)
910 $
911 Note how the report ends up by showing the list of interfaces im‐
913 pacted by the leaf change. That’s the effect of the additional
914 --impacted-interfaces option.
915 Now if you don’t want to see that list of impacted interfaces,
917 then you can just avoid using the --impacted-interface option.
918 You can learn about that option below, in any case.
919 Please note that when comparing two Linux Kernel packages, it’s
921 this leaf changes report that is emitted, by default. The normal
922 so-called full impact report can be emitted with the option
923 --full-impact which is documented later below.
924 • --impacted-interfaces
926 When showing leaf changes, this option instructs abipkgdiff to
928 show the list of impacted interfaces. This option is thus to be
929 used in addition to the --leaf-changes-only option, or, when com‐
930 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
931 • --full-impact|-f
933 When comparing two Linux Kernel packages, this function instructs
935 abipkgdiff to emit the so-called full impact report, which is the
936 default report kind emitted by the abidiff tool:
937 $ abidiff libtest-v0.so libtest-v1.so
939 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
940 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
941 1 function with some indirect sub-type change:
943 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
945 parameter 1 of type 'C&' has sub-type changes:
946 in referenced type 'struct C' at test-v1.cc:7:1:
947 type size hasn't changed
948 1 data member change:
949 type of 'leaf* C::m0' changed:
950 in pointed to type 'struct leaf' at test-v1.cc:1:1:
951 type size changed from 32 to 64 bits
952 1 data member insertion:
953 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
954 $
956 • --non-reachable-types|-t
958 Analyze and emit change reports for all the types of the binary,
960 including those that are not reachable from global functions and
961 variables.
962 This option might incur some serious performance degradation as
964 the number of types analyzed can be huge. However, if paired with
965 the --devel-pkg{1,2} options, the additional non-reachable types
966 analyzed are restricted to those defined in the public headers
967 files carried by the referenced development packages, thus hope‐
968 fully making the performance hit acceptable.
969 Also, using this option alongside suppression specifications (by
971 also using the --suppressions option) might help keep the number
972 of analyzed types (and the potential performance degradation) in
973 control.
974 Note that without this option, only types that are reachable from
976 global functions and variables are analyzed, so the tool detects
977 and reports changes on these reachable types only.
978 • --redundant
980 In the diff reports, do display redundant changes. A redundant
981 change is a change that has been displayed elsewhere in a given
982 report.
983 • --harmless
985 In the diff report, display only the harmless changes. By de‐
987 fault, the harmless changes are filtered out of the diff report
988 keep the clutter to a minimum and have a greater chance to spot
989 real ABI issues.
990 • --no-linkage-name
992 In the resulting report, do not display the linkage names of the
994 added, removed, or changed functions or variables.
995 • --no-added-syms
997 Do not show the list of functions, variables, or any symbol that
999 was added.
1000 • --no-added-binaries
1002 Do not show the list of binaries that got added to the second
1004 package.
1005 Please note that the presence of such added binaries is not con‐
1007 sidered like an ABI change by this tool; as such, it doesn’t have
1008 any impact on the exit code of the tool. It does only have an in‐
1009 formational value. Removed binaries are, however, considered as
1010 an ABI change.
1011 • --no-abignore
1013 Do not search the package for the presence of suppression files.
1015 • --no-parallel
1017 By default, abipkgdiff will use all the processors it has avail‐
1019 able to execute concurrently. This option tells it not to extract
1020 packages or run comparisons in parallel.
1021 • --no-default-suppression
1023 Do not load the default suppression specification files.
1025 • --suppressions | --suppr <path-to-suppressions>
1027 Use a suppression specification file located at path-to-suppres‐
1029 sions. Note that this option can appear multiple times on the
1030 command line. In that case, all of the suppression specification
1031 files are taken into account.
1032 Please note that, by default, if this option is not provided, then
1034 the default suppression specification files are loaded .
1035 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
1037 When comparing two Linux kernel RPM packages, this option points
1039 to the white list of names of ELF symbols of functions and vari‐
1040 ables that must be compared for ABI changes. That white list is
1041 called a “Linux kernel ABI white list”.
1042 Any other function or variable which ELF symbol are not present in
1044 that white list will not be considered by the ABI comparison
1045 process.
1046 If this option is not provided – thus if no white list is provided
1048 – then the ABI of all publicly defined and exported functions and
1049 global variables by the Linux Kernel binaries are compared.
1050 Please note that if a white list package is given in parameter,
1052 this option handles it just fine, like if the –wp option was used.
1053 • --wp <path-to-whitelist-package>
1055 When comparing two Linux kernel RPM packages, this option points
1057 an RPM package containining several white lists of names of ELF
1058 symbols of functions and variables that must be compared for ABI
1059 changes. Those white lists are called “Linux kernel ABI white
1060 lists”.
1061 From the content of that white list package, this program then
1063 chooses the appropriate Linux kernel ABI white list to consider
1064 when comparing the ABI of Linux kernel binaries contained in the
1065 Linux kernel packages provided on the command line.
1066 That choosen Linux kernel ABI white list contains the list of
1068 names of ELF symbols of functions and variables that must be com‐
1069 pared for ABI changes.
1070 Any other function or variable which ELF symbol are not present in
1072 that white list will not be considered by the ABI comparison
1073 process.
1074 Note that this option can be provided twice (not mor than twice),
1076 specifying one white list package for each Linux Kernel package
1077 that is provided on the command line.
1078 If this option is not provided – thus if no white list is provided
1080 – then the ABI of all publicly defined and exported functions and
1081 global variables by the Linux Kernel binaries are compared.
1082 • --no-unreferenced-symbols
1084 In the resulting report, do not display change information about
1086 function and variable symbols that are not referenced by any debug
1087 information. Note that for these symbols not referenced by any
1088 debug information, the change information displayed is either
1089 added or removed symbols.
1090 • --no-show-locs
1092 Do not show information about where in the second shared library
1093 the respective type was changed.
1094 • --show-bytes
1096 Show sizes and offsets in bytes, not bits. By default, sizes and
1098 offsets are shown in bits.
1099 • --show-bits
1101 Show sizes and offsets in bits, not bytes. This option is acti‐
1103 vated by default.
1104 • --show-hex
1106 Show sizes and offsets in hexadecimal base.
1108 • --show-dec
1110 Show sizes and offsets in decimal base. This option is activated
1112 by default.
1113 • --no-show-relative-offset-changes
1115 Without this option, when the offset of a data member changes, the
1117 change report not only mentions the older and newer offset, but it
1118 also mentions by how many bits the data member changes. With this
1119 option, the latter is not shown.
1120 • --show-identical-binaries
1122 Show the names of the all binaries compared, including the bina‐
1123 ries whose ABI compare equal. By default, when this option is
1124 not provided, only binaries with ABI changes are mentionned in
1125 the output.
1126 • --fail-no-dbg
1128 Make the program fail and return a non-zero exit code if couldn’t
1130 read any of the debug information that comes from the debug info
1131 packages that were given on the command line. If no debug info
1132 package were provided on the command line then this option is not
1133 active.
1134 Note that the non-zero exit code returned by the program as a re‐
1136 sult of this option is the constant ABIDIFF_ERROR. To know the
1137 numerical value of that constant, please refer to the exit code
1138 documentation.
1139 • --keep-tmp-files
1141 Do not erase the temporary directory files that are created during
1143 the execution of the tool.
1144 • --verbose
1146 Emit verbose progress messages.
1148 • self-check
1150 This is used to test the underlying Libabigail library. When in
1152 used, the command expects only on input package, along with its
1153 associated debug info packages. The command then compares each
1154 binary inside the package against its own ABIXML representation.
1155 The result of the comparison should yield the empty set if Libabi‐
1156 gail behaves correctly. Otherwise, it means there is an issue
1157 that ought to be fixed. This option is used by people interested
1158 in Libabigail development for regression testing purposes. Here
1159 is an example of the use of this option:
1160 $ 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
1162 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
1163 $
1164 Return value
1166 The exit code of the abipkgdiff command is either 0 if the ABI of the
1167 binaries compared are equal, or non-zero if they differ or if the tool
1168 encountered an error.
1169 In the later case, the value of the exit code is the same as for the
1171 abidiff tool.
1172 kmidiff
1174 kmidiff compares the binary Kernel Module Interfaces of two Linux Ker‐
1175 nel trees. The binary KMI is the interface that the Linux Kernel ex‐
1176 poses to its modules. The trees we are interested in here are the re‐
1177 sult of the build of the Linux Kernel source tree.
1178 General approach
1180 And example of how to build your kernel if you want to compare it to
1181 another one using kmidiff is:
1182 git clone -b v4.5 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux/v4.5
1184 cd linux/v4.5
1185 make allyesconfig all
1186 Then install the modules into a directory, for instance, the build/mod‐
1188 ules sub-directory of the your kernel source tree:
1189 mkdir build/modules
1191 make modules_install INSTALL_MOD_DIR=build/modules
1192 Then construct a list of interfaces exported by the kernel, that you
1194 want to compare:
1195 cat > kmi-whitelist << EOF
1197 [kernel_4.5_kmi_whitelist]
1198 init_task
1199 schedule
1200 dev_queue_xmit
1201 __kmalloc
1202 printk
1203 EOF
1204 Suppose you’ve done something similar for the v4.6 branch of the Linux
1206 kernel, you now have these two directories: linux/v4.5 and linux/v4.6.
1207 Their modules are present under the directories linux/v4.5/build/mod‐
1208 ules and linux/v4.6/build/modules.
1209 To Comparing their KMI kmidiff needs to know where to find the vmlinux
1211 binaries and their associated modules. Here would be what the command
1212 line looks like:
1213 kmidiff \
1215 --kmi-whitelist linux/v4.6/kmi-whitelist \
1216 --vmlinux1 linux/v4.5/vmlinux \
1217 --vmlinux2 linux/v4.6/vmlinux \
1218 linux/v4.5/build/modules \
1219 linux/v4.6/build/modules
1220 Invocation
1222 More generally, kmidiff is invoked under the form:
1223 kmidiff [options] <first-modules-dir> <second-modules-dir>
1225 Environment
1227 By default, kmidiff compares all the interfaces (exported functions and
1228 variables) between the Kernel and its modules. In practice, though,
1229 users want to compare a subset of the those interfaces.
1230 Users can then define a “white list” of the interfaces to compare.
1232 Such a white list is a just a file in the “INI” format that looks like:
1233 [kernel_version_x86_64_whitelist]
1235 function1_name
1236 function2_name
1237 global_variable1_name
1238 ....
1239 Note that the name of the section (the name that is between the two
1241 brackets) of that INI file just has to end with the string “whitelist”.
1242 So you can define the name you want, for instance [ker‐
1243 nel_46_x86_64_whitelist].
1244 Then each line of that whitelist file is the name of an exported func‐
1246 tion or variable. Only those interfaces along with the types reachable
1247 from their signatures are going to be compared by kmidiff recursively.
1248 Note that kmidiff compares the interfaces exported by the vmlinux bi‐
1250 nary and by the all of the compiled modules.
1251 Options
1253 • --help | -h
1254 Display a short help about the command and exit.
1256 • --version | -v
1258 Display the version of the program and exit.
1260 • --verbose
1262 Display some verbose messages while executing.
1264 • --debug-info-dir1 | --d1 <di-path1>
1266 For cases where the debug information for the binaries of the
1268 first Linux kernel is split out into separate files, tells kmidiff
1269 where to find those separate debug information files.
1270 Note that di-path must point to the root directory under which the
1272 debug information is arranged in a tree-like manner. Under Red
1273 Hat based systems, that directory is usually <root>/usr/lib/debug.
1274 • --debug-info-dir2 | --d2 <di-path2>
1276 Like --debug-info-dir1, this options tells kmidiff where to find
1278 the split debug information for the binaries of the second Linux
1279 kernel.
1280 • --vmlinux1 | --l1 <path-to-first-vmlinux>
1282 Sets the path to the first vmlinux binary to consider. This has
1284 to be the uncompressed vmlinux binary compiled with debug info.
1285 • --vmlinux2 | --l2 <path-to-first-vmlinux>
1287 Sets the path to the second vmlinux binary to consider. This has
1289 to be the uncompressed vmlinux binary compiled with debug info.
1290 • --kmi-whitelist | -w <path-to-interface-whitelist>
1292 Set the path to the white list of interfaces to compare while com‐
1294 paring the Kernel Module Interface of the first kernel against the
1295 one of the second kernel.
1296 If this option is not provided, all the exported interfaces of the
1298 two kernels are compared. That takes a lot of times and is not
1299 necessarily meaningful because many interface are probably meant
1300 to see their reachable types change.
1301 So please, make sure you always use this option unless you really
1303 know what you are doing.
1304 • --suppressions | --suppr <path-to-suppressions>
1306 Use a suppression specification file located at path-to-suppres‐
1308 sions. Note that this option can appear multiple times on the
1309 command line. In that case, all of the provided suppression spec‐
1310 ification files are taken into account.
1311 Please note that, by default, if this option is not provided, then
1313 the default suppression specification files are loaded .
1314 • --impacted-interfaces | -i
1316 Tell what interfaces got impacted by each individual ABI change.
1318 • --full-impact | -f
1320 Emit a change report that shows the full impact of each change on
1322 exported interfaces. This is the default kind of report emitted
1323 by tools like abidiff or abipkgdiff.
1324 • --show-bytes
1326 Show sizes and offsets in bytes, not bits. This option is acti‐
1328 vated by default.
1329 • --show-bits
1331 Show sizes and offsets in bits, not bytes. By default, sizes and
1333 offsets are shown in bytes.
1334 • --show-hex
1336 Show sizes and offsets in hexadecimal base. This option is acti‐
1338 vated by default.
1339 • --show-dec
1341 Show sizes and offsets in decimal base.
1343 abidw
1345 abidw reads a shared library in ELF format and emits an XML representa‐
1346 tion of its ABI to standard output. The emitted representation in‐
1347 cludes all the globally defined functions and variables, along with a
1348 complete representation of their types. It also includes a representa‐
1349 tion of the globally defined ELF symbols of the file. The input shared
1350 library must contain associated debug information in DWARF format.
1351 When given the --linux-tree option, this program can also handle a
1353 Linux kernel tree. That is, a directory tree that contains both the
1354 vmlinux binary and Linux kernel modules. It analyses those Linux ker‐
1355 nel binaries and emits an XML representation of the interface between
1356 the kernel and its module, to standard output. In this case, we don’t
1357 call it an ABI, but a KMI (Kernel Module Interface). The emitted KMI
1358 includes all the globally defined functions and variables, along with a
1359 complete representation of their types. The input binaries must con‐
1360 tain associated debug information in DWARF format.
1361 Invocation
1363 abidw [options] [<path-to-elf-file>]
1364 Options
1366 • --help | -h
1367 Display a short help about the command and exit.
1369 • –version | -v
1371 Display the version of the program and exit.
1373 • --debug-info-dir | -d <dir-path>
1375 In cases where the debug info for path-to-elf-file is in a sepa‐
1377 rate file that is located in a non-standard place, this tells
1378 abidw where to look for that debug info file.
1379 Note that dir-path must point to the root directory under which
1381 the debug information is arranged in a tree-like manner. Under
1382 Red Hat based systems, that directory is usually
1383 <root>/usr/lib/debug.
1384 This option can be provided several times with different root di‐
1386 rectories. In that case, abidw will potentially look into all
1387 those root directories to find the split debug info for the elf
1388 file.
1389 Note that this option is not mandatory for split debug information
1391 installed by your system’s package manager because then abidw
1392 knows where to find it.
1393 • --out-file <file-path>
1395 This option instructs abidw to emit the XML representation of
1397 path-to-elf-file into the file file-path, rather than emitting it
1398 to its standard output.
1399 • --noout
1401 This option instructs abidw to not emit the XML representation of
1403 the ABI. So it only reads the ELF and debug information, builds
1404 the internal representation of the ABI and exits. This option is
1405 usually useful for debugging purposes.
1406 • --no-corpus-path
1408 Do not emit the path attribute for the ABI corpus.
1410 • --suppressions | suppr <path-to-suppression-specifications-file>
1412 Use a suppression specification file located at path-to-suppres‐
1414 sion-specifications-file. Note that this option can appear multi‐
1415 ple times on the command line. In that case, all of the provided
1416 suppression specification files are taken into account. ABI arti‐
1417 facts matched by the suppression specifications are suppressed
1418 from the output of this tool.
1419 • --kmi-whitelist | -kaw <path-to-whitelist>
1421 When analyzing a Linux kernel binary, this option points to the
1423 white list of names of ELF symbols of functions and variables
1424 which ABI must be written out. That white list is called a ” Ker‐
1425 nel Module Interface white list”. This is because for the Kernel,
1426 we don’t talk about the ABI; we rather talk about the interface
1427 between the Kernel and its module. Hence the term KMI rather than
1428 ABI
1429 Any other function or variable which ELF symbol are not present in
1431 that white list will not be considered by the KMI writing process.
1432 If this option is not provided – thus if no white list is provided
1434 – then the entire KMI, that is, all publicly defined and exported
1435 functions and global variables by the Linux Kernel binaries is
1436 emitted.
1437 • --linux-tree | --lt
1439 Make abidw to consider the input path as a path to a directory
1441 containing the vmlinux binary as several kernel modules binaries.
1442 In that case, this program emits the representation of the Kernel
1443 Module Interface (KMI) on the standard output.
1444 Below is an example of usage of abidw on a Linux Kernel tree.
1446 First, checkout a Linux kernel source tree and build it. Then in‐
1448 stall the kernel modules in a directory somewhere. Copy the vm‐
1449 linux binary into that directory too. And then serialize the KMI
1450 of that kernel to disk, using abidw:
1451 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
1453 $ cd linux && git checkout v4.5
1454 $ make allyesconfig all
1455 $ mkdir build-output
1456 $ make INSTALL_MOD_PATH=./build-output modules_install
1457 $ cp vmlinux build-output/modules/4.5.0
1458 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
1459 • --headers-dir | --hd <headers-directory-path-1>
1461 Specifies where to find the public headers of the binary that the
1463 tool has to consider. The tool will thus filter out types that
1464 are not defined in public headers.
1465 Note that several public header directories can be specified for
1467 the binary to consider. In that case the --header-dir option
1468 should be present several times on the command line, like in the
1469 following example:
1470 $ abidw --header-dir /some/path \
1472 --header-dir /some/other/path \
1473 binary > binary.abi
1474 • --header-file | --hf <header-file-path>
1476 Specifies where to find one of the public headers of the abi file
1478 that the tool has to consider. The tool will thus filter out
1479 types that are not defined in public headers.
1480 • --drop-private-types
1482 This option is to be used with the --headers-dir and/or
1484 header-file options. With this option, types that are NOT defined
1485 in the headers are entirely dropped from the internal representa‐
1486 tion build by Libabigail to represent the ABI and will not end up
1487 in the abi XML file.
1488 • --no-elf-needed
1490 Do not include the list of DT_NEEDED dependency names in the cor‐
1492 pus.
1493 • --drop-undefined-syms
1495 With this option functions or variables for which the (exported)
1497 ELF symbol is undefined are dropped from the internal representa‐
1498 tion build by Libabigail to represent the ABI and will not end up
1499 in the abi XML file.
1500 • --no-linux-kernel-mode
1502 Without this option, if abipkgiff detects that the binaries it is
1504 looking at are Linux Kernel binaries (either vmlinux or modules)
1505 then it only considers functions and variables which ELF symbols
1506 are listed in the __ksymtab and __ksymtab_gpl sections.
1507 With this option, abipkgdiff considers the binary as a non-special
1509 ELF binary. It thus considers functions and variables which are
1510 defined and exported in the ELF sense.
1511 • --check-alternate-debug-info <elf-path>
1513 If the debug info for the file elf-path contains a reference to an
1515 alternate debug info file, abidw checks that it can find that al‐
1516 ternate debug info file. In that case, it emits a meaningful suc‐
1517 cess message mentioning the full path to the alternate debug info
1518 file found. Otherwise, it emits an error code.
1519 • --no-show-locs
1521 In the emitted ABI representation, do not show file, line or
1522 column where ABI artifacts are defined.
1523 • --no-parameter-names
1525 In the emitted ABI representation, do not show names of function
1527 parameters, just the types.
1528 • --no-write-default-sizes
1530 In the XML ABI representation, do not write the size-in-bits for
1532 pointer type definitions, reference type definitions, function
1533 declarations and function types when they are equal to the default
1534 address size of the translation unit. Note that libabigail before
1535 1.8 will not set the default size and will interpret types without
1536 a size-in-bits attribute as zero sized.
1537 • --type-id-style <sequence``|``hash>
1539 This option controls how types are idenfied in the generated XML
1541 files. The default sequence style just numbers (with type-id- as
1542 prefix) the types in the order they are encountered. The hash
1543 style uses a (stable, portable) hash of libabigail’s internal type
1544 names and is intended to make the XML files easier to diff.
1545 • --check-alternate-debug-info-base-name <elf-path>
1547 Like --check-alternate-debug-info, but in the success message,
1549 only mention the base name of the debug info file; not its full
1550 path.
1551 • --load-all-types
1553 By default, libabigail (and thus abidw) only loads types that are
1555 reachable from functions and variables declarations that are pub‐
1556 licly defined and exported by the binary. So only those types are
1557 present in the output of abidw. This option however makes abidw
1558 load all the types defined in the binaries, even those that are
1559 not reachable from public declarations.
1560 • --abidiff
1562 Load the ABI of the ELF binary given in argument, save it in
1563 libabigail’s XML format in a temporary file; read the ABI from
1564 the temporary XML file and compare the ABI that has been read
1565 back against the ABI of the ELF binary given in argument. The
1566 ABIs should compare equal. If they don’t, the program emits a
1567 diagnostic and exits with a non-zero code.
1568 This is a debugging and sanity check option.
1570 • --debug-abidiff
1572 Same as --abidiff but in debug mode. In this mode, error mes‐
1574 sages are emitted for types which fail type canonicalization.
1575 This is an optional debugging and sanity check option. To en‐
1577 able it the libabigail package needs to be configured with the
1578 –enable-debug-self-comparison option.
1579 • --annotate
1581 Annotate the ABIXML output with comments above most elements.
1582 The comments are made of the pretty-printed form types, declara‐
1583 tion or even ELF symbols. The purpose is to make the ABIXML
1584 output more human-readable for debugging or documenting pur‐
1585 poses.
1586 • --stats
1588 Emit statistics about various internal things.
1590 • --verbose
1592 Emit verbose logs about the progress of miscellaneous internal
1594 things.
1595 Notes
1597 Alternate debug info files
1598 As of the version 4 of the DWARF specification, Alternate debug infor‐
1599 mation is a GNU extension to the DWARF specification. It has however
1600 been proposed for inclusion into the upcoming version 5 of the DWARF
1601 standard. You can read more about the GNU extensions to the DWARF
1602 standard here.
1603 abicompat
1605 abicompat checks that an application that links against a given shared
1606 library is still ABI compatible with a subsequent version of that li‐
1607 brary. If the new version of the library introduces an ABI incompati‐
1608 bility, then abicompat hints the user at what exactly that incompati‐
1609 bility is.
1610 Invocation
1612 abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
1613 Options
1615 • --help
1616 Display a short help about the command and exit.
1618 • –version | -v
1620 Display the version of the program and exit.
1622 • --list-undefined-symbols | -u
1624 Display the list of undefined symbols of the application and exit.
1626 • --show-base-names | -b
1628 In the resulting report emitted by the tool, this option makes the
1630 application and libraries be referred to by their base names only;
1631 not by a full absolute name. This can be useful for use in
1632 scripts that wants to compare names of the application and li‐
1633 braries independently of what their directory names are.
1634 • --app-debug-info-dir | --appd <path-to-app-debug-info-directory>
1636 Set the path to the directory under which the debug information of
1638 the application is supposed to be laid out. This is useful for
1639 application binaries for which the debug info is in a separate set
1640 of files.
1641 • --lib-debug-info-dir1 | --libd1 <path-to-lib1-debug-info>
1643 Set the path to the directory under which the debug information of
1645 the first version of the shared library is supposed to be laid
1646 out. This is useful for shared library binaries for which the de‐
1647 bug info is in a separate set of files.
1648 • --lib-debug-info-dir2 | --libd2 <path-to-lib1-debug-info>
1650 Set the path to the directory under which the debug information of
1652 the second version of the shared library is supposed to be laid
1653 out. This is useful for shared library binaries for which the de‐
1654 bug info is in a separate set of files.
1655 • --suppressions | --suppr <path-to-suppressions>
1657 Use a suppression specification file located at path-to-suppres‐
1659 sions. Note that this option can appear multiple times on the
1660 command line; all the suppression specification files are then
1661 taken into account.
1662 • --no-show-locs
1664 Do not show information about where in the second shared library
1665 the respective type was changed.
1666 • --weak-mode
1668 This triggers the weak mode of abicompat. In this mode, only one
1670 version of the library is required. That is, abicompat is invoked
1671 like this:
1672 abicompat --weak-mode <the-application> <the-library>
1674 Note that the --weak-mode option can even be omitted if only one
1676 version of the library is given, along with the application; in
1677 that case, abicompat automatically switches to operate in weak
1678 mode:
1679 abicompat <the-application> <the-library>
1681 In this weak mode, the types of functions and variables exported
1683 by the library and consumed by the application (as in, the symbols
1684 of the these functions and variables are undefined in the applica‐
1685 tion and are defined and exported by the library) are compared to
1686 the version of these types as expected by the application. And if
1687 these two versions of types are different, abicompat tells the
1688 user what the differences are.
1689 In other words, in this mode, abicompat checks that the types of
1691 the functions and variables exported by the library mean the same
1692 thing as what the application expects, as far as the ABI is con‐
1693 cerned.
1694 Note that in this mode, abicompat doesn’t detect exported func‐
1696 tions or variables (symbols) that are expected by the application
1697 but that are removed from the library. That is why it is called
1698 weak mode.
1699 Return values
1701 The exit code of the abicompat command is either 0 if the ABI of the
1702 binaries being compared are equal, or non-zero if they differ or if the
1703 tool encountered an error.
1704 In the later case, the exit code is a 8-bits-wide bit field in which
1706 each bit has a specific meaning.
1707 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
1709 ror.
1710 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
1712 an error in the way the user invoked the tool. It might be set, for
1713 instance, if the user invoked the tool with an unknown command line
1714 switch, with a wrong number or argument, etc. If this bit is set, then
1715 the ABIDIFF_ERROR bit must be set as well.
1716 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
1718 the binaries being compared are different.
1719 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
1721 the ABI of the binaries compared are different in an incompatible way.
1722 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
1723 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
1724 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
1725 or might not be compatible. In that case, a human being needs to re‐
1726 view the ABI changes to decide if they are compatible or not.
1727 The remaining bits are not used for the moment.
1729 Usage examples
1731 • Detecting a possible ABI incompatibility in a new shared library
1732 version:
1733 $ cat -n test0.h
1735 1 struct foo
1736 2 {
1737 3 int m0;
1738 4
1739 5 foo()
1740 6 : m0()
1741 7 {}
1742 8 };
1743 9
1744 10 foo*
1745 11 first_func();
1746 12
1747 13 void
1748 14 second_func(foo&);
1749 15
1750 16 void
1751 17 third_func();
1752 $
1753 $ cat -n test-app.cc
1755 1 // Compile with:
1756 2 // g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
1757 3
1758 4 #include "test0.h"
1759 5
1760 6 int
1761 7 main()
1762 8 {
1763 9 foo* f = first_func();
1764 10 second_func(*f);
1765 11 return 0;
1766 12 }
1767 $
1768 $ cat -n test0.cc
1770 1 // Compile this with:
1771 2 // g++ -g -Wall -shared -o libtest-0.so test0.cc
1772 3
1773 4 #include "test0.h"
1774 5
1775 6 foo*
1776 7 first_func()
1777 8 {
1778 9 foo* f = new foo();
1779 10 return f;
1780 11 }
1781 12
1782 13 void
1783 14 second_func(foo&)
1784 15 {
1785 16 }
1786 17
1787 18 void
1788 19 third_func()
1789 20 {
1790 21 }
1791 $
1792 $ cat -n test1.h
1794 1 struct foo
1795 2 {
1796 3 int m0;
1797 4 char m1; /* <-- a new member got added here! */
1798 5
1799 6 foo()
1800 7 : m0(),
1801 8 m1()
1802 9 {}
1803 10 };
1804 11
1805 12 foo*
1806 13 first_func();
1807 14
1808 15 void
1809 16 second_func(foo&);
1810 17
1811 18 void
1812 19 third_func();
1813 $
1814 $ cat -n test1.cc
1816 1 // Compile this with:
1817 2 // g++ -g -Wall -shared -o libtest-1.so test1.cc
1818 3
1819 4 #include "test1.h"
1820 5
1821 6 foo*
1822 7 first_func()
1823 8 {
1824 9 foo* f = new foo();
1825 10 return f;
1826 11 }
1827 12
1828 13 void
1829 14 second_func(foo&)
1830 15 {
1831 16 }
1832 17
1833 18 /* Let's comment out the definition of third_func()
1834 19 void
1835 20 third_func()
1836 21 {
1837 22 }
1838 23 */
1839 $
1840 • Compile the first and second versions of the libraries:
1842 libtest-0.so and libtest-1.so:
1843 $ g++ -g -Wall -shared -o libtest-0.so test0.cc
1845 $ g++ -g -Wall -shared -o libtest-1.so test1.cc
1846 • Compile the application and link it against the first version of
1848 the library, creating the test-app binary:
1849 $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
1851 • Now, use abicompat to see if libtest-1.so is ABI compatible with
1853 app, with respect to the ABI of libtest-0.so:
1854 $ abicompat test-app libtest-0.so libtest-1.so
1856 ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
1857 Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
1858 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1859 2 functions with some indirect sub-type change:
1861 [C]'function foo* first_func()' has some indirect sub-type changes:
1863 return type changed:
1864 in pointed to type 'struct foo':
1865 size changed from 32 to 64 bits
1866 1 data member insertion:
1867 'char foo::m1', at offset 32 (in bits)
1868 [C]'function void second_func(foo&)' has some indirect sub-type changes:
1869 parameter 0 of type 'foo&' has sub-type changes:
1870 referenced type 'struct foo' changed, as reported earlier
1871 $
1873 • Now use the weak mode of abicompat, that is, providing just the
1875 application and the new version of the library:
1876 $ abicompat --weak-mode test-app libtest-1.so
1878 functions defined in library
1879 'libtest-1.so'
1880 have sub-types that are different from what application
1881 'test-app'
1882 expects:
1883 function foo* first_func():
1885 return type changed:
1886 in pointed to type 'struct foo':
1887 size changed from 32 to 64 bits
1888 1 data member insertion:
1889 'char foo::m1', at offset 32 (in bits)
1890 $
1892 abilint
1894 abilint parses the native XML representation of an ABI as emitted by
1895 abidw. Once it has parsed the XML representation of the ABI, abilint
1896 builds and in-memory model from it. It then tries to save it back to
1897 an XML form, to standard output. If that read-write operation succeeds
1898 chances are the input XML ABI representation is meaningful.
1899 Note that the main intent of this tool to help debugging issues in the
1901 underlying Libabigail library.
1902 Note also that abilint can also read an ELF input file, build the
1904 in-memory model for its ABI, and serialize that model back into XML to
1905 standard output. In that case, the ELF input file must be accompanied
1906 with its debug information in the DWARF format.
1907 Invocation
1909 abilint [options] [<abi-file1>]
1910 Options
1912 • --help
1913 Display a short help message and exits.
1915 • –version | -v
1917 Display the version of the program and exit.
1919 • --debug-info-dir <path>
1921 When reading an ELF input file which debug information is split
1923 out into a separate file, this options tells abilint where to find
1924 that separate debug information file.
1925 Note that path must point to the root directory under which the
1927 debug information is arranged in a tree-like manner. Under Red
1928 Hat based systems, that directory is usually <root>/usr/lib/debug.
1929 Note also that this option is not mandatory for split debug infor‐
1931 mation installed by your system’s package manager because then
1932 abidiff knows where to find it.
1933 • --diff
1935 For XML inputs, perform a text diff between the input and the mem‐
1937 ory model saved back to disk. This can help to spot issues in the
1938 handling of the XML format by the underlying Libabigail library.
1939 • --noout
1941 Do not display anything on standard output. The return code of
1943 the command is the only way to know if the command succeeded.
1944 • --suppressions | suppr <path-to-suppression-specifications-file>
1946 Use a suppression specification file located at path-to-suppres‐
1948 sion-specifications-file. Note that this option can appear multi‐
1949 ple times on the command line. In that case, all of the provided
1950 suppression specification files are taken into account. ABI arti‐
1951 facts matched by the suppression specifications are suppressed
1952 from the output of this tool.
1953 • --headers-dir | --hd <headers-directory-path-1>
1955 Specifies where to find the public headers of the first shared li‐
1957 brary that the tool has to consider. The tool will thus filter
1958 out types that are not defined in public headers.
1959 • --header-file | --hf <header-file-path>
1961 Specifies where to find one of the public headers of the abi file
1963 that the tool has to consider. The tool will thus filter out
1964 types that are not defined in public headers.
1965 • --stdin | --
1967 Read the input content from standard input.
1969 • --tu
1971 Expect the input XML to represent a single translation unit.
1973 fedabipkgdiff
1975 fedabipkgdiff compares the ABI of shared libraries in Fedora packages.
1976 It’s a convenient way to do so without having to manually download
1977 packages from the Fedora Build System.
1978 fedabipkgdiff knows how to talk with the Fedora Build System to find
1980 the right packages versions, their associated debug information and de‐
1981 velopment packages, download them, compare their ABI locally, and re‐
1982 port about the possible ABI changes.
1983 Note that by default, this tool reports ABI changes about types that
1985 are defined in public header files found in the development packages
1986 associated with the packages being compared. It also reports ABI
1987 changes about functions and global variables whose symbols are defined
1988 and exported in the ELF binaries found in the packages being compared.
1989 Invocation
1991 fedabipkgdiff [option] <NVR> ...
1992 Environment
1994 fedabipkgdiff loads two default suppression specifications files,
1995 merges their content and use it to filter out ABI change reports that
1996 might be considered as false positives to users.
1997 • Default system-wide suppression specification file
1999 It’s located by the optional environment variable LIBABIGAIL_DE‐
2001 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
2002 set, then fedabipkgdiff tries to load the suppression file $lib‐
2003 dir/libabigail/libabigail-default.abignore. If that file is not
2004 present, then no default system-wide suppression specification file
2005 is loaded.
2006 • Default user suppression specification file.
2008 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
2010 PRESSION_FILE. If that environment variable is not set, then fed‐
2011 abipkgdiff tries to load the suppression file $HOME/.abignore. If
2012 that file is not present, then no default user suppression specifica‐
2013 tion is loaded.
2014 Options
2016 • --help | -h
2017 Display a short help about the command and exit.
2019 • --dry-run
2021 Don’t actually perform the ABI comparison. Details about what is
2023 going to be done are emitted on standard output.
2024 • --debug
2026 Emit debugging messages about the execution of the program. De‐
2028 tails about each method invocation, including input parameters and
2029 returned values, are emitted.
2030 • --traceback
2032 Show traceback when an exception raised. This is useful for devel‐
2034 opers of the tool itself to know more exceptional errors.
2035 • --server <URL>
2037 Specifies the URL of the Koji XMLRPC service the tool talks to.
2039 The default value of this option is
2040 http://koji.fedoraproject.org/kojihub.
2041 • --topurl <URL>
2043 Specifies the URL of the package store the tool downloads RPMs
2045 from. The default value of this option is
2046 https://kojipkgs.fedoraproject.org.
2047 • --from <distro>
2049 Specifies the name of the baseline Fedora distribution in which to
2051 find the first build that is used for comparison. The distro value
2052 can be any valid value of the RPM macro %{?dist} for Fedora, for
2053 example, fc4, fc23, fc25.
2054 • --to <distro>
2056 Specifies the name of the Fedora distribution in which to find the
2058 build that is compared against the baseline specified by option
2059 --from. The distro value could be any valid value of the RPM
2060 macro %{?dist} for Fedora, for example, fc4, fc23.
2061 • --all-subpackages
2063 Instructs the tool to also compare the ABI of the binaries in the
2065 sub-packages of the packages specified.
2066 • --dso-only
2068 Compares the ABI of shared libraries only. If this option is not
2070 provided, the tool compares the ABI of all ELF binaries found in
2071 the packages.
2072 • --suppressions <path-to-suppresions>
2074 Use a suppression specification file located at path-to-suppres‐
2076 sions.
2077 • --no-default-suppression
2079 Do not load the default suppression specification files.
2081 • --no-devel-pkg
2083 Do not take associated development packages into account when per‐
2085 forming the ABI comparison. This makes the tool report ABI
2086 changes about all types that are reachable from functions and
2087 global variables which symbols are defined and publicly exported
2088 in the binaries being compared, even if those types are not de‐
2089 fined in public header files available from the packages being
2090 compared.
2091 • --show-identical-binaries
2093 Show the names of the all binaries compared, including the bina‐
2094 ries whose ABI compare equal. By default, when this option is
2095 not provided, only binaries with ABI changes are mentionned in
2096 the output.
2097 • --abipkgdiff <path/to/abipkgdiff>
2099 Specify an alternative abipkgdiff instead of the one installed in
2101 system.
2102 • --clean-cache-before
2104 Clean cache before ABI comparison.
2106 • --clean-cache-after
2108 Clean cache after ABI comparison.
2110 • --clean-cache
2112 If you want to clean cache both before and after ABI comparison,
2114 --clean-cache is the convenient way for you to save typing of two
2115 options at same time.
2116 Note that a build is a specific version and release of an RPM package.
2118 It’s specified by its the package name, version and release. These are
2119 specified by the Fedora Naming Guidelines
2120 Return value
2122 The exit code of the abipkgdiff command is either 0 if the ABI of the
2123 binaries compared are equivalent, or non-zero if they differ or if the
2124 tool encountered an error.
2125 In the later case, the value of the exit code is the same as for the
2127 abidiff tool.
2128 Use cases
2130 Below are some usage examples currently supported by fedabipkgdiff.
2131 1. Compare the ABI of binaries in a local package against the ABI of
2133 the latest stable package in Fedora 23.
2134 Suppose you have built just built the httpd package and you want
2136 to compare the ABI of the binaries in this locally built package
2137 against the ABI of the binaries in the latest http build from
2138 Fedora 23. The command line invocation would be:
2139 $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
2141 2. Compare the ABI of binaries in two local packages.
2143 Suppose you have built two versions of package httpd, and you
2145 want to see what ABI differences between these two versions of
2146 RPM files. The command line invocation would be:
2147 $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
2149 All what fedabipkgdiff does happens on local machine without the
2151 need of querying or downloading RPMs from Koji.
2152 3. Compare the ABI of binaries in the latest build of the httpd
2154 package in Fedora 23 against the ABI of the binaries in the lat‐
2155 est build of the same package in 24.
2156 In this case, note that neither of the two packages are available
2158 locally. The tool is going to talk with the Fedora Build System,
2159 determine what the versions and releases of the latest packages
2160 are, download them and perform the comparison locally. The com‐
2161 mand line invocation would be:
2162 $ fedabipkgdiff --from fc23 --to fc24 httpd
2164 4. Compare the ABI of binaries of two builds of the httpd package,
2166 designated their versions and releases.
2167 If we want to do perform the ABI comparison for all the processor
2169 architectures supported by Fedora the command line invocation
2170 would be:
2171 $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
2173 But if we want to perform the ABI comparison for a specific ar‐
2175 chitecture, say, x86_64, then the command line invocation would
2176 be:
2177 $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
2179 5. If the use wants to also compare the sub-packages of a given
2181 package, she can use the –all-subpackages option. The first com‐
2182 mand of the previous example would thus look like:
2183 $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
2185
2187 ABI artifacts
2188 An ABI artifact is a relevant part of the ABI of a shared library or
2189 program. Examples of ABI artifacts are exported types, variables,
2190 functions, or ELF symbols exported by a shared library.
2191 The set of ABI artifact for a binary is called an ABI Corpus.
2193 Harmful changes
2195 A change in the diff report is considered harmful if it might cause ABI
2196 compatibility issues. That is, it might prevent an application dynami‐
2197 cally linked against a given version of a library to keep working with
2198 the changed subsequent versions of the same library.
2199 Harmless changes
2201 A change in the diff report is considered harmless if it will not cause
2202 any ABI compatibility issue. That is, it will not prevent an applica‐
2203 tion dynamically linked against given version of a library to keep
2204 working with the changed subsequent versions of the same library.
2205 By default, abidiff filters harmless changes from the diff report.
2207 Suppression specifications
2209 Definition
2210 A suppression specification file is a way for a user to instruct abid‐
2211 iff, abipkgdiff or any other relevant libabigail tool to avoid emitting
2212 reports for changes involving certain ABI artifacts.
2213 It contains directives (or specifications) that describe the set of ABI
2215 artifacts to avoid emitting change reports about.
2216 Introductory examples
2218 Its syntax is based on a simplified and customized form of Ini File
2219 Syntax. For instance, to specify that change reports on a type named
2220 FooPrivateType should be suppressed, one could write this suppression
2221 specification:
2222 [suppress_type]
2224 name = FooPrivateType
2225 If we want to ensure that only change reports about structures named
2227 FooPrivateType should be suppressed, we could write:
2228 [suppress_type]
2230 type_kind = struct
2231 name = FooPrivateType
2232 But we could also want to suppress change reports avoid typedefs named
2234 FooPrivateType. In that case we would write:
2235 [suppress_type]
2237 type_kind = typedef
2238 name = FooPrivateType
2239 Or, we could want to suppress change reports about all struct which
2241 names end with the string “PrivateType”:
2242 [suppress_type]
2244 type_kind = struct
2245 name_regexp = ^.*PrivateType
2246 Let’s now look at the generic syntax of suppression specification
2248 files.
2249 Syntax
2251 Properties
2252 More generally, the format of suppression lists is organized around the
2253 concept of property. Every property has a name and a value, delimited
2254 by the = sign. E.g:
2255 name = value
2257 Leading and trailing white spaces are ignored around property names and
2259 values.
2260 Regular expressions
2262 The value of some properties might be a regular expression. In that
2263 case, they must comply with the syntax of extended POSIX regular ex‐
2264 pressions. Note that Libabigail uses the regular expression engine of
2265 the GNU C Library.
2266 Escaping a character in a regular expression
2268 When trying to match a string that contains a * character, like in the
2269 pointer type int*, one must be careful to notice that the character *
2270 is a special character in the extended POSIX regular expression syntax.
2271 And that character must be escaped for the regular expression engine.
2272 Thus the regular expression that would match the string int* in a sup‐
2273 pression file should be
2274 int\\*
2276 Wait; but then why the two \ characters? Well, because the \ character
2278 is a special character in the Ini File Syntax used for specifying sup‐
2279 pressions. So it must be escaped as well, so that the Ini File parser
2280 leaves a \ character intact in the data stream that is handed to the
2281 regular expression engine. Hence the \\ targeted at the Ini File
2282 parser.
2283 So, in short, to escape a character in a regular expression, always
2285 prefix the character with the \\ sequence.
2286 Modus operandi
2288 Suppression specifications can be applied at two different points of
2289 the processing pipeline of libabigail.
2290 In the default operating mode called “late suppression mode”, suppres‐
2292 sion specifications are applied to the result of comparing the in-mem‐
2293 ory internal representations of two ABIs. In this mode, if an ABI ar‐
2294 tifact matches a suppression specification, its changes are not men‐
2295 tioned in the ABI change report. The internal representation of the
2296 “suppressed” changed ABI artifact is still present in memory; it is
2297 just not mentioned in the ABI change report. The change report can
2298 still mention statistics about the number of changed ABI artifacts that
2299 were suppressed.
2300 There is another operating mode called the “early suppression mode”
2302 where suppression specifications are applied during the construction of
2303 the in-memory internal representation of a given ABI. In that mode, if
2304 an ABI artifact matches a suppression specification, no in-memory in‐
2305 ternal representation is built for it. As a result, no change about
2306 the matched ABI artifact is going to be mentioned in the ABI change re‐
2307 port and no statistic about the number of suppressed ABI changes is
2308 available. Also, please note that because suppressed ABI artifacts are
2309 removed from the in-memory internal representation in this mode, the
2310 amount memory used by the internal representation is potentially
2311 smaller than the memory consumption in the late suppression mode.
2312 Sections
2314 Properties are then grouped into arbitrarily named sections that shall
2315 not be nested. The name of the section is on a line by itself and is
2316 surrounded by square brackets, i.e:
2317 [section_name]
2319 property1_name = property1_value
2320 property2_name = property2_value
2321 A section might or might not have properties. Sections that expect to
2323 have properties and which are found nonetheless empty are just ignored.
2324 Properties that are not recognized by the reader are ignored as well.
2325 Section names
2327 Each different section can be thought of as being a directive to sup‐
2328 press ABI change reports for a particular kind of ABI artifact.
2329 [suppress_file]
2331 This directive prevents a given tool from loading a file (binary or
2332 abixml file) if its file name or other properties match certain proper‐
2333 ties. Thus, if the tool is meant to compare the ABIs of two files, and
2334 if the directive prevents it from loading either one of the files, then
2335 no comparison is performed.
2336 Note that for the [suppress_file] directive to work, at least one of
2338 the following properties must be provided:
2339 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2340 ame_not_regexp.
2341 If none of the above properties are provided, then the [suppress_file]
2343 directive is simply ignored.
2344 The potential properties of this sections are listed below:
2346 • file_name_regexp
2348 Usage:
2350 file_name_regexp = <regular-expression>
2351 Prevents the system from loading the file which name matches the reg‐
2353 ular expression specified as value of this property.
2354 • file_name_not_regexp
2356 Usage:
2358 file_name_not_regexp = <regular-expression>
2359 Prevents the system from loading the file which name does not match
2361 the regular expression specified as value of this property.
2362 • soname_regexp
2364 Usage:
2366 soname_regexp = <regular-expression>
2367 Prevents the system from loading the file which contains a SONAME
2369 property that matches the regular expression of this property. Note
2370 that this property also works on an abixml file if it contains a SON‐
2371 AME property.
2372 • soname_not_regexp
2374 Usage:
2376 soname_not_regexp = <regular-expression>
2377 Prevents the system from loading the file which contains a SONAME
2379 property that does NOT match the regular expression of this property.
2380 Note that this property also works on an abixml file if it contains a
2381 SONAME property.
2382 • label
2384 Usage:
2385 label = <some-value>
2386 Define a label for the section. A label is just an informative
2388 string that might be used by the tool to refer to a type suppression
2389 in error messages.
2390 [suppress_type]
2392 This directive suppresses report messages about a type change.
2393 Note that for the [suppress_type] directive to work, at least one of
2395 the following properties must be provided:
2396 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2397 ame_not_regexp, name, name_regexp, name_not_regexp, type_kind,
2398 source_location_not_in, source_location_not_regexp.
2399 If none of the above properties are provided, then the [suppress_type]
2401 directive is simply ignored.
2402 The potential properties of this sections are listed below:
2404 • file_name_regexp
2406 Usage:
2408 file_name_regexp = <regular-expression>
2409 Suppresses change reports about ABI artifacts that are defined in a
2411 binary file which name matches the regular expression specified as
2412 value of this property.
2413 • file_name_not_regexp
2415 Usage:
2417 file_name_not_regexp = <regular-expression>
2418 Suppresses change reports about ABI artifacts that are defined in a
2420 binary file which name does not match the regular expression speci‐
2421 fied as value of this property.
2422 • soname_regexp
2424 Usage:
2426 soname_regexp = <regular-expression>
2427 Suppresses change reports about ABI artifacts that are defined in a
2429 shared library which SONAME property matches the regular expression
2430 specified as value of this property.
2431 • soname_not_regexp
2433 Usage:
2435 soname_not_regexp = <regular-expression>
2436 Suppresses change reports about ABI artifacts that are defined in a
2438 shared library which SONAME property does not match the regular ex‐
2439 pression specified as value of this property.
2440 • name_regexp
2442 Usage:
2443 name_regexp = <regular-expression>
2444 Suppresses change reports involving types whose name matches the
2446 regular expression specified as value of this property.
2447 • name_not_regexp
2449 Usage:
2450 name_not_regexp = <regular-expression>
2451 Suppresses change reports involving types whose name does NOT match
2453 the regular expression specified as value of this property. Said
2454 otherwise, this property specifies which types to keep, rather than
2455 types to suppress from reports.
2456 • name
2458 Usage:
2459 name = <a-value>
2460 Suppresses change reports involving types whose name equals the
2462 value of this property.
2463 • type_kind
2465 Usage:
2466 type_kind = class | struct | union | enum |
2468 array | typedef | builtin
2469 Suppresses change reports involving a certain kind of type. The
2471 kind of type to suppress change reports for is specified by the pos‐
2472 sible values listed above:
2473 •
2475 class: suppress change reports for class types. Note that
2477 even if class types don’t exist for C, this value still
2478 triggers the suppression of change reports for struct
2479 types, in C. In C++ however, it should do what it sug‐
2480 gests.
2481 •
2483 struct: suppress change reports for struct types in C or C++.
2485 Note that the value class above is a super-set of this
2486 one.
2487 • union: suppress change reports for union types.
2489 • enum: suppress change reports for enum types.
2491 • array: suppress change reports for array types.
2493 • typedef: suppress change reports for typedef types.
2495 • builtin: suppress change reports for built-in (or native)
2497 types. Example of built-in types are char, int, unsigned int,
2498 etc.
2499 • source_location_not_in
2501 Usage:
2502 source_location_not_in = <list-of-file-paths>
2503 Suppresses change reports involving a type which is defined in a
2505 file which path is NOT listed in the value list-of-file-paths. Note
2506 that the value is a comma-separated list of file paths e.g, this
2507 property
2508 source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h
2510 suppresses change reports about all the types that are NOT defined
2512 in header files whose path end up with the strings libabi‐
2513 gail/abg-ir.h or libabigail/abg-dwarf-reader.h.
2514 • source_location_not_regexp
2516 Usage:
2517 source_location_not_regexp = <regular-expression>
2518 Suppresses change reports involving a type which is defined in a
2520 file which path does NOT match the regular expression provided as
2521 value of the property. E.g, this property
2522 source_location_not_regexp = libabigail/abg-.*\\.h
2524 suppresses change reports involving all the types that are NOT de‐
2526 fined in header files whose path match the regular expression pro‐
2527 vided a value of the property.
2528 • has_data_member_inserted_at
2530 Usage:
2531 has_data_member_inserted_at = <offset-in-bit>
2532 Suppresses change reports involving a type which has at least one
2534 data member inserted at an offset specified by the property value
2535 offset-in-bit. The value offset-in-bit is either:
2536 • an integer value, expressed in bits, which denotes the off‐
2538 set of the insertion point of the data member, starting
2539 from the beginning of the relevant structure or class.
2540 • the keyword end which is a named constant which value
2542 equals the offset of the end of the of the structure or
2543 class.
2544 • the function call expression offset_of(data-member-name)
2546 where data-member-name is the name of a given data member
2547 of the relevant structure or class. The value of this
2548 function call expression is an integer that represents the
2549 offset of the data member denoted by data-member-name.
2550 • the function call expression offset_after(data-member-name)
2552 where data-member-name is the name of a given data member
2553 of the relevant structure or class. The value of this
2554 function call expression is an integer that represents the
2555 offset of the point that comes right after the region occu‐
2556 pied by the data member denoted by data-member-name.
2557 • has_data_member_inserted_between
2559 Usage:
2560 has_data_member_inserted_between = {<range-begin>, <range-end>}
2561 Suppresses change reports involving a type which has at least one
2563 data mber inserted at an offset that is comprised in the range be‐
2564 tween range-begin`` and range-end. Please note that each of the
2565 values range-begin and range-end can be of the same form as the
2566 has_data_member_inserted_at property above.
2567 Usage examples of this properties are:
2569 has_data_member_inserted_between = {8, 64}
2571 or:
2573 has_data_member_inserted_between = {16, end}
2575 or:
2577 has_data_member_inserted_between = {offset_after(member1), end}
2579 • has_data_members_inserted_between
2581 Usage:
2582 has_data_members_inserted_between = {<sequence-of-ranges>}
2583 Suppresses change reports involving a type which has multiple data
2585 member inserted in various offset ranges. A usage example of this
2586 property is, for instance:
2587 has_data_members_inserted_between = {{8, 31}, {72, 95}}
2589 This usage example suppresses change reports involving a type which
2591 has data members inserted in bit offset ranges [8 31] and [72 95].
2592 The length of the sequence of ranges or this has_data_members_in‐
2593 serted_between is not bounded; it can be as long as the system can
2594 cope with. The values of the boundaries of the ranges are of the
2595 same kind as for the has_data_member_inserted_at property above.
2596 Another usage example of this property is thus:
2598 has_data_members_inserted_between =
2600 {
2601 {offset_after(member0), offset_of(member1)},
2602 {72, end}
2603 }
2604 • accessed_through
2606 Usage:
2607 accessed_through = <some-predefined-values>
2608 Suppress change reports involving a type which is referred to either
2610 directly or through a pointer or a reference. The potential values
2611 of this property are the predefined keywords below:
2612 • direct
2614 So if the [suppress_type] contains the property description:
2616 accessed_through = direct
2618 then changes about a type that is referred-to directly (i.e,
2620 not through a pointer or a reference) are going to be sup‐
2621 pressed.
2622 • pointer
2624 If the accessed_through property is set to the value pointer
2626 then changes about a type that is referred-to through a
2627 pointer are going to be suppressed.
2628 • reference
2630 If the accessed_through property is set to the value reference
2632 then changes about a type that is referred-to through a refer‐
2633 ence are going to be suppressed.
2634 • reference-or-pointer
2636 If the accessed_through property is set to the value refer‐
2638 ence-or-pointer then changes about a type that is referred-to
2639 through either a reference or a pointer are going to be sup‐
2640 pressed.
2641 For an extensive example of how to use this property, please check
2643 out the example below about suppressing change reports about types
2644 accessed either directly or through pointers.
2645 • drop
2647 Usage:
2648 drop = yes | no
2649 If a type is matched by a suppression specification which contains
2651 the “drop” property set to “yes” (or to “true”) then the type is not
2652 even going to be represented in the internal representation of the
2653 ABI being analyzed. This property makes its enclosing suppression
2654 specification to be applied in the early suppression specification
2655 mode. The net effect is that it potentially reduces the memory used
2656 to represent the ABI being analyzed.
2657 Please note that for this property to be effective, the enclosing
2659 suppression specification must have at least one of the following
2660 properties specified: name_regexp, name, name_regexp, source_loca‐
2661 tion_not_in or source_location_not_regexp.
2662 • label
2664 Usage:
2665 label = <some-value>
2666 Define a label for the section. A label is just an informative
2668 string that might be used by a tool to refer to a type suppression
2669 in error messages.
2670 • changed_enumerators
2672 Usage:
2674 changed_enumerators = <list-of-enumerators>
2675 Suppresses change reports involving changes in the value of enumera‐
2677 tors of a given enum type. This property is applied if the type_kind
2678 property is set to the value enum, at least. The value of the
2679 changed_enumerators is a comma-separated list of the enumerators that
2680 the user expects to change. For instance:
2681 changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1
2683 [suppress_function]
2685 This directive suppresses report messages about changes on a set of
2686 functions.
2687 Note that for the [suppress_function] directive to work, at least one
2689 of the following properties must be provided:
2690 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2691 ame_not_regexp, name, name_regexp, name_not_regexp, parameter, re‐
2692 turn_type_name, return_type_regexp, symbol_name, symbol_name_regexp,
2693 symbol_name_not_regexp, symbol_version, symbol_version_regexp.
2694 If none of the above properties are provided, then the [suppress_func‐
2696 tion] directive is simply ignored.
2697 The potential properties of this sections are:
2699 • label
2701 Usage:
2702 label = <some-value>
2703 This property is the same as the label property defined above.
2705 • file_name_regexp
2707 Usage:
2709 file_name_regexp = <regular-expression>
2711 Suppresses change reports about ABI artifacts that are defined in a
2713 binary file which name matches the regular expression specified as
2714 value of this property.
2715 • file_name_not_regexp
2717 Usage:
2719 file_name_not_regexp = <regular-expression>
2720 Suppresses change reports about ABI artifacts that are defined in a
2722 binary file which name does not match the regular expression speci‐
2723 fied as value of this property.
2724 • soname_regexp
2726 Usage:
2728 soname_regexp = <regular-expression>
2729 Suppresses change reports about ABI artifacts that are defined in a
2731 shared library which SONAME property matches the regular expression
2732 specified as value of this property.
2733 • soname_not_regexp
2735 Usage:
2737 soname_not_regexp = <regular-expression>
2738 Suppresses change reports about ABI artifacts that are defined in a
2740 shared library which SONAME property does not match the regular ex‐
2741 pression specified as value of this property.
2742 • name
2744 Usage:
2745 name = <some-value>
2746 Suppresses change reports involving functions whose name equals the
2748 value of this property.
2749 • name_regexp
2751 Usage:
2752 name_regexp = <regular-expression>
2753 Suppresses change reports involving functions whose name matches the
2755 regular expression specified as value of this property.
2756 Let’s consider the case of functions that have several symbol names.
2758 This happens when the underlying symbol for the function has
2759 aliases. Each symbol name is actually one alias name.
2760 In this case, if the regular expression matches the name of at least
2762 one of the aliases names, then it must match the names of all of the
2763 aliases of the function for the directive to actually suppress the
2764 diff reports for said function.
2765 • name_not_regexp
2767 Usage:
2768 name_not_regexp = <regular-expression>
2769 Suppresses change reports involving functions whose names don’t
2771 match the regular expression specified as value of this property.
2772 The rules for functions that have several symbol names are the same
2774 rules as for the name_regexp property above.
2775 • change_kind
2777 Usage:
2778 change_kind = <predefined-possible-values>
2779 Specifies the kind of changes this suppression specification should
2781 apply to. The possible values of this property as well as their
2782 meaning are listed below:
2783 • function-subtype-change
2785 This suppression specification applies to functions that which
2787 have at least one sub-type that has changed.
2788 • added-function
2790 This suppression specification applies to functions that have
2792 been added to the binary.
2793 • deleted-function
2795 This suppression specification applies to functions that have
2797 been removed from the binary.
2798 • all
2800 This suppression specification applies to functions that have
2802 all of the changes above. Note that not providing the
2803 change_kind property at all is equivalent to setting it to the
2804 value all.
2805 • parameter
2807 Usage:
2808 parameter = <function-parameter-specification>
2809 Suppresses change reports involving functions whose parameters match
2811 the parameter specification indicated as value of this property.
2812 The format of the function parameter specification is:
2814 ' <parameter-index> <space> <type-name-or-regular-expression>
2816 That is, an apostrophe followed by a number that is the index of the
2818 parameter, followed by one of several spaces, followed by either the
2819 name of the type of the parameter, or a regular expression describ‐
2820 ing a family of parameter type names.
2821 If the parameter type name is designated by a regular expression,
2823 then said regular expression must be enclosed between two slashes;
2824 like /some-regular-expression/.
2825 The index of the first parameter of the function is zero. Note that
2827 for member functions (methods of classes), the this is the first pa‐
2828 rameter that comes after the implicit “this” pointer parameter.
2829 Examples of function parameter specifications are:
2831 '0 int
2833 Which means, the parameter at index 0, whose type name is int.
2835 '4 unsigned char*
2837 Which means, the parameter at index 4, whose type name is unsigned
2839 char*.
2840 '2 /^foo.*&/
2842 Which means, the parameter at index 2, whose type name starts with
2844 the string “foo” and ends with an ‘&’. In other words, this is the
2845 third parameter and it’s a reference on a type that starts with the
2846 string “foo”.
2847 • return_type_name
2849 Usage:
2850 return_type_name = <some-value>
2851 Suppresses change reports involving functions whose return type name
2853 equals the value of this property.
2854 • return_type_regexp
2856 Usage:
2857 return_type_regexp = <regular-expression>
2858 Suppresses change reports involving functions whose return type name
2860 matches the regular expression specified as value of this property.
2861 • symbol_name
2863 Usage:
2864 symbol_name = <some-value>
2865 Suppresses change reports involving functions whose symbol name
2867 equals the value of this property.
2868 • symbol_name_regexp
2870 Usage:
2871 symbol_name_regexp = <regular-expression>
2872 Suppresses change reports involving functions whose symbol name
2874 matches the regular expression specified as value of this property.
2875 Let’s consider the case of functions that have several symbol names.
2877 This happens when the underlying symbol for the function has
2878 aliases. Each symbol name is actually one alias name.
2879 In this case, the regular expression must match the names of all of
2881 the aliases of the function for the directive to actually suppress
2882 the diff reports for said function.
2883 • symbol_name_not_regexp
2885 Usage:
2886 symbol_name_not_regexp = <regular-expression>
2887 Suppresses change reports involving functions whose symbol name does
2889 not match the regular expression specified as value of this prop‐
2890 erty.
2891 • symbol_version
2893 Usage:
2894 symbol_version = <some-value>
2895 Suppresses change reports involving functions whose symbol version
2897 equals the value of this property.
2898 • symbol_version_regexp
2900 Usage:
2901 symbol_version_regexp = <regular-expression>
2902 Suppresses change reports involving functions whose symbol version
2904 matches the regular expression specified as value of this property.
2905 • drop
2907 Usage:
2908 drop = yes | no
2909 If a function is matched by a suppression specification which con‐
2911 tains the “drop” property set to “yes” (or to “true”) then the func‐
2912 tion is not even going to be represented in the internal representa‐
2913 tion of the ABI being analyzed. This property makes its enclosing
2914 suppression specification to be applied in the early suppression
2915 specification mode. The net effect is that it potentially reduces
2916 the memory used to represent the ABI being analyzed.
2917 Please note that for this property to be effective, the enclosing
2919 suppression specification must have at least one of the following
2920 properties specified: name_regexp, name, name_regexp, source_loca‐
2921 tion_not_in or source_location_not_regexp.
2922 [suppress_variable]
2924 This directive suppresses report messages about changes on a set of
2925 variables.
2926 Note that for the [suppress_variable] directive to work, at least one
2928 of the following properties must be provided:
2929 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2930 ame_not_regexp, name, name_regexp, name_not_regexp, symbol_name,
2931 symbol_name_regexp, symbol_name_not_regexp, symbol_version, sym‐
2932 bol_version_regexp, type_name, type_name_regexp.
2933 If none of the above properties are provided, then the [suppress_vari‐
2935 able] directive is simply ignored.
2936 The potential properties of this sections are:
2938 • label
2940 Usage:
2941 label = <some-value>
2942 This property is the same as the label property defined above.
2944 • file_name_regexp
2946 Usage:
2948 file_name_regexp = <regular-expression>
2950 Suppresses change reports about ABI artifacts that are defined in a
2952 binary file which name matches the regular expression specified as
2953 value of this property.
2954 • file_name_not_regexp
2956 Usage:
2958 file_name_not_regexp = <regular-expression>
2959 Suppresses change reports about ABI artifacts that are defined in a
2961 binary file which name does not match the regular expression speci‐
2962 fied as value of this property.
2963 • soname_regexp
2965 Usage:
2967 soname_regexp = <regular-expression>
2968 Suppresses change reports about ABI artifacts that are defined in a
2970 shared library which SONAME property matches the regular expression
2971 specified as value of this property.
2972 • soname_not_regexp
2974 Usage:
2976 soname_not_regexp = <regular-expression>
2977 Suppresses change reports about ABI artifacts that are defined in a
2979 shared library which SONAME property does not match the regular ex‐
2980 pression specified as value of this property.
2981 • name
2983 Usage:
2984 name = <some-value>
2985 Suppresses change reports involving variables whose name equals the
2987 value of this property.
2988 • name_regexp
2990 Usage:
2991 name_regexp = <regular-expression>
2992 Suppresses change reports involving variables whose name matches the
2994 regular expression specified as value of this property.
2995 • change_kind
2997 Usage:
2998 change_kind = <predefined-possible-values>
2999 Specifies the kind of changes this suppression specification should
3001 apply to. The possible values of this property as well as their
3002 meaning are the same as when it’s used in the [suppress_function]
3003 section.
3004 • symbol_name
3006 Usage:
3007 symbol_name = <some-value>
3008 Suppresses change reports involving variables whose symbol name
3010 equals the value of this property.
3011 • symbol_name_regexp
3013 Usage:
3014 symbol_name_regexp = <regular-expression>
3015 Suppresses change reports involving variables whose symbol name
3017 matches the regular expression specified as value of this property.
3018 • symbol_name_not_regexp
3020 Usage:
3021 symbol_name_not_regexp = <regular-expression>
3022 Suppresses change reports involving variables whose symbol name does
3024 not match the regular expression specified as value of this prop‐
3025 erty.
3026 • symbol_version
3028 Usage:
3029 symbol_version = <some-value>
3030 Suppresses change reports involving variables whose symbol version
3032 equals the value of this property.
3033 • symbol_version_regexp
3035 Usage:
3036 symbol_version_regexp = <regular-expression>
3037 Suppresses change reports involving variables whose symbol version
3039 matches the regular expression specified as value of this property.
3040 • type_name
3042 Usage:
3043 type_name = <some-value>
3044 Suppresses change reports involving variables whose type name equals
3046 the value of this property.
3047 • type_name_regexp
3049 Usage:
3050 type_name_regexp = <regular-expression>
3051 Suppresses change reports involving variables whose type name
3053 matches the regular expression specified as value of this property.
3054 Comments
3056 ; or # ASCII character at the beginning of a line indicates a comment.
3057 Comment lines are ignored.
3058 Code examples
3060 1. Suppressing change reports about types.
3061 Suppose we have a library named libtest1-v0.so which contains this
3063 very useful code:
3064 $ cat -n test1-v0.cc
3066 1 // A forward declaration for a type considered to be opaque to
3067 2 // function foo() below.
3068 3 struct opaque_type;
3069 4
3070 5 // This function cannot touch any member of opaque_type. Hence,
3071 6 // changes to members of opaque_type should not impact foo, as far as
3072 7 // ABI is concerned.
3073 8 void
3074 9 foo(opaque_type*)
3075 10 {
3076 11 }
3077 12
3078 13 struct opaque_type
3079 14 {
3080 15 int member0;
3081 16 char member1;
3082 17 };
3083 $
3084 Let’s change the layout of struct opaque_type by inserting a data mem‐
3086 ber around line 15, leading to a new version of the library, that we
3087 shall name libtest1-v1.so:
3088 $ cat -n test1-v1.cc
3090 1 // A forward declaration for a type considered to be opaque to
3091 2 // function foo() below.
3092 3 struct opaque_type;
3093 4
3094 5 // This function cannot touch any member of opaque_type; Hence,
3095 6 // changes to members of opaque_type should not impact foo, as far as
3096 7 // ABI is concerned.
3097 8 void
3098 9 foo(opaque_type*)
3099 10 {
3100 11 }
3101 12
3102 13 struct opaque_type
3103 14 {
3104 15 char added_member; // <-- a new member got added here now.
3105 16 int member0;
3106 17 char member1;
3107 18 };
3108 $
3109 Let’s compile both examples. We shall not forget to compile them with
3111 debug information generation turned on:
3112 $ g++ -shared -g -Wall -o libtest1-v0.so test1-v0.cc
3114 $ g++ -shared -g -Wall -o libtest1-v1.so test1-v1.cc
3115 Let’s ask abidiff which ABI differences it sees between libtest1-v0.so
3117 and libtest1-v1.so:
3118 $ abidiff libtest1-v0.so libtest1-v1.so
3120 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3121 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3122 1 function with some indirect sub-type change:
3124 [C]'function void foo(opaque_type*)' has some indirect sub-type changes:
3126 parameter 0 of type 'opaque_type*' has sub-type changes:
3127 in pointed to type 'struct opaque_type':
3128 size changed from 64 to 96 bits
3129 1 data member insertion:
3130 'char opaque_type::added_member', at offset 0 (in bits)
3131 2 data member changes:
3132 'int opaque_type::member0' offset changed from 0 to 32
3133 'char opaque_type::member1' offset changed from 32 to 64
3134 So abidiff reports that the opaque_type’s layout has changed in a sig‐
3136 nificant way, as far as ABI implications are concerned, in theory. Af‐
3137 ter all, a sub-type (struct opaque_type) of an exported function
3138 (foo()) has seen its layout change. This might have non negligible ABI
3139 implications. But in practice here, the programmer of the
3140 litest1-v1.so library knows that the “soft” contract between the func‐
3141 tion foo() and the type struct opaque_type is to stay away from the
3142 data members of the type. So layout changes of struct opaque_type
3143 should not impact foo().
3144 Now to teach abidiff about this soft contract and have it avoid emit‐
3146 ting what amounts to false positives in this case, we write the sup‐
3147 pression specification file below:
3148 $ cat test1.suppr
3150 [suppress_type]
3151 type_kind = struct
3152 name = opaque_type
3153 Translated in plain English, this suppression specification would read:
3155 “Do not emit change reports about a struct which name is opaque_type”.
3156 Let’s now invoke abidiff on the two versions of the library again, but
3158 this time with the suppression specification:
3159 $ abidiff --suppressions test1.suppr libtest1-v0.so libtest1-v1.so
3161 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3162 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3163 As you can see, abidiff does not report the change anymore; it tells us
3165 that it was filtered out instead.
3166 Suppressing change reports about types with data member insertions
3168 Suppose the first version of a library named libtest3-v0.so has this
3170 source code:
3171 /* Compile this with:
3173 gcc -g -Wall -shared -o libtest3-v0.so test3-v0.c
3174 */
3175 struct S
3177 {
3178 char member0;
3179 int member1; /*
3180 between member1 and member2, there is some padding,
3181 at least on some popular platforms. On
3182 these platforms, adding a small enough data
3183 member into that padding shouldn't change
3184 the offset of member1. Right?
3185 */
3186 };
3187 int
3189 foo(struct S* s)
3190 {
3191 return s->member0 + s->member1;
3192 }
3193 Now, suppose the second version of the library named libtest3-v1.so has
3195 this source code in which a data member has been added in the padding
3196 space of struct S and another data member has been added at its end:
3197 /* Compile this with:
3199 gcc -g -Wall -shared -o libtest3-v1.so test3-v1.c
3200 */
3201 struct S
3203 {
3204 char member0;
3205 char inserted1; /* <---- A data member has been added here... */
3206 int member1;
3207 char inserted2; /* <---- ... and another one has been added here. */
3208 };
3209 int
3211 foo(struct S* s)
3212 {
3213 return s->member0 + s->member1;
3214 }
3215 In libtest3-v1.so, adding char data members S::inserted1 and S::in‐
3217 serted2 can be considered harmless (from an ABI compatibility perspec‐
3218 tive), at least on the x86 platform, because that doesn’t change the
3219 offsets of the data members S::member0 and S::member1. But then run‐
3220 ning abidiff on these two versions of library yields:
3221 $ abidiff libtest3-v0.so libtest3-v1.so
3223 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3224 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3225 1 function with some indirect sub-type change:
3227 [C]'function int foo(S*)' has some indirect sub-type changes:
3229 parameter 0 of type 'S*' has sub-type changes:
3230 in pointed to type 'struct S':
3231 type size changed from 64 to 96 bits
3232 2 data member insertions:
3233 'char S::inserted1', at offset 8 (in bits)
3234 'char S::inserted2', at offset 64 (in bits)
3235 $
3236 That is, abidiff shows us the two changes, even though we (the develop‐
3238 ers of that very involved library) know that these changes are harmless
3239 in this particular context.
3240 Luckily, we can devise a suppression specification that essentially
3242 tells abidiff to filter out change reports about adding a data member
3243 between S::member0 and S::member1, and adding a data member at the end
3244 of struct S. We have written such a suppression specification in a
3245 file called test3-1.suppr and it unsurprisingly looks like:
3246 [suppress_type]
3248 name = S
3249 has_data_member_inserted_between = {offset_after(member0), offset_of(member1)}
3250 has_data_member_inserted_at = end
3251 Now running abidiff with this suppression specification yields:
3253 $ ../build/tools/abidiff --suppressions test3-1.suppr libtest3-v0.so libtest3-v1.so
3255 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3256 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3257 $
3259 Hooora! \o/ (I guess)
3261 Suppressing change reports about types accessed either directly or
3263 through pointers
3264 Suppose we have a first version of an object file which source code is
3266 the file widget-v0.cc below:
3267 // Compile with: g++ -g -c widget-v0.cc
3269 struct widget
3271 {
3272 int x;
3273 int y;
3274 widget()
3276 :x(), y()
3277 {}
3278 };
3279 void
3281 fun0(widget*)
3282 {
3283 // .. do stuff here.
3284 }
3285 void
3287 fun1(widget&)
3288 {
3289 // .. do stuff here ..
3290 }
3291 void
3293 fun2(widget w)
3294 {
3295 // ... do other stuff here ...
3296 }
3297 Now suppose in the second version of that file, named widget-v1.cc, we
3299 have added some data members at the end of the type struct widget; here
3300 is what the content of that file would look like:
3301 // Compile with: g++ -g -c widget-v1.cc
3303 struct widget
3305 {
3306 int x;
3307 int y;
3308 int w; // We have added these two new data members here ..
3309 int h; // ... and here.
3310 widget()
3312 : x(), y(), w(), h()
3313 {}
3314 };
3315 void
3317 fun0(widget*)
3318 {
3319 // .. do stuff here.
3320 }
3321 void
3323 fun1(widget&)
3324 {
3325 // .. do stuff here ..
3326 }
3327 void
3329 fun2(widget w)
3330 {
3331 // ... do other stuff here ...
3332 }
3333 When we invoke abidiff on the object files resulting from the compila‐
3335 tion of the two file above, here is what we get:
3336 $ abidiff widget-v0.o widget-v1.o
3338 Functions changes summary: 0 Removed, 2 Changed (1 filtered out), 0 Added functions
3339 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3340 2 functions with some indirect sub-type change:
3342 [C]'function void fun0(widget*)' has some indirect sub-type changes:
3344 parameter 1 of type 'widget*' has sub-type changes:
3345 in pointed to type 'struct widget':
3346 type size changed from 64 to 128 bits
3347 2 data member insertions:
3348 'int widget::w', at offset 64 (in bits)
3349 'int widget::h', at offset 96 (in bits)
3350 [C]'function void fun2(widget)' has some indirect sub-type changes:
3352 parameter 1 of type 'struct widget' has sub-type changes:
3353 details were reported earlier
3354 $
3355 I guess a little bit of explaining is due here. abidiff detects that
3357 two data member got added at the end of struct widget. it also tells
3358 us that the type change impacts the exported function fun0() which uses
3359 the type struct widget through a pointer, in its signature.
3360 Careful readers will notice that the change to struct widget also im‐
3362 pacts the exported function fun1(), that uses type struct widget
3363 through a reference. But then abidiff doesn’t tell us about the impact
3364 on that function fun1() because it has evaluated that change as being
3365 redundant with the change it reported on fun0(). It has thus filtered
3366 it out, to avoid cluttering the output with noise.
3367 Redundancy detection and filtering is fine and helpful to avoid burying
3369 the important information in a sea of noise. However, it must be
3370 treated with care, by fear of mistakenly filtering out relevant and im‐
3371 portant information.
3372 That is why abidiff tells us about the impact that the change to struct
3374 widget has on function fun2(). In this case, that function uses the
3375 type struct widget directly (in its signature). It does not use it via
3376 a pointer or a reference. In this case, the direct use of this type
3377 causes fun2() to be exposed to a potentially harmful ABI change.
3378 Hence, the report about fun2() is not filtered out, even though it’s
3379 about that same change on struct widget.
3380 To go further in suppressing reports about changes that are harmless
3382 and keeping only those that we know are harmful, we would like to go
3383 tell abidiff to suppress reports about this particular struct widget
3384 change when it impacts uses of struct widget through a pointer or ref‐
3385 erence. In other words, suppress the change reports about fun0() and
3386 fun1(). We would then write this suppression specification, in file
3387 widget.suppr:
3388 [suppress_type]
3390 name = widget
3391 type_kind = struct
3392 has_data_member_inserted_at = end
3393 accessed_through = reference-or-pointer
3394 # So this suppression specification says to suppress reports about
3396 # the type 'struct widget', if this type was added some data member
3397 # at its end, and if the change impacts uses of the type through a
3398 # reference or a pointer.
3399 Invoking abidiff on widget-v0.o and widget-v1.o with this suppression
3401 specification yields:
3402 $ abidiff --suppressions widget.suppr widget-v0.o widget-v1.o
3404 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
3405 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3406 1 function with some indirect sub-type change:
3408 [C]'function void fun2(widget)' has some indirect sub-type changes:
3410 parameter 1 of type 'struct widget' has sub-type changes:
3411 type size changed from 64 to 128 bits
3412 2 data member insertions:
3413 'int widget::w', at offset 64 (in bits)
3414 'int widget::h', at offset 96 (in bits)
3415 $
3416 As expected, I guess.
3418 Suppressing change reports about functions.
3420 Suppose we have a first version a library named libtest2-v0.so whose
3422 source code is:
3423 $ cat -n test2-v0.cc
3425 1 struct S1
3427 2 {
3428 3 int m0;
3429 4
3430 5 S1()
3431 6 : m0()
3432 7 {}
3433 8 };
3434 9
3435 10 struct S2
3436 11 {
3437 12 int m0;
3438 13
3439 14 S2()
3440 15 : m0()
3441 16 {}
3442 17 };
3443 18
3444 19 struct S3
3445 20 {
3446 21 int m0;
3447 22
3448 23 S3()
3449 24 : m0()
3450 25 {}
3451 26 };
3452 27
3453 28 int
3454 29 func(S1&)
3455 30 {
3456 31 // suppose the code does something with the argument.
3457 32 return 0;
3458 33
3459 34 }
3460 35
3461 36 char
3462 37 func(S2*)
3463 38 {
3464 39 // suppose the code does something with the argument.
3465 40 return 0;
3466 41 }
3467 42
3468 43 unsigned
3469 44 func(S3)
3470 45 {
3471 46 // suppose the code does something with the argument.
3472 47 return 0;
3473 48 }
3474 $
3475 And then we come up with a second version libtest2-v1.so of that li‐
3477 brary; the source code is modified by making the structures S1, S2, S3
3478 inherit another struct:
3479 $ cat -n test2-v1.cc
3481 1 struct base_type
3482 2 {
3483 3 int m_inserted;
3484 4 };
3485 5
3486 6 struct S1 : public base_type // <--- S1 now has base_type as its base
3487 7 // type.
3488 8 {
3489 9 int m0;
3490 10
3491 11 S1()
3492 12 : m0()
3493 13 {}
3494 14 };
3495 15
3496 16 struct S2 : public base_type // <--- S2 now has base_type as its base
3497 17 // type.
3498 18 {
3499 19 int m0;
3500 20
3501 21 S2()
3502 22 : m0()
3503 23 {}
3504 24 };
3505 25
3506 26 struct S3 : public base_type // <--- S3 now has base_type as its base
3507 27 // type.
3508 28 {
3509 29 int m0;
3510 30
3511 31 S3()
3512 32 : m0()
3513 33 {}
3514 34 };
3515 35
3516 36 int
3517 37 func(S1&)
3518 38 {
3519 39 // suppose the code does something with the argument.
3520 40 return 0;
3521 41
3522 42 }
3523 43
3524 44 char
3525 45 func(S2*)
3526 46 {
3527 47 // suppose the code does something with the argument.
3528 48 return 0;
3529 49 }
3530 50
3531 51 unsigned
3532 52 func(S3)
3533 53 {
3534 54 // suppose the code does something with the argument.
3535 55 return 0;
3536 56 }
3537 $
3538 Now let’s build the two libraries:
3540 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
3542 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
3543 Let’s look at the output of abidiff:
3545 $ abidiff libtest2-v0.so libtest2-v1.so
3547 Functions changes summary: 0 Removed, 3 Changed, 0 Added functions
3548 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3549 3 functions with some indirect sub-type change:
3551 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
3553 parameter 0 of type 'struct S3' has sub-type changes:
3554 size changed from 32 to 64 bits
3555 1 base class insertion:
3556 struct base_type
3557 1 data member change:
3558 'int S3::m0' offset changed from 0 to 32
3559 [C]'function char func(S2*)' has some indirect sub-type changes:
3561 parameter 0 of type 'S2*' has sub-type changes:
3562 in pointed to type 'struct S2':
3563 size changed from 32 to 64 bits
3564 1 base class insertion:
3565 struct base_type
3566 1 data member change:
3567 'int S2::m0' offset changed from 0 to 32
3568 [C]'function int func(S1&)' has some indirect sub-type changes:
3570 parameter 0 of type 'S1&' has sub-type changes:
3571 in referenced type 'struct S1':
3572 size changed from 32 to 64 bits
3573 1 base class insertion:
3574 struct base_type
3575 1 data member change:
3576 'int S1::m0' offset changed from 0 to 32
3577 $
3578 Let’s tell abidiff to avoid showing us the differences on the overloads
3580 of func that takes either a pointer or a reference. For that, we au‐
3581 thor this simple suppression specification:
3582 $ cat -n libtest2.suppr
3584 1 [suppress_function]
3585 2 name = func
3586 3 parameter = '0 S1&
3587 4
3588 5 [suppress_function]
3589 6 name = func
3590 7 parameter = '0 S2*
3591 $
3592 And then let’s invoke abidiff with the suppression specification:
3594 $ ../build/tools/abidiff --suppressions libtest2.suppr libtest2-v0.so libtest2-v1.so
3596 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
3597 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3598 1 function with some indirect sub-type change:
3600 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
3602 parameter 0 of type 'struct S3' has sub-type changes:
3603 size changed from 32 to 64 bits
3604 1 base class insertion:
3605 struct base_type
3606 1 data member change:
3607 'int S3::m0' offset changed from 0 to 32
3608 The suppression specification could be reduced using regular expres‐
3610 sions:
3611 $ cat -n libtest2-1.suppr
3613 1 [suppress_function]
3614 2 name = func
3615 3 parameter = '0 /^S.(&|\\*)/
3616 $
3617 $ ../build/tools/abidiff --suppressions libtest2-1.suppr libtest2-v0.so libtest2-v1.so
3619 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
3620 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3621 1 function with some indirect sub-type change:
3623 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
3625 parameter 0 of type 'struct S3' has sub-type changes:
3626 size changed from 32 to 64 bits
3627 1 base class insertion:
3628 struct base_type
3629 1 data member change:
3630 'int S3::m0' offset changed from 0 to 32
3631 $
3633
3635 Dodji Seketeli
3636
3638 2014-2021, Red Hat, Inc.
3639 Oct 04, 2021 LIBABIGAIL(7)