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 between two input shared li‐
63 braries that includes changes about function and variable sub-types,
64 abidiff uses by default, debug information in DWARF format, if present,
65 otherwise it compares interfaces using debug information in CTF format,
66 if present, finally, if neither is found, it uses only ELF symbols to
67 report which of them were added or removed.
68 This tool uses the libabigail library to analyze the binary as well as
70 its associated debug information. Here is its general mode of opera‐
71 tion.
72 When instructed to do so, a binary and its associated debug information
74 is read and analyzed. To that effect, libabigail analyzes by default
75 the descriptions of the types reachable by the interfaces (functions
76 and variables) that are visible outside of their translation unit.
77 Once that analysis is done, an Application Binary Interface Corpus is
78 constructed by only considering the subset of types reachable from in‐
79 terfaces associated to ELF symbols that are defined and exported by the
80 binary. It’s that final ABI corpus which libabigail considers as rep‐
81 resenting the ABI of the analyzed binary.
82 Libabigail then has capabilities to generate textual representations of
84 ABI Corpora, compare them, analyze their changes and report about them.
85 Invocation
87 abidiff [options] <first-shared-library> <second-shared-library>
88 Environment
90 abidiff loads two default suppression specifications files, merges
91 their content and use it to filter out ABI change reports that might be
92 considered as false positives to users.
93 • Default system-wide suppression specification file
95 It’s located by the optional environment variable LIBABIGAIL_DE‐
97 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
98 set, then abidiff tries to load the suppression file $libdir/libabi‐
99 gail/libabigail-default.abignore. If that file is not present, then
100 no default system-wide suppression specification file is loaded.
101 • Default user suppression specification file.
103 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
105 PRESSION_FILE. If that environment variable is not set, then abidiff
106 tries to load the suppression file $HOME/.abignore. If that file is
107 not present, then no default user suppression specification is
108 loaded.
109 Options
111 • --help | -h
112 Display a short help about the command and exit.
114 • --debug-self-comparison
116 In this mode, error messages are emitted for types which fail type
118 canonicalization, in some circumstances, when comparing a binary
119 against itself.
120 When comparing a binary against itself, canonical types of the
122 second binary should be equal (as much as possible) to canonical
123 types of the first binary. When some discrepancies are detected
124 in this mode, an abort signal is emitted and execution is halted.
125 This option should be used while executing the tool in a debugger,
126 for troubleshooting purposes.
127 This is an optional debugging and sanity check option. To enable
129 it the libabigail package needs to be configured with the –en‐
130 able-debug-self-comparison configure option.
131 • --debug-tc
133 In this mode, the process of type canonicalization is put under
135 heavy scrutiny. Basically, during type canonicalization, each
136 type comparison is performed twice: once in a structural mode
137 (comparing every sub-type member-wise), and once using canonical
138 comparison. The two comparisons should yield the same result.
139 Otherwise, an abort signal is emitted and the process can be de‐
140 bugged to understand why the two kinds of comparison yield differ‐
141 ent results.
142 This is an optional debugging and sanity check option. To enable
144 it the libabigail package needs to be configured with the –en‐
145 able-debug-type-canonicalization configure option.
146 • --version | -v
148 Display the version of the program and exit.
150 • --debug-info-dir1 | --d1 <di-path1>
152 For cases where the debug information for first-shared-library is
154 split out into a separate file, tells abidiff where to find that
155 separate debug information file.
156 Note that di-path must point to the root directory under which the
158 debug information is arranged in a tree-like manner. Under Red
159 Hat based systems, that directory is usually <root>/usr/lib/debug.
160 This option can be provided several times with different root di‐
162 rectories. In that case, abidiff will potentially look into all
163 those root directories to find the split debug info for
164 first-shared-library.
165 Note also that this option is not mandatory for split debug infor‐
167 mation installed by your system’s package manager because then
168 abidiff knows where to find it.
169 • --debug-info-dir2 | --d2 <di-path2>
171 Like --debug-info-dir1, this options tells abidiff where to find
173 the split debug information for the second-shared-library file.
174 This option can be provided several times with different root di‐
176 rectories. In that case, abidiff will potentially look into all
177 those root directories to find the split debug info for sec‐
178 ond-shared-library.
179 • --headers-dir1 | --hd1 <headers-directory-path-1>
181 Specifies where to find the public headers of the first shared li‐
183 brary (or binary in general) that the tool has to consider. The
184 tool will thus filter out ABI changes on types that are not de‐
185 fined in public headers.
186 Note that several public header directories can be specified for
188 the first shared library. In that case the --headers-dir1 option
189 should be present several times on the command line, like in the
190 following example:
191 $ abidiff --headers-dir1 /some/path \
193 --headers-dir1 /some/other/path \
194 binary-version-1 binary-version-2
195 • --header-file1 | --hf1 <header-file-path-1>
197 Specifies where to find one public header of the first shared li‐
199 brary that the tool has to consider. The tool will thus filter
200 out ABI changes on types that are not defined in public headers.
201 • --headers-dir2 | --hd2 <headers-directory-path-2>
203 Specifies where to find the public headers of the second shared
205 library that the tool has to consider. The tool will thus filter
206 out ABI changes on types that are not defined in public headers.
207 Note that several public header directories can be specified for
209 the second shared library. In that case the --headers-dir2 option
210 should be present several times like in the following example:
211 $ abidiff --headers-dir2 /some/path \
213 --headers-dir2 /some/other/path \
214 binary-version-1 binary-version-2
215 • --header-file2 | --hf2 <header-file-path-2>
217 Specifies where to find one public header of the second shared li‐
219 brary that the tool has to consider. The tool will thus filter
220 out ABI changes on types that are not defined in public headers.
221 • --no-linux-kernel-mode
223 Without this option, if abidiff detects that the binaries it is
225 looking at are Linux Kernel binaries (either vmlinux or modules)
226 then it only considers functions and variables which ELF symbols
227 are listed in the __ksymtab and __ksymtab_gpl sections.
228 With this option, abidiff considers the binary as a non-special
230 ELF binary. It thus considers functions and variables which are
231 defined and exported in the ELF sense.
232 • --kmi-whitelist | -kaw <path-to-whitelist>
234 When analyzing a Linux kernel binary, this option points to the
236 white list of names of ELF symbols of functions and variables
237 which ABI must be considered. That white list is called a “Kernel
238 Module Interface white list”. This is because for the Kernel, we
239 don’t talk about ABI; we rather talk about the interface between
240 the Kernel and its module. Hence the term KMI rather than ABI.
241 Any other function or variable which ELF symbol are not present in
243 that white list will not be considered by this tool.
244 If this option is not provided – thus if no white list is provided
246 – then the entire KMI, that is, the set of all publicly defined
247 and exported functions and global variables by the Linux Kernel
248 binaries, is considered.
249 • --drop-private-types
251 This option is to be used with the --headers-dir1, header-file1,
253 header-file2 and --headers-dir2 options. With this option, types
254 that are NOT defined in the headers are entirely dropped from the
255 internal representation build by Libabigail to represent the ABI.
256 They thus don’t have to be filtered out from the final ABI change
257 report because they are not even present in Libabigail’s represen‐
258 tation.
259 Without this option however, those private types are kept in the
261 internal representation and later filtered out from the report.
262 This options thus potentially makes Libabigail consume less mem‐
264 ory. It’s meant to be mainly used to optimize the memory consump‐
265 tion of the tool on binaries with a lot of publicly defined and
266 exported types.
267 • --exported-interfaces-only
269 By default, when looking at the debug information accompanying a
271 binary, this tool analyzes the descriptions of the types reachable
272 by the interfaces (functions and variables) that are visible out‐
273 side of their translation unit. Once that analysis is done, an
274 ABI corpus is constructed by only considering the subset of types
275 reachable from interfaces associated to ELF symbols that are de‐
276 fined and exported by the binary. It’s those final ABI Corpora
277 that are compared by this tool.
278 The problem with that approach however is that analyzing all the
280 interfaces that are visible from outside their translation unit
281 can amount to a lot of data, especially when those binaries are
282 applications, as opposed to shared libraries. One example of such
283 applications is the
284 `Linux Kernel`_
285 . Analyzing massive ABI corpora like these can be extremely slow.
286 To mitigate that performance issue, this option allows libabigail
288 to only analyze types that are reachable from interfaces associ‐
289 ated with defined and exported ELF symbols.
290 Note that this option is turned on by default when analyzing the
292 `Linux Kernel`_
294 . Otherwise, it’s turned off by default.
295 • --allow-non-exported-interfaces
297 When looking at the debug information accompanying a binary, this
299 tool analyzes the descriptions of the types reachable by the in‐
300 terfaces (functions and variables) that are visible outside of
301 their translation unit. Once that analysis is done, an ABI corpus
302 is constructed by only considering the subset of types reachable
303 from interfaces associated to ELF symbols that are defined and ex‐
304 ported by the binary. It’s those final ABI Corpora that are com‐
305 pared by this tool.
306 The problem with that approach however is that analyzing all the
308 interfaces that are visible from outside their translation unit
309 can amount to a lot of data, especially when those binaries are
310 applications, as opposed to shared libraries. One example of such
311 applications is the
312 `Linux Kernel`_
313 . Analyzing massive ABI Corpora like these can be extremely slow.
314 In the presence of an “average sized” binary however one can af‐
316 ford having libabigail analyze all interfaces that are visible
317 outside of their translation unit, using this option.
318 Note that this option is turned on by default, unless we are in
320 the presence of the
321 `Linux Kernel`_
322 .
323 • --stat
325 Rather than displaying the detailed ABI differences between
327 first-shared-library and second-shared-library, just display some
328 summary statistics about these differences.
329 • --symtabs
331 Only display the symbol tables of the first-shared-library and
333 second-shared-library.
334 • --deleted-fns
336 In the resulting report about the differences between
338 first-shared-library and second-shared-library, only display the
339 globally defined functions that got deleted from first-shared-li‐
340 brary.
341 • --changed-fns
343 In the resulting report about the differences between
345 first-shared-library and second-shared-library, only display the
346 changes in sub-types of the global functions defined in
347 first-shared-library.
348 • --added-fns
350 In the resulting report about the differences between
352 first-shared-library and second-shared-library, only display the
353 globally defined functions that were added to second-shared-li‐
354 brary.
355 • --deleted-vars
357 In the resulting report about the differences between
359 first-shared-library and second-shared-library, only display the
360 globally defined variables that were deleted from first-shared-li‐
361 brary.
362 • --changed-vars
364 In the resulting report about the differences between
366 first-shared-library and second-shared-library, only display the
367 changes in the sub-types of the global variables defined in
368 first-shared-library
369 • --added-vars
371 In the resulting report about the differences between
373 first-shared-library and second-shared-library, only display the
374 global variables that were added (defined) to second-shared-li‐
375 brary.
376 • --non-reachable-types|-t
378 Analyze and emit change reports for all the types of the binary,
380 including those that are not reachable from global functions and
381 variables.
382 This option might incur some serious performance degradation as
384 the number of types analyzed can be huge. However, if paired with
385 the --headers-dir{1,2} and/or header-file{1,2} options, the addi‐
386 tional non-reachable types analyzed are restricted to those de‐
387 fined in public headers files, thus hopefully making the perfor‐
388 mance hit acceptable.
389 Also, using this option alongside suppression specifications (by
391 also using the --suppressions option) might help keep the number
392 of analyzed types (and the potential performance degradation) in
393 control.
394 Note that without this option, only types that are reachable from
396 global functions and variables are analyzed, so the tool detects
397 and reports changes on these reachable types only.
398 • --no-added-syms
400 In the resulting report about the differences between
402 first-shared-library and second-shared-library, do not display
403 added functions or variables. Do not display added functions or
404 variables ELF symbols either. All other kinds of changes are dis‐
405 played unless they are explicitely forbidden by other options on
406 the command line.
407 • --no-linkage-name
409 In the resulting report, do not display the linkage names of the
411 added, removed, or changed functions or variables.
412 • --no-show-locs
414 Do not show information about where in the second shared library
415 the respective type was changed.
416 • --show-bytes
418 Show sizes and offsets in bytes, not bits. By default, sizes and
420 offsets are shown in bits.
421 • --show-bits
423 Show sizes and offsets in bits, not bytes. This option is acti‐
425 vated by default.
426 • --show-hex
428 Show sizes and offsets in hexadecimal base.
430 • --show-dec
432 Show sizes and offsets in decimal base. This option is activated
434 by default.
435 • --ignore-soname
437 Ignore differences in the SONAME when doing a comparison
439 • --no-show-relative-offset-changes
441 Without this option, when the offset of a data member changes, the
443 change report not only mentions the older and newer offset, but it
444 also mentions by how many bits the data member changes. With this
445 option, the latter is not shown.
446 • --no-unreferenced-symbols
448 In the resulting report, do not display change information about
450 function and variable symbols that are not referenced by any debug
451 information. Note that for these symbols not referenced by any
452 debug information, the change information displayed is either
453 added or removed symbols.
454 • --no-default-suppression
456 Do not load the default suppression specification files.
458 • --suppressions | --suppr <path-to-suppressions>
460 Use a suppression specification file located at path-to-suppres‐
462 sions. Note that this option can appear multiple times on the
463 command line. In that case, all of the provided suppression spec‐
464 ification files are taken into account.
465 Please note that, by default, if this option is not provided, then
467 the default suppression specification files are loaded .
468 • --drop <regex>
470 When reading the first-shared-library and second-shared-library
472 ELF input files, drop the globally defined functions and variables
473 which name match the regular expression regex. As a result, no
474 change involving these functions or variables will be emitted in
475 the diff report.
476 • --drop-fn <regex>
478 When reading the first-shared-library and second-shared-library
480 ELF input files, drop the globally defined functions which name
481 match the regular expression regex. As a result, no change in‐
482 volving these functions will be emitted in the diff report.
483 • --drop-var <regex>
485 When reading the first-shared-library and second-shared-library
487 ELF input files, drop the globally defined variables matching a
488 the regular expression regex.
489 • --keep <regex>
491 When reading the first-shared-library and second-shared-library
493 ELF input files, keep the globally defined functions and variables
494 which names match the regular expression regex. All other func‐
495 tions and variables are dropped on the floor and will thus not ap‐
496 pear in the resulting diff report.
497 • --keep-fn <regex>
499 When reading the first-shared-library and second-shared-library
501 ELF input files, keep the globally defined functions which name
502 match the regular expression regex. All other functions are
503 dropped on the floor and will thus not appear in the resulting
504 diff report.
505 • --keep-var <regex>
507 When reading the first-shared-library and second-shared-library
509 ELF input files, keep the globally defined which names match the
510 regular expression regex. All other variables are dropped on the
511 floor and will thus not appear in the resulting diff report.
512 • --harmless
514 In the diff report, display only the harmless changes. By de‐
516 fault, the harmless changes are filtered out of the diff report
517 keep the clutter to a minimum and have a greater chance to spot
518 real ABI issues.
519 • --no-harmful
521 In the diff report, do not display the harmful changes. By de‐
523 fault, only the harmful changes are displayed in diff report.
524 • --redundant
526 In the diff report, do display redundant changes. A redundant
528 change is a change that has been displayed elsewhere in the re‐
529 port.
530 • --no-redundant
532 In the diff report, do NOT display redundant changes. A redundant
534 change is a change that has been displayed elsewhere in the re‐
535 port. This option is switched on by default.
536 • --no-architecture
538 Do not take architecture in account when comparing ABIs.
540 • --no-corpus-path
542 Do not emit the path attribute for the ABI corpus.
544 • --fail-no-debug-info
546 If no debug info was found, then this option makes the program to
548 fail. Otherwise, without this option, the program will attempt to
549 compare properties of the binaries that are not related to debug
550 info, like pure ELF properties.
551 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
553 pact analysis report. This option implies --redundant.
554 The typical output of abidiff when comparing two binaries looks
556 like this
557 $ abidiff libtest-v0.so libtest-v1.so
559 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
560 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
561 1 function with some indirect sub-type change:
563 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
565 parameter 1 of type 'C&' has sub-type changes:
566 in referenced type 'struct C' at test-v1.cc:7:1:
567 type size hasn't changed
568 1 data member change:
569 type of 'leaf* C::m0' changed:
570 in pointed to type 'struct leaf' at test-v1.cc:1:1:
571 type size changed from 32 to 64 bits
572 1 data member insertion:
573 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
574 $
576 So in that example the report emits information about how the data
578 member insertion change of “struct leaf” is reachable from func‐
579 tion “void fn(C&)”. In other words, the report not only shows the
580 data member change on “struct leaf”, but it also shows the impact
581 of that change on the function “void fn(C&)”.
582 In abidiff parlance, the change on “struct leaf” is called a leaf
584 change. So the --leaf-changes-only --impacted-interfaces options
585 show, well, only the leaf change. And it goes like this:
586 $ abidiff -l libtest-v0.so libtest-v1.so
588 'struct leaf' changed:
589 type size changed from 32 to 64 bits
590 1 data member insertion:
591 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
592 one impacted interface:
594 function void fn(C&)
595 $
596 Note how the report ends by showing the list of interfaces im‐
598 pacted by the leaf change.
599 Now if you don’t want to see that list of impacted interfaces,
601 then you can just avoid using the --impacted-interface option.
602 You can learn about that option below, in any case.
603 • --impacted-interfaces
605 When showing leaf changes, this option instructs abidiff to show
607 the list of impacted interfaces. This option is thus to be used
608 in addition the --leaf-changes-only option, otherwise, it’s ig‐
609 nored.
610 • --dump-diff-tree
612 After the diff report, emit a textual representation of the diff
613 nodes tree used by the comparison engine to represent the
614 changed functions and variables. That representation is emitted
615 to the error output for debugging purposes. Note that this diff
616 tree is relevant only to functions and variables that have some
617 sub-type changes. Added or removed functions and variables do
618 not have any diff nodes tree associated to them.
619 • --no-assume-odr-for-cplusplus
621 When analysing a binary originating from C++ code using DWARF de‐
623 bug information, libabigail assumes the One Definition Rule to
624 speed-up the analysis. In that case, when several types have the
625 same name in the binary, they are assumed to all be equal.
626 This option disables that assumption and instructs libabigail to
628 actually actually compare the types to determine if they are
629 equal.
630 • --no-leverage-dwarf-factorization
632 When analysing a binary which DWARF debug information was pro‐
634 cessed with the DWZ tool, the type information is supposed to be
635 already factorized. That context is used by libabigail to perform
636 some speed optimizations.
637 This option disables those optimizations.
639 • --ctf
641 When comparing binaries, extract ABI information from CTF debug
643 information, if present.
644 • --stats
646 Emit statistics about various internal things.
648 • --verbose
650 Emit verbose logs about the progress of miscellaneous internal
652 things.
653 Return values
655 The exit code of the abidiff command is either 0 if the ABI of the bi‐
656 naries being compared are equal, or non-zero if they differ or if the
657 tool encountered an error.
658 In the later case, the exit code is a 8-bits-wide bit field in which
660 each bit has a specific meaning.
661 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
663 ror.
664 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
666 an error in the way the user invoked the tool. It might be set, for
667 instance, if the user invoked the tool with an unknown command line
668 switch, with a wrong number or argument, etc. If this bit is set, then
669 the ABIDIFF_ERROR bit must be set as well.
670 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
672 the binaries being compared are different.
673 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
675 the ABI of the binaries compared are different in an incompatible way.
676 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
677 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
678 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
679 or might not be compatible. In that case, a human being needs to re‐
680 view the ABI changes to decide if they are compatible or not.
681 Note that, at the moment, there are only a few kinds of ABI changes
683 that would result in setting the flag ABIDIFF_ABI_INCOMPATIBLE_CHANGE.
684 Those ABI changes are either:
685 • the removal of the symbol of a function or variable that has been
687 defined and exported.
688 • the modification of the index of a member of a virtual function
690 table (for C++ programs and libraries).
691 With time, when more ABI change patterns are found to always constitute
693 incompatible ABI changes, we will adapt the code to recognize those
694 cases and set the ABIDIFF_ABI_INCOMPATIBLE_CHANGE accordingly. So, if
695 you find such patterns, please let us know.
696 The remaining bits are not used for the moment.
698 Usage examples
700 1. Detecting a change in a sub-type of a function:
701 $ cat -n test-v0.cc
703 1 // Compile this with:
704 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
705 3
706 4 struct S0
707 5 {
708 6 int m0;
709 7 };
710 8
711 9 void
712 10 foo(S0* /*parameter_name*/)
713 11 {
714 12 // do something with parameter_name.
715 13 }
716 $
717 $ cat -n test-v1.cc
718 1 // Compile this with:
719 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
720 3
721 4 struct type_base
722 5 {
723 6 int inserted;
724 7 };
725 8
726 9 struct S0 : public type_base
727 10 {
728 11 int m0;
729 12 };
730 13
731 14 void
732 15 foo(S0* /*parameter_name*/)
733 16 {
734 17 // do something with parameter_name.
735 18 }
736 $
737 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
738 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
739 $
740 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
741 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
742 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
743 1 function with some indirect sub-type change:
745 [C]'function void foo(S0*)' has some indirect sub-type changes:
747 parameter 0 of type 'S0*' has sub-type changes:
748 in pointed to type 'struct S0':
749 size changed from 32 to 64 bits
750 1 base class insertion:
751 struct type_base
752 1 data member change:
753 'int S0::m0' offset changed from 0 to 32
754 $
755 2. Detecting another change in a sub-type of a function:
757 $ cat -n test-v0.cc
759 1 // Compile this with:
760 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
761 3
762 4 struct S0
763 5 {
764 6 int m0;
765 7 };
766 8
767 9 void
768 10 foo(S0& /*parameter_name*/)
769 11 {
770 12 // do something with parameter_name.
771 13 }
772 $
773 $ cat -n test-v1.cc
774 1 // Compile this with:
775 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
776 3
777 4 struct S0
778 5 {
779 6 char inserted_member;
780 7 int m0;
781 8 };
782 9
783 10 void
784 11 foo(S0& /*parameter_name*/)
785 12 {
786 13 // do something with parameter_name.
787 14 }
788 $
789 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
790 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
791 $
792 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
793 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
794 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
795 1 function with some indirect sub-type change:
797 [C]'function void foo(S0&)' has some indirect sub-type changes:
799 parameter 0 of type 'S0&' has sub-type changes:
800 in referenced type 'struct S0':
801 size changed from 32 to 64 bits
802 1 data member insertion:
803 'char S0::inserted_member', at offset 0 (in bits)
804 1 data member change:
805 'int S0::m0' offset changed from 0 to 32
806 $
809 3. Detecting that functions got removed or added to a library:
811 $ cat -n test-v0.cc
813 1 // Compile this with:
814 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
815 3
816 4 struct S0
817 5 {
818 6 int m0;
819 7 };
820 8
821 9 void
822 10 foo(S0& /*parameter_name*/)
823 11 {
824 12 // do something with parameter_name.
825 13 }
826 $
827 $ cat -n test-v1.cc
828 1 // Compile this with:
829 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
830 3
831 4 struct S0
832 5 {
833 6 char inserted_member;
834 7 int m0;
835 8 };
836 9
837 10 void
838 11 bar(S0& /*parameter_name*/)
839 12 {
840 13 // do something with parameter_name.
841 14 }
842 $
843 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
844 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
845 $
846 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
847 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
848 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
849 1 Removed function:
851 'function void foo(S0&)' {_Z3fooR2S0}
852 1 Added function:
854 'function void bar(S0&)' {_Z3barR2S0}
855 $
857 abipkgdiff
859 abipkgdiff compares the Application Binary Interfaces (ABI) of the ELF
860 binaries contained in two software packages. The software package for‐
861 mats currently supported are Deb, RPM, tar archives (either compressed
862 or not) and plain directories that contain binaries.
863 For a comprehensive ABI change report that includes changes about func‐
865 tion and variable sub-types, the two input packages must be accompanied
866 with their debug information packages that contain debug information
867 either in DWARF or in CTF formats. Please note however that some pack‐
868 ages contain binaries that embed the debug information directly in a
869 section of said binaries. In those cases, obviously, no separate debug
870 information package is needed as the tool will find the debug informa‐
871 tion inside the binaries.
872 By default, abipkgdiff uses debug information in DWARF format, if
874 present, otherwise it compares binaries interfaces using debug informa‐
875 tion in CTF format, if present, finally, if neither is found, it uses
876 only ELF symbols to report which of them were added or removed.
877 This tool uses the libabigail library to analyze the binary as well as
879 its associated debug information. Here is its general mode of opera‐
880 tion.
881 When instructed to do so, a binary and its associated debug information
883 is read and analyzed. To that effect, libabigail analyzes by default
884 the descriptions of the types reachable by the interfaces (functions
885 and variables) that are visible outside of their translation unit.
886 Once that analysis is done, an Application Binary Interface Corpus is
887 constructed by only considering the subset of types reachable from in‐
888 terfaces associated to ELF symbols that are defined and exported by the
889 binary. It’s that final ABI corpus which libabigail considers as rep‐
890 resenting the ABI of the analyzed binary.
891 Libabigail then has capabilities to generate textual representations of
893 ABI Corpora, compare them, analyze their changes and report about them.
894 Invocation
896 abipkgdiff [option] <package1> <package2>
897 package1 and package2 are the packages that contain the binaries to be
899 compared.
900 Environment
902 abipkgdiff loads two default suppression specifications files, merges
903 their content and use it to filter out ABI change reports that might be
904 considered as false positives to users.
905 • Default system-wide suppression specification file
907 It’s located by the optional environment variable LIBABIGAIL_DE‐
909 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
910 set, then abipkgdiff tries to load the suppression file $lib‐
911 dir/libabigail/libabigail-default.abignore. If that file is not
912 present, then no default system-wide suppression specification file
913 is loaded.
914 • Default user suppression specification file.
916 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
918 PRESSION_FILE. If that environment variable is not set, then abip‐
919 kgdiff tries to load the suppression file $HOME/.abignore. If that
920 file is not present, then no default user suppression specification
921 is loaded.
922 In addition to those default suppression specification files, abip‐
924 kgdiff will also look inside the packages being compared and if it sees
925 a file that ends with the extension .abignore, then it will consider it
926 as a suppression specification and it will combine it to the default
927 suppression specification that might be already loaded.
928 The user might as well use the --suppressions option (that is docu‐
930 mented further below) to provide a suppression specification.
931 Options
933 • --help | -h
934 Display a short help about the command and exit.
936 • –version | -v
938 Display the version of the program and exit.
940 • --debug-info-pkg1 | --d1 <path>
942 For cases where the debug information for package1 is split out
944 into a separate file, tells abipkgdiff where to find that separate
945 debug information package.
946 Note that the debug info for package1 can have been split into
948 several different debug info packages. In that case, several in‐
949 stances of this options can be provided, along with those several
950 different debug info packages.
951 • --debug-info-pkg2 | --d2 <path>
953 For cases where the debug information for package2 is split out
955 into a separate file, tells abipkgdiff where to find that separate
956 debug information package.
957 Note that the debug info for package2 can have been split into
959 several different debug info packages. In that case, several in‐
960 stances of this options can be provided, along with those several
961 different debug info packages.
962 • --devel-pkg1 | --devel1 <path>
964 Specifies where to find the Development Package associated with
966 the first package to be compared. That Development Package at
967 path should at least contain header files in which public types
968 exposed by the libraries (of the first package to be compared) are
969 defined. When this option is provided, the tool filters out re‐
970 ports about ABI changes to types that are NOT defined in these
971 header files.
972 • --devel-pkg2 | --devel2 <path>
974 Specifies where to find the Development Package associated with
976 the second package to be compared. That Development Package at
977 path should at least contains header files in which public types
978 exposed by the libraries (of the second package to be compared)
979 are defined. When this option is provided, the tool filters out
980 reports about ABI changes to types that are NOT defined in these
981 header files.
982 • --drop-private-types
984 This option is to be used with the --devel-pkg1 and --devel-pkg2
986 options. With this option, types that are NOT defined in the
987 headers are entirely dropped from the internal representation
988 build by Libabigail to represent the ABI. They thus don’t have to
989 be filtered out from the final ABI change report because they are
990 not even present in Libabigail’s representation.
991 Without this option however, those private types are kept in the
993 internal representation and later filtered out from the report.
994 This options thus potentially makes Libabigail consume less mem‐
996 ory. It’s meant to be mainly used to optimize the memory consump‐
997 tion of the tool on binaries with a lot of publicly defined and
998 exported types.
999 • --dso-only
1001 Compare ELF files that are shared libraries, only. Do not compare
1003 executable files, for instance.
1004 • --private-dso
1006 By default, abipkgdiff does not compare DSOs that are private to
1008 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
1009 vertised in the “provides” property of the RPM.
1010 This option instructs abipkgdiff to also compare DSOs that are NOT
1012 advertised in the “provides” property of the RPM.
1013 Please note that the fact that (by default) abipkgdiff skips pri‐
1015 vate DSO is a feature that is available only for RPMs, at the mo‐
1016 ment. We would happily accept patches adding that feature for
1017 other package formats.
1018 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
1020 pact analysis report. This option implies --redundant
1021 The typical output of abipkgdiff and abidiff when comparing two
1023 binaries, that we shall call full impact report, looks like this
1024 $ abidiff libtest-v0.so libtest-v1.so
1026 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
1027 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1028 1 function with some indirect sub-type change:
1030 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
1032 parameter 1 of type 'C&' has sub-type changes:
1033 in referenced type 'struct C' at test-v1.cc:7:1:
1034 type size hasn't changed
1035 1 data member change:
1036 type of 'leaf* C::m0' changed:
1037 in pointed to type 'struct leaf' at test-v1.cc:1:1:
1038 type size changed from 32 to 64 bits
1039 1 data member insertion:
1040 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1041 $
1043 So in that example the report emits information about how the data
1045 member insertion change of “struct leaf” is reachable from func‐
1046 tion “void fn(C&)”. In other words, the report not only shows the
1047 data member change on “struct leaf”, but it also shows the impact
1048 of that change on the function “void fn(C&)”.
1049 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
1051 is called a leaf change. So the --leaf-changes-only --im‐
1052 pacted-interfaces options show, well, only the leaf change. And
1053 it goes like this:
1054 $ abidiff -l libtest-v0.so libtest-v1.so
1056 'struct leaf' changed:
1057 type size changed from 32 to 64 bits
1058 1 data member insertion:
1059 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1060 one impacted interface:
1062 function void fn(C&)
1063 $
1064 Note how the report ends up by showing the list of interfaces im‐
1066 pacted by the leaf change. That’s the effect of the additional
1067 --impacted-interfaces option.
1068 Now if you don’t want to see that list of impacted interfaces,
1070 then you can just avoid using the --impacted-interface option.
1071 You can learn about that option below, in any case.
1072 Please note that when comparing two Linux Kernel packages, it’s
1074 this leaf changes report that is emitted, by default. The normal
1075 so-called full impact report can be emitted with the option
1076 --full-impact which is documented later below.
1077 • --impacted-interfaces
1079 When showing leaf changes, this option instructs abipkgdiff to
1081 show the list of impacted interfaces. This option is thus to be
1082 used in addition to the --leaf-changes-only option, or, when com‐
1083 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
1084 • --full-impact|-f
1086 When comparing two Linux Kernel packages, this function instructs
1088 abipkgdiff to emit the so-called full impact report, which is the
1089 default report kind emitted by the abidiff tool:
1090 $ abidiff libtest-v0.so libtest-v1.so
1092 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
1093 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1094 1 function with some indirect sub-type change:
1096 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
1098 parameter 1 of type 'C&' has sub-type changes:
1099 in referenced type 'struct C' at test-v1.cc:7:1:
1100 type size hasn't changed
1101 1 data member change:
1102 type of 'leaf* C::m0' changed:
1103 in pointed to type 'struct leaf' at test-v1.cc:1:1:
1104 type size changed from 32 to 64 bits
1105 1 data member insertion:
1106 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1107 $
1109 • --non-reachable-types|-t
1111 Analyze and emit change reports for all the types of the binary,
1113 including those that are not reachable from global functions and
1114 variables.
1115 This option might incur some serious performance degradation as
1117 the number of types analyzed can be huge. However, if paired with
1118 the --devel-pkg{1,2} options, the additional non-reachable types
1119 analyzed are restricted to those defined in the public headers
1120 files carried by the referenced development packages, thus hope‐
1121 fully making the performance hit acceptable.
1122 Also, using this option alongside suppression specifications (by
1124 also using the --suppressions option) might help keep the number
1125 of analyzed types (and the potential performance degradation) in
1126 control.
1127 Note that without this option, only types that are reachable from
1129 global functions and variables are analyzed, so the tool detects
1130 and reports changes on these reachable types only.
1131 • --exported-interfaces-only
1133 By default, when looking at the debug information accompanying a
1135 binary, this tool analyzes the descriptions of the types reachable
1136 by the interfaces (functions and variables) that are visible out‐
1137 side of their translation unit. Once that analysis is done, an
1138 ABI corpus is constructed by only considering the subset of types
1139 reachable from interfaces associated to ELF symbols that are de‐
1140 fined and exported by the binary. It’s those final ABI Corpora
1141 that are compared by this tool.
1142 The problem with that approach however is that analyzing all the
1144 interfaces that are visible from outside their translation unit
1145 can amount to a lot of data, especially when those binaries are
1146 applications, as opposed to shared libraries. One example of such
1147 applications is the
1148 `Linux Kernel`_
1149 . Analyzing massive ABI corpora like these can be extremely slow.
1150 To mitigate that performance issue, this option allows libabigail
1152 to only analyze types that are reachable from interfaces associ‐
1153 ated with defined and exported ELF symbols.
1154 Note that this option is turned on by default when analyzing the
1156 `Linux Kernel`_
1158 . Otherwise, it’s turned off by default.
1159 • --allow-non-exported-interfaces
1161 When looking at the debug information accompanying a binary, this
1163 tool analyzes the descriptions of the types reachable by the in‐
1164 terfaces (functions and variables) that are visible outside of
1165 their translation unit. Once that analysis is done, an ABI corpus
1166 is constructed by only considering the subset of types reachable
1167 from interfaces associated to ELF symbols that are defined and ex‐
1168 ported by the binary. It’s those final ABI Corpora that are com‐
1169 pared by this tool.
1170 The problem with that approach however is that analyzing all the
1172 interfaces that are visible from outside their translation unit
1173 can amount to a lot of data, especially when those binaries are
1174 applications, as opposed to shared libraries. One example of such
1175 applications is the
1176 `Linux Kernel`_
1177 . Analyzing massive ABI Corpora like these can be extremely slow.
1178 In the presence of an “average sized” binary however one can af‐
1180 ford having libabigail analyze all interfaces that are visible
1181 outside of their translation unit, using this option.
1182 Note that this option is turned on by default, unless we are in
1184 the presence of the
1185 `Linux Kernel`_
1186 .
1187 • --redundant
1189 In the diff reports, do display redundant changes. A redundant
1190 change is a change that has been displayed elsewhere in a given
1191 report.
1192 • --harmless
1194 In the diff report, display only the harmless changes. By de‐
1196 fault, the harmless changes are filtered out of the diff report
1197 keep the clutter to a minimum and have a greater chance to spot
1198 real ABI issues.
1199 • --no-linkage-name
1201 In the resulting report, do not display the linkage names of the
1203 added, removed, or changed functions or variables.
1204 • --no-added-syms
1206 Do not show the list of functions, variables, or any symbol that
1208 was added.
1209 • --no-added-binaries
1211 Do not show the list of binaries that got added to the second
1213 package.
1214 Please note that the presence of such added binaries is not con‐
1216 sidered like an ABI change by this tool; as such, it doesn’t have
1217 any impact on the exit code of the tool. It does only have an in‐
1218 formational value. Removed binaries are, however, considered as
1219 an ABI change.
1220 • --no-abignore
1222 Do not search the package for the presence of suppression files.
1224 • --no-parallel
1226 By default, abipkgdiff will use all the processors it has avail‐
1228 able to execute concurrently. This option tells it not to extract
1229 packages or run comparisons in parallel.
1230 • --no-default-suppression
1232 Do not load the default suppression specification files.
1234 • --suppressions | --suppr <path-to-suppressions>
1236 Use a suppression specification file located at path-to-suppres‐
1238 sions. Note that this option can appear multiple times on the
1239 command line. In that case, all of the suppression specification
1240 files are taken into account.
1241 Please note that, by default, if this option is not provided, then
1243 the default suppression specification files are loaded .
1244 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
1246 When comparing two Linux kernel RPM packages, this option points
1248 to the white list of names of ELF symbols of functions and vari‐
1249 ables that must be compared for ABI changes. That white list is
1250 called a “Linux kernel ABI white list”.
1251 Any other function or variable which ELF symbol are not present in
1253 that white list will not be considered by the ABI comparison
1254 process.
1255 If this option is not provided – thus if no white list is provided
1257 – then the ABI of all publicly defined and exported functions and
1258 global variables by the Linux Kernel binaries are compared.
1259 Please note that if a white list package is given in parameter,
1261 this option handles it just fine, like if the –wp option was used.
1262 • --wp <path-to-whitelist-package>
1264 When comparing two Linux kernel RPM packages, this option points
1266 an RPM package containining several white lists of names of ELF
1267 symbols of functions and variables that must be compared for ABI
1268 changes. Those white lists are called “Linux kernel ABI white
1269 lists”.
1270 From the content of that white list package, this program then
1272 chooses the appropriate Linux kernel ABI white list to consider
1273 when comparing the ABI of Linux kernel binaries contained in the
1274 Linux kernel packages provided on the command line.
1275 That choosen Linux kernel ABI white list contains the list of
1277 names of ELF symbols of functions and variables that must be com‐
1278 pared for ABI changes.
1279 Any other function or variable which ELF symbol are not present in
1281 that white list will not be considered by the ABI comparison
1282 process.
1283 Note that this option can be provided twice (not mor than twice),
1285 specifying one white list package for each Linux Kernel package
1286 that is provided on the command line.
1287 If this option is not provided – thus if no white list is provided
1289 – then the ABI of all publicly defined and exported functions and
1290 global variables by the Linux Kernel binaries are compared.
1291 • --no-unreferenced-symbols
1293 In the resulting report, do not display change information about
1295 function and variable symbols that are not referenced by any debug
1296 information. Note that for these symbols not referenced by any
1297 debug information, the change information displayed is either
1298 added or removed symbols.
1299 • --no-show-locs
1301 Do not show information about where in the second shared library
1302 the respective type was changed.
1303 • --show-bytes
1305 Show sizes and offsets in bytes, not bits. By default, sizes and
1307 offsets are shown in bits.
1308 • --show-bits
1310 Show sizes and offsets in bits, not bytes. This option is acti‐
1312 vated by default.
1313 • --show-hex
1315 Show sizes and offsets in hexadecimal base.
1317 • --show-dec
1319 Show sizes and offsets in decimal base. This option is activated
1321 by default.
1322 • --no-show-relative-offset-changes
1324 Without this option, when the offset of a data member changes, the
1326 change report not only mentions the older and newer offset, but it
1327 also mentions by how many bits the data member changes. With this
1328 option, the latter is not shown.
1329 • --show-identical-binaries
1331 Show the names of the all binaries compared, including the bina‐
1332 ries whose ABI compare equal. By default, when this option is
1333 not provided, only binaries with ABI changes are mentionned in
1334 the output.
1335 • --fail-no-dbg
1337 Make the program fail and return a non-zero exit code if couldn’t
1339 read any of the debug information that comes from the debug info
1340 packages that were given on the command line. If no debug info
1341 package were provided on the command line then this option is not
1342 active.
1343 Note that the non-zero exit code returned by the program as a re‐
1345 sult of this option is the constant ABIDIFF_ERROR. To know the
1346 numerical value of that constant, please refer to the exit code
1347 documentation.
1348 • --keep-tmp-files
1350 Do not erase the temporary directory files that are created during
1352 the execution of the tool.
1353 • --verbose
1355 Emit verbose progress messages.
1357 • --self-check
1359 This is used to test the underlying Libabigail library. When in
1361 used, the command expects only on input package, along with its
1362 associated debug info packages. The command then compares each
1363 binary inside the package against its own ABIXML representation.
1364 The result of the comparison should yield the empty set if Libabi‐
1365 gail behaves correctly. Otherwise, it means there is an issue
1366 that ought to be fixed. This option is used by people interested
1367 in Libabigail development for regression testing purposes. Here
1368 is an example of the use of this option:
1369 $ 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
1371 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
1372 $
1373 • --no-assume-odr-for-cplusplus
1375 When analysing a binary originating from C++ code using DWARF de‐
1377 bug information, libabigail assumes the One Definition Rule to
1378 speed-up the analysis. In that case, when several types have the
1379 same name in the binary, they are assumed to all be equal.
1380 This option disables that assumption and instructs libabigail to
1382 actually actually compare the types to determine if they are
1383 equal.
1384 • --no-leverage-dwarf-factorization
1386 When analysing a binary which DWARF debug information was pro‐
1388 cessed with the DWZ tool, the type information is supposed to be
1389 already factorized. That context is used by libabigail to perform
1390 some speed optimizations.
1391 This option disables those optimizations.
1393 • --ctf
1395 This is used to compare packages with CTF debug information,
1396 if present.
1397 Return value
1399 The exit code of the abipkgdiff command is either 0 if the ABI of the
1400 binaries compared are equal, or non-zero if they differ or if the tool
1401 encountered an error.
1402 In the later case, the value of the exit code is the same as for the
1404 abidiff tool.
1405 kmidiff
1407 kmidiff compares the binary Kernel Module Interfaces of two Linux Ker‐
1408 nel trees. The binary KMI is the interface that the Linux Kernel ex‐
1409 poses to its modules. The trees we are interested in here are the re‐
1410 sult of the build of the Linux Kernel source tree.
1411 General approach
1413 And example of how to build your kernel if you want to compare it to
1414 another one using kmidiff is:
1415 git clone -b v4.5 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux/v4.5
1417 cd linux/v4.5
1418 make allyesconfig all
1419 Then install the modules into a directory, for instance, the build/mod‐
1421 ules sub-directory of the your kernel source tree:
1422 mkdir build/modules
1424 make modules_install INSTALL_MOD_DIR=build/modules
1425 Then construct a list of interfaces exported by the kernel, that you
1427 want to compare:
1428 cat > kmi-whitelist << EOF
1430 [kernel_4.5_kmi_whitelist]
1431 init_task
1432 schedule
1433 dev_queue_xmit
1434 __kmalloc
1435 printk
1436 EOF
1437 Suppose you’ve done something similar for the v4.6 branch of the Linux
1439 kernel, you now have these two directories: linux/v4.5 and linux/v4.6.
1440 Their modules are present under the directories linux/v4.5/build/mod‐
1441 ules and linux/v4.6/build/modules.
1442 To Comparing their KMI kmidiff needs to know where to find the vmlinux
1444 binaries and their associated modules. Here would be what the command
1445 line looks like:
1446 kmidiff \
1448 --kmi-whitelist linux/v4.6/kmi-whitelist \
1449 --vmlinux1 linux/v4.5/vmlinux \
1450 --vmlinux2 linux/v4.6/vmlinux \
1451 linux/v4.5/build/modules \
1452 linux/v4.6/build/modules
1453 This tool uses the libabigail library to analyze the binary as well as
1455 its associated debug information. Here is its general mode of opera‐
1456 tion.
1457 When instructed to do so, a binary and its associated debug information
1459 is read and analyzed. To that effect, libabigail analyzes by default
1460 the descriptions of the types reachable by the interfaces (functions
1461 and variables) that are visible outside of their translation unit.
1462 Once that analysis is done, an Application Binary Interface Corpus is
1463 constructed by only considering the subset of types reachable from in‐
1464 terfaces associated to ELF symbols that are defined and exported by the
1465 binary. It’s that final ABI corpus which libabigail considers as rep‐
1466 resenting the ABI of the analyzed binary.
1467 Libabigail then has capabilities to generate textual representations of
1469 ABI Corpora, compare them, analyze their changes and report about them.
1470 Invocation
1472 More generally, kmidiff is invoked under the form:
1473 kmidiff [options] <first-modules-dir> <second-modules-dir>
1475 Environment
1477 By default, kmidiff compares all the interfaces (exported functions and
1478 variables) between the Kernel and its modules. In practice, though,
1479 some users might want to compare a subset of the those interfaces.
1480 By default, kmidiff uses debug information in DWARF format, if present,
1482 otherwise it compares interfaces using debug information in CTF format,
1483 if present, finally, if neither is found, it uses only ELF symbols to
1484 report which were added or removed.
1485 Users can then define a “white list” of the interfaces to compare.
1487 Such a white list is a just a file in the “INI” format that looks like:
1488 [kernel_version_x86_64_whitelist]
1490 function1_name
1491 function2_name
1492 global_variable1_name
1493 ....
1494 Note that the name of the section (the name that is between the two
1496 brackets) of that INI file just has to end with the string “whitelist”.
1497 So you can define the name you want, for instance [ker‐
1498 nel_46_x86_64_whitelist].
1499 Then each line of that whitelist file is the name of an exported func‐
1501 tion or variable. Only those interfaces along with the types reachable
1502 from their signatures are going to be compared by kmidiff recursively.
1503 Note that by default kmidiff analyzes the types reachable from the in‐
1505 terfaces associated with ELF symbols that are defined and exported by
1506 the Linux Kernel as being the union of the vmlinux binary and all its
1507 compiled modules. It then compares those interfaces (along with their
1508 types).
1509 Options
1511 • --help | -h
1512 Display a short help about the command and exit.
1514 • --version | -v
1516 Display the version of the program and exit.
1518 • --verbose
1520 Display some verbose messages while executing.
1522 • --debug-info-dir1 | --d1 <di-path1>
1524 For cases where the debug information for the binaries of the
1526 first Linux kernel is split out into separate files, tells kmidiff
1527 where to find those separate debug information files.
1528 Note that di-path must point to the root directory under which the
1530 debug information is arranged in a tree-like manner. Under Red
1531 Hat based systems, that directory is usually <root>/usr/lib/debug.
1532 • --debug-info-dir2 | --d2 <di-path2>
1534 Like --debug-info-dir1, this options tells kmidiff where to find
1536 the split debug information for the binaries of the second Linux
1537 kernel.
1538 • --vmlinux1 | --l1 <path-to-first-vmlinux>
1540 Sets the path to the first vmlinux binary to consider. This has
1542 to be the uncompressed vmlinux binary compiled with debug info.
1543 • --vmlinux2 | --l2 <path-to-first-vmlinux>
1545 Sets the path to the second vmlinux binary to consider. This has
1547 to be the uncompressed vmlinux binary compiled with debug info.
1548 • --kmi-whitelist | -w <path-to-interface-whitelist>
1550 Set the path to the white list of interfaces to compare while com‐
1552 paring the Kernel Module Interface of the first kernel against the
1553 one of the second kernel.
1554 If this option is not provided, all the exported interfaces of the
1556 two kernels are compared. That takes a lot of times and is not
1557 necessarily meaningful because many interface are probably meant
1558 to see their reachable types change.
1559 So please, make sure you always use this option unless you really
1561 know what you are doing.
1562 • --suppressions | --suppr <path-to-suppressions>
1564 Use a suppression specification file located at path-to-suppres‐
1566 sions. Note that this option can appear multiple times on the
1567 command line. In that case, all of the provided suppression spec‐
1568 ification files are taken into account.
1569 Please note that, by default, if this option is not provided, then
1571 the default suppression specification files are loaded .
1572 • --ctf
1574 Extract ABI information from CTF debug information, if present in
1576 the Kernel and Modules.
1577 • --impacted-interfaces | -i
1579 Tell what interfaces got impacted by each individual ABI change.
1581 • --full-impact | -f
1583 Emit a change report that shows the full impact of each change on
1585 exported interfaces. This is the default kind of report emitted
1586 by tools like abidiff or abipkgdiff.
1587 • --exported-interfaces-only
1589 When using this option, this tool analyzes the descriptions of the
1591 types reachable by the interfaces (functions and variables) asso‐
1592 ciated with ELF symbols that are defined and exported by the Linux
1593 Kernel.
1594 Otherwise, the tool also has the ability to analyze the descrip‐
1596 tions of the types reachable by the interfaces associated with ELF
1597 symbols that are visible outside their translation unit. This
1598 later possibility is however much more resource intensive and re‐
1599 sults in much slower operations.
1600 That is why this option is enabled by default.
1602 • --allow-non-exported-interfaces
1604 When using this option, this tool analyzes the descriptions of the
1606 types reachable by the interfaces (functions and variables) that
1607 are visible outside of their translation unit. Once that analysis
1608 is done, an ABI Corpus is constructed by only considering the sub‐
1609 set of types reachable from interfaces associated to ELF symbols
1610 that are defined and exported by the binary. It’s that final ABI
1611 corpus which is compared against another one.
1612 The problem with that approach however is that analyzing all the
1614 interfaces that are visible from outside their translation unit
1615 can amount to a lot of data, leading to very slow operations.
1616 Note that this option is turned off by default.
1618 • --show-bytes
1620 Show sizes and offsets in bytes, not bits. This option is acti‐
1622 vated by default.
1623 • --show-bits
1625 Show sizes and offsets in bits, not bytes. By default, sizes and
1627 offsets are shown in bytes.
1628 • --show-hex
1630 Show sizes and offsets in hexadecimal base. This option is acti‐
1632 vated by default.
1633 • --show-dec
1635 Show sizes and offsets in decimal base.
1637 abidw
1639 abidw reads a shared library in ELF format and emits an XML representa‐
1640 tion of its ABI to standard output. The emitted representation format,
1641 named ABIXML, includes all the globally defined functions and vari‐
1642 ables, along with a complete representation of their types. It also
1643 includes a representation of the globally defined ELF symbols of the
1644 file.
1645 When given the --linux-tree option, this program can also handle a
1647 Linux kernel tree. That is, a directory tree that contains both the
1648 vmlinux binary and Linux Kernel modules. It analyses those Linux Ker‐
1649 nel binaries and emits an XML representation of the interface between
1650 the kernel and its module, to standard output. In this case, we don’t
1651 call it an ABI, but a KMI (Kernel Module Interface). The emitted KMI
1652 includes all the globally defined functions and variables, along with a
1653 complete representation of their types.
1654 To generate either ABI or KMI representation, by default abidw uses de‐
1656 bug information in DWARF format, if present, otherwise it looks for de‐
1657 bug information in CTF format, if present, finally, if neither is
1658 found, it uses only ELF symbols to report which of them were added or
1659 removed.
1660 This tool uses the libabigail library to analyze the binary as well as
1662 its associated debug information. Here is its general mode of opera‐
1663 tion.
1664 When instructed to do so, a binary and its associated debug information
1666 is read and analyzed. To that effect, libabigail analyzes by default
1667 the descriptions of the types reachable by the interfaces (functions
1668 and variables) that are visible outside of their translation unit.
1669 Once that analysis is done, an Application Binary Interface Corpus is
1670 constructed by only considering the subset of types reachable from in‐
1671 terfaces associated to ELF symbols that are defined and exported by the
1672 binary. It’s that final ABI corpus which libabigail considers as rep‐
1673 resenting the ABI of the analyzed binary.
1674 Libabigail then has capabilities to generate textual representations of
1676 ABI Corpora, compare them, analyze their changes and report about them.
1677 Invocation
1679 abidw [options] [<path-to-elf-file>]
1680 Options
1682 • --help | -h
1683 Display a short help about the command and exit.
1685 • –version | -v
1687 Display the version of the program and exit.
1689 • –abixml-version
1691 Display the version of the ABIXML format emitted by this program
1693 and exit.
1694 • --debug-info-dir | -d <dir-path>
1696 In cases where the debug info for path-to-elf-file is in a sepa‐
1698 rate file that is located in a non-standard place, this tells
1699 abidw where to look for that debug info file.
1700 Note that dir-path must point to the root directory under which
1702 the debug information is arranged in a tree-like manner. Under
1703 Red Hat based systems, that directory is usually
1704 <root>/usr/lib/debug.
1705 This option can be provided several times with different root di‐
1707 rectories. In that case, abidw will potentially look into all
1708 those root directories to find the split debug info for the elf
1709 file.
1710 Note that this option is not mandatory for split debug information
1712 installed by your system’s package manager because then abidw
1713 knows where to find it.
1714 • --out-file <file-path>
1716 This option instructs abidw to emit the XML representation of
1718 path-to-elf-file into the file file-path, rather than emitting it
1719 to its standard output.
1720 • --noout
1722 This option instructs abidw to not emit the XML representation of
1724 the ABI. So it only reads the ELF and debug information, builds
1725 the internal representation of the ABI and exits. This option is
1726 usually useful for debugging purposes.
1727 • --no-corpus-path
1729 Do not emit the path attribute for the ABI corpus.
1731 • --suppressions | suppr <path-to-suppression-specifications-file>
1733 Use a suppression specification file located at path-to-suppres‐
1735 sion-specifications-file. Note that this option can appear multi‐
1736 ple times on the command line. In that case, all of the provided
1737 suppression specification files are taken into account. ABI arti‐
1738 facts matched by the suppression specifications are suppressed
1739 from the output of this tool.
1740 • --kmi-whitelist | -kaw <path-to-whitelist>
1742 When analyzing a Linux Kernel binary, this option points to the
1744 white list of names of ELF symbols of functions and variables
1745 which ABI must be written out. That white list is called a ” Ker‐
1746 nel Module Interface white list”. This is because for the Kernel,
1747 we don’t talk about the ABI; we rather talk about the interface
1748 between the Kernel and its module. Hence the term KMI rather than
1749 ABI
1750 Any other function or variable which ELF symbol are not present in
1752 that white list will not be considered by the KMI writing process.
1753 If this option is not provided – thus if no white list is provided
1755 – then the entire KMI, that is, all publicly defined and exported
1756 functions and global variables by the Linux Kernel binaries is
1757 emitted.
1758 • --linux-tree | --lt
1760 Make abidw to consider the input path as a path to a directory
1762 containing the vmlinux binary as several kernel modules binaries.
1763 In that case, this program emits the representation of the Kernel
1764 Module Interface (KMI) on the standard output.
1765 Below is an example of usage of abidw on a Linux Kernel tree.
1767 First, checkout a Linux Kernel source tree and build it. Then in‐
1769 stall the kernel modules in a directory somewhere. Copy the vm‐
1770 linux binary into that directory too. And then serialize the KMI
1771 of that kernel to disk, using abidw:
1772 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
1774 $ cd linux && git checkout v4.5
1775 $ make allyesconfig all
1776 $ mkdir build-output
1777 $ make INSTALL_MOD_PATH=./build-output modules_install
1778 $ cp vmlinux build-output/modules/4.5.0
1779 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
1780 • --headers-dir | --hd <headers-directory-path-1>
1782 Specifies where to find the public headers of the binary that the
1784 tool has to consider. The tool will thus filter out types that
1785 are not defined in public headers.
1786 Note that several public header directories can be specified for
1788 the binary to consider. In that case the --header-dir option
1789 should be present several times on the command line, like in the
1790 following example:
1791 $ abidw --header-dir /some/path \
1793 --header-dir /some/other/path \
1794 binary > binary.abi
1795 • --header-file | --hf <header-file-path>
1797 Specifies where to find one of the public headers of the abi file
1799 that the tool has to consider. The tool will thus filter out
1800 types that are not defined in public headers.
1801 • --drop-private-types
1803 This option is to be used with the --headers-dir and/or
1805 header-file options. With this option, types that are NOT defined
1806 in the headers are entirely dropped from the internal representa‐
1807 tion build by Libabigail to represent the ABI and will not end up
1808 in the abi XML file.
1809 • --no-elf-needed
1811 Do not include the list of DT_NEEDED dependency names in the cor‐
1813 pus.
1814 • --drop-undefined-syms
1816 With this option functions or variables for which the (exported)
1818 ELF symbol is undefined are dropped from the internal representa‐
1819 tion build by Libabigail to represent the ABI and will not end up
1820 in the abi XML file.
1821 • --exported-interfaces-only
1823 By default, when looking at the debug information accompanying a
1825 binary, this tool analyzes the descriptions of the types reachable
1826 by the interfaces (functions and variables) that are visible out‐
1827 side of their translation unit. Once that analysis is done, an
1828 ABI corpus is constructed by only considering the subset of types
1829 reachable from interfaces associated to ELF symbols that are de‐
1830 fined and exported by the binary. It’s that final ABI corpus
1831 which textual representation is saved as ABIXML.
1832 The problem with that approach however is that analyzing all the
1834 interfaces that are visible from outside their translation unit
1835 can amount to a lot of data, especially when those binaries are
1836 applications, as opposed to shared libraries. One example of such
1837 applications is the Linux Kernel. Analyzing massive ABI corpora
1838 like these can be extremely slow.
1839 To mitigate that performance issue, this option allows libabigail
1841 to only analyze types that are reachable from interfaces associ‐
1842 ated with defined and exported ELF symbols.
1843 Note that this option is turned on by default when analyzing the
1845 Linux Kernel. Otherwise, it’s turned off by default.
1846 • --allow-non-exported-interfaces
1848 When looking at the debug information accompanying a binary, this
1850 tool analyzes the descriptions of the types reachable by the in‐
1851 terfaces (functions and variables) that are visible outside of
1852 their translation unit. Once that analysis is done, an ABI corpus
1853 is constructed by only considering the subset of types reachable
1854 from interfaces associated to ELF symbols that are defined and ex‐
1855 ported by the binary. It’s that final ABI corpus which textual
1856 representation is saved as ABIXML.
1857 The problem with that approach however is that analyzing all the
1859 interfaces that are visible from outside their translation unit
1860 can amount to a lot of data, especially when those binaries are
1861 applications, as opposed to shared libraries. One example of such
1862 applications is the Linux Kernel. Analyzing massive ABI corpora
1863 like these can be extremely slow.
1864 In the presence of an “average sized” binary however one can af‐
1866 ford having libabigail analyze all interfaces that are visible
1867 outside of their translation unit, using this option.
1868 Note that this option is turned on by default, unless we are in
1870 the presence of the Linux Kernel.
1871 • --no-linux-kernel-mode
1873 Without this option, if abipkgiff detects that the binaries it is
1875 looking at are Linux Kernel binaries (either vmlinux or modules)
1876 then it only considers functions and variables which ELF symbols
1877 are listed in the __ksymtab and __ksymtab_gpl sections.
1878 With this option, abipkgdiff considers the binary as a non-special
1880 ELF binary. It thus considers functions and variables which are
1881 defined and exported in the ELF sense.
1882 • --check-alternate-debug-info <elf-path>
1884 If the debug info for the file elf-path contains a reference to an
1886 alternate debug info file, abidw checks that it can find that al‐
1887 ternate debug info file. In that case, it emits a meaningful suc‐
1888 cess message mentioning the full path to the alternate debug info
1889 file found. Otherwise, it emits an error code.
1890 • --no-show-locs
1892 In the emitted ABI representation, do not show file, line or
1893 column where ABI artifacts are defined.
1894 • --no-parameter-names
1896 In the emitted ABI representation, do not show names of function
1898 parameters, just the types.
1899 • --no-write-default-sizes
1901 In the XML ABI representation, do not write the size-in-bits for
1903 pointer type definitions, reference type definitions, function
1904 declarations and function types when they are equal to the default
1905 address size of the translation unit. Note that libabigail before
1906 1.8 will not set the default size and will interpret types without
1907 a size-in-bits attribute as zero sized.
1908 • --type-id-style <sequence``|``hash>
1910 This option controls how types are idenfied in the generated XML
1912 files. The default sequence style just numbers (with type-id- as
1913 prefix) the types in the order they are encountered. The hash
1914 style uses a (stable, portable) hash of libabigail’s internal type
1915 names and is intended to make the XML files easier to diff.
1916 • --check-alternate-debug-info-base-name <elf-path>
1918 Like --check-alternate-debug-info, but in the success message,
1920 only mention the base name of the debug info file; not its full
1921 path.
1922 • --load-all-types
1924 By default, libabigail (and thus abidw) only loads types that are
1926 reachable from functions and variables declarations that are pub‐
1927 licly defined and exported by the binary. So only those types are
1928 present in the output of abidw. This option however makes abidw
1929 load all the types defined in the binaries, even those that are
1930 not reachable from public declarations.
1931 • --abidiff
1933 Load the ABI of the ELF binary given in argument, save it in
1934 libabigail’s XML format in a temporary file; read the ABI from
1935 the temporary XML file and compare the ABI that has been read
1936 back against the ABI of the ELF binary given in argument. The
1937 ABIs should compare equal. If they don’t, the program emits a
1938 diagnostic and exits with a non-zero code.
1939 This is a debugging and sanity check option.
1941 • --debug-abidiff
1943 Same as --abidiff but in debug mode. In this mode, error mes‐
1945 sages are emitted for types which fail type canonicalization.
1946 This is an optional debugging and sanity check option. To en‐
1948 able it the libabigail package needs to be configured with the
1949 –enable-debug-self-comparison option.
1950 • --debug-type-canonicalization | --debug-tc
1952 Debug the type canonicalization process. This is done by using
1954 structural and canonical equality when canonicalizing every sin‐
1955 gle type. Structural and canonical equality should yield the
1956 same result. If they don’t yield the same result for a given
1957 type, then it means that the canonicalization of that type went
1958 wrong. In that case, an error message is emitted and the execu‐
1959 tion of the program is aborted.
1960 This option is available only if the package was configured with
1962 the –enable-debug-type-canonicalization option.
1963 • --no-assume-odr-for-cplusplus
1965 When analysing a binary originating from C++ code using DWARF de‐
1967 bug information, libabigail assumes the One Definition Rule to
1968 speed-up the analysis. In that case, when several types have the
1969 same name in the binary, they are assumed to all be equal.
1970 This option disables that assumption and instructs libabigail to
1972 actually actually compare the types to determine if they are
1973 equal.
1974 • --no-leverage-dwarf-factorization
1976 When analysing a binary which DWARF debug information was pro‐
1978 cessed with the DWZ tool, the type information is supposed to be
1979 already factorized. That context is used by libabigail to perform
1980 some speed optimizations.
1981 This option disables those optimizations.
1983 • --ctf
1985 Extract ABI information from CTF debug information, if present in
1987 the given object.
1988 • --annotate
1990 Annotate the ABIXML output with comments above most elements.
1991 The comments are made of the pretty-printed form types, declara‐
1992 tion or even ELF symbols. The purpose is to make the ABIXML
1993 output more human-readable for debugging or documenting pur‐
1994 poses.
1995 • --stats
1997 Emit statistics about various internal things.
1999 • --verbose
2001 Emit verbose logs about the progress of miscellaneous internal
2003 things.
2004 Notes
2006 Alternate debug info files
2007 As of the version 4 of the DWARF specification, Alternate debug infor‐
2008 mation is a GNU extension to the DWARF specification. It has however
2009 been proposed for inclusion into the upcoming version 5 of the DWARF
2010 standard. You can read more about the GNU extensions to the DWARF
2011 standard here.
2012 abicompat
2014 abicompat checks that an application that links against a given shared
2015 library is still ABI compatible with a subsequent version of that li‐
2016 brary. If the new version of the library introduces an ABI incompati‐
2017 bility, then abicompat hints the user at what exactly that incompati‐
2018 bility is.
2019 Invocation
2021 abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
2022 Options
2024 • --help
2025 Display a short help about the command and exit.
2027 • –version | -v
2029 Display the version of the program and exit.
2031 • --list-undefined-symbols | -u
2033 Display the list of undefined symbols of the application and exit.
2035 • --show-base-names | -b
2037 In the resulting report emitted by the tool, this option makes the
2039 application and libraries be referred to by their base names only;
2040 not by a full absolute name. This can be useful for use in
2041 scripts that wants to compare names of the application and li‐
2042 braries independently of what their directory names are.
2043 • --app-debug-info-dir | --appd <path-to-app-debug-info-directory>
2045 Set the path to the directory under which the debug information of
2047 the application is supposed to be laid out. This is useful for
2048 application binaries for which the debug info is in a separate set
2049 of files.
2050 • --lib-debug-info-dir1 | --libd1 <path-to-lib1-debug-info>
2052 Set the path to the directory under which the debug information of
2054 the first version of the shared library is supposed to be laid
2055 out. This is useful for shared library binaries for which the de‐
2056 bug info is in a separate set of files.
2057 • --lib-debug-info-dir2 | --libd2 <path-to-lib1-debug-info>
2059 Set the path to the directory under which the debug information of
2061 the second version of the shared library is supposed to be laid
2062 out. This is useful for shared library binaries for which the de‐
2063 bug info is in a separate set of files.
2064 • --suppressions | --suppr <path-to-suppressions>
2066 Use a suppression specification file located at path-to-suppres‐
2068 sions. Note that this option can appear multiple times on the
2069 command line; all the suppression specification files are then
2070 taken into account.
2071 • --no-show-locs
2073 Do not show information about where in the second shared library
2074 the respective type was changed.
2075 • --ctf
2077 When comparing binaries, extract ABI information from CTF debug
2079 information, if present.
2080 • --fail-no-debug-info
2082 If no debug info was found, then this option makes the program to
2084 fail. Otherwise, without this option, the program will attempt to
2085 compare properties of the binaries that are not related to debug
2086 info, like pure ELF properties.
2087 • --ignore-soname
2089 Ignore differences in the SONAME when doing a comparison
2091 • --weak-mode
2093 This triggers the weak mode of abicompat. In this mode, only one
2095 version of the library is required. That is, abicompat is invoked
2096 like this:
2097 abicompat --weak-mode <the-application> <the-library>
2099 Note that the --weak-mode option can even be omitted if only one
2101 version of the library is given, along with the application; in
2102 that case, abicompat automatically switches to operate in weak
2103 mode:
2104 abicompat <the-application> <the-library>
2106 In this weak mode, the types of functions and variables exported
2108 by the library and consumed by the application (as in, the symbols
2109 of the these functions and variables are undefined in the applica‐
2110 tion and are defined and exported by the library) are compared to
2111 the version of these types as expected by the application. And if
2112 these two versions of types are different, abicompat tells the
2113 user what the differences are.
2114 In other words, in this mode, abicompat checks that the types of
2116 the functions and variables exported by the library mean the same
2117 thing as what the application expects, as far as the ABI is con‐
2118 cerned.
2119 Note that in this mode, abicompat doesn’t detect exported func‐
2121 tions or variables (symbols) that are expected by the application
2122 but that are removed from the library. That is why it is called
2123 weak mode.
2124 Return values
2126 The exit code of the abicompat command is either 0 if the ABI of the
2127 binaries being compared are equal, or non-zero if they differ or if the
2128 tool encountered an error.
2129 In the later case, the exit code is a 8-bits-wide bit field in which
2131 each bit has a specific meaning.
2132 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
2134 ror.
2135 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
2137 an error in the way the user invoked the tool. It might be set, for
2138 instance, if the user invoked the tool with an unknown command line
2139 switch, with a wrong number or argument, etc. If this bit is set, then
2140 the ABIDIFF_ERROR bit must be set as well.
2141 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
2143 the binaries being compared are different.
2144 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
2146 the ABI of the binaries compared are different in an incompatible way.
2147 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
2148 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
2149 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
2150 or might not be compatible. In that case, a human being needs to re‐
2151 view the ABI changes to decide if they are compatible or not.
2152 The remaining bits are not used for the moment.
2154 Usage examples
2156 • Detecting a possible ABI incompatibility in a new shared library
2157 version:
2158 $ cat -n test0.h
2160 1 struct foo
2161 2 {
2162 3 int m0;
2163 4
2164 5 foo()
2165 6 : m0()
2166 7 {}
2167 8 };
2168 9
2169 10 foo*
2170 11 first_func();
2171 12
2172 13 void
2173 14 second_func(foo&);
2174 15
2175 16 void
2176 17 third_func();
2177 $
2178 $ cat -n test-app.cc
2180 1 // Compile with:
2181 2 // g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
2182 3
2183 4 #include "test0.h"
2184 5
2185 6 int
2186 7 main()
2187 8 {
2188 9 foo* f = first_func();
2189 10 second_func(*f);
2190 11 return 0;
2191 12 }
2192 $
2193 $ cat -n test0.cc
2195 1 // Compile this with:
2196 2 // g++ -g -Wall -shared -o libtest-0.so test0.cc
2197 3
2198 4 #include "test0.h"
2199 5
2200 6 foo*
2201 7 first_func()
2202 8 {
2203 9 foo* f = new foo();
2204 10 return f;
2205 11 }
2206 12
2207 13 void
2208 14 second_func(foo&)
2209 15 {
2210 16 }
2211 17
2212 18 void
2213 19 third_func()
2214 20 {
2215 21 }
2216 $
2217 $ cat -n test1.h
2219 1 struct foo
2220 2 {
2221 3 int m0;
2222 4 char m1; /* <-- a new member got added here! */
2223 5
2224 6 foo()
2225 7 : m0(),
2226 8 m1()
2227 9 {}
2228 10 };
2229 11
2230 12 foo*
2231 13 first_func();
2232 14
2233 15 void
2234 16 second_func(foo&);
2235 17
2236 18 void
2237 19 third_func();
2238 $
2239 $ cat -n test1.cc
2241 1 // Compile this with:
2242 2 // g++ -g -Wall -shared -o libtest-1.so test1.cc
2243 3
2244 4 #include "test1.h"
2245 5
2246 6 foo*
2247 7 first_func()
2248 8 {
2249 9 foo* f = new foo();
2250 10 return f;
2251 11 }
2252 12
2253 13 void
2254 14 second_func(foo&)
2255 15 {
2256 16 }
2257 17
2258 18 /* Let's comment out the definition of third_func()
2259 19 void
2260 20 third_func()
2261 21 {
2262 22 }
2263 23 */
2264 $
2265 • Compile the first and second versions of the libraries:
2267 libtest-0.so and libtest-1.so:
2268 $ g++ -g -Wall -shared -o libtest-0.so test0.cc
2270 $ g++ -g -Wall -shared -o libtest-1.so test1.cc
2271 • Compile the application and link it against the first version of
2273 the library, creating the test-app binary:
2274 $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
2276 • Now, use abicompat to see if libtest-1.so is ABI compatible with
2278 app, with respect to the ABI of libtest-0.so:
2279 $ abicompat test-app libtest-0.so libtest-1.so
2281 ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
2282 Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
2283 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
2284 2 functions with some indirect sub-type change:
2286 [C]'function foo* first_func()' has some indirect sub-type changes:
2288 return type changed:
2289 in pointed to type 'struct foo':
2290 size changed from 32 to 64 bits
2291 1 data member insertion:
2292 'char foo::m1', at offset 32 (in bits)
2293 [C]'function void second_func(foo&)' has some indirect sub-type changes:
2294 parameter 0 of type 'foo&' has sub-type changes:
2295 referenced type 'struct foo' changed, as reported earlier
2296 $
2298 • Now use the weak mode of abicompat, that is, providing just the
2300 application and the new version of the library:
2301 $ abicompat --weak-mode test-app libtest-1.so
2303 functions defined in library
2304 'libtest-1.so'
2305 have sub-types that are different from what application
2306 'test-app'
2307 expects:
2308 function foo* first_func():
2310 return type changed:
2311 in pointed to type 'struct foo':
2312 size changed from 32 to 64 bits
2313 1 data member insertion:
2314 'char foo::m1', at offset 32 (in bits)
2315 $
2317 abilint
2319 abilint parses the native XML representation of an ABI as emitted by
2320 abidw. Once it has parsed the XML representation of the ABI, abilint
2321 builds and in-memory model from it. It then tries to save it back to
2322 an XML form, to standard output. If that read-write operation succeeds
2323 chances are the input XML ABI representation is meaningful.
2324 Note that the main intent of this tool to help debugging issues in the
2326 underlying Libabigail library.
2327 Note also that abilint can also read an ELF input file, build the
2329 in-memory model for its ABI, and serialize that model back into XML to
2330 standard output. In that case, the ELF input file must be accompanied
2331 with its debug information in the DWARF format.
2332 Invocation
2334 abilint [options] [<abi-file1>]
2335 Options
2337 • --help
2338 Display a short help message and exits.
2340 • –version | -v
2342 Display the version of the program and exit.
2344 • --debug-info-dir <path>
2346 When reading an ELF input file which debug information is split
2348 out into a separate file, this options tells abilint where to find
2349 that separate debug information file.
2350 Note that path must point to the root directory under which the
2352 debug information is arranged in a tree-like manner. Under Red
2353 Hat based systems, that directory is usually <root>/usr/lib/debug.
2354 Note also that this option is not mandatory for split debug infor‐
2356 mation installed by your system’s package manager because then
2357 abidiff knows where to find it.
2358 • --diff
2360 For XML inputs, perform a text diff between the input and the mem‐
2362 ory model saved back to disk. This can help to spot issues in the
2363 handling of the XML format by the underlying Libabigail library.
2364 • --noout
2366 Do not display anything on standard output. The return code of
2368 the command is the only way to know if the command succeeded.
2369 • --suppressions | suppr <path-to-suppression-specifications-file>
2371 Use a suppression specification file located at path-to-suppres‐
2373 sion-specifications-file. Note that this option can appear multi‐
2374 ple times on the command line. In that case, all of the provided
2375 suppression specification files are taken into account. ABI arti‐
2376 facts matched by the suppression specifications are suppressed
2377 from the output of this tool.
2378 • --headers-dir | --hd <headers-directory-path-1>
2380 Specifies where to find the public headers of the first shared li‐
2382 brary that the tool has to consider. The tool will thus filter
2383 out types that are not defined in public headers.
2384 • --header-file | --hf <header-file-path>
2386 Specifies where to find one of the public headers of the abi file
2388 that the tool has to consider. The tool will thus filter out
2389 types that are not defined in public headers.
2390 • --stdin | --
2392 Read the input content from standard input.
2394 • --tu
2396 Expect the input XML to represent a single translation unit.
2398 • --ctf
2400 Extract ABI information from CTF debug information, if present in
2402 the given object.
2403 fedabipkgdiff
2405 fedabipkgdiff compares the ABI of shared libraries in Fedora packages.
2406 It’s a convenient way to do so without having to manually download
2407 packages from the Fedora Build System.
2408 fedabipkgdiff knows how to talk with the Fedora Build System to find
2410 the right packages versions, their associated debug information and de‐
2411 velopment packages, download them, compare their ABI locally, and re‐
2412 port about the possible ABI changes.
2413 Note that by default, this tool reports ABI changes about types that
2415 are defined in public header files found in the development packages
2416 associated with the packages being compared. It also reports ABI
2417 changes about functions and global variables whose symbols are defined
2418 and exported in the ELF binaries found in the packages being compared.
2419 Invocation
2421 fedabipkgdiff [option] <NVR> ...
2422 Environment
2424 fedabipkgdiff loads two default suppression specifications files,
2425 merges their content and use it to filter out ABI change reports that
2426 might be considered as false positives to users.
2427 • Default system-wide suppression specification file
2429 It’s located by the optional environment variable LIBABIGAIL_DE‐
2431 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
2432 set, then fedabipkgdiff tries to load the suppression file $lib‐
2433 dir/libabigail/libabigail-default.abignore. If that file is not
2434 present, then no default system-wide suppression specification file
2435 is loaded.
2436 • Default user suppression specification file.
2438 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
2440 PRESSION_FILE. If that environment variable is not set, then fed‐
2441 abipkgdiff tries to load the suppression file $HOME/.abignore. If
2442 that file is not present, then no default user suppression specifica‐
2443 tion is loaded.
2444 Options
2446 • --help | -h
2447 Display a short help about the command and exit.
2449 • --dry-run
2451 Don’t actually perform the ABI comparison. Details about what is
2453 going to be done are emitted on standard output.
2454 • --debug
2456 Emit debugging messages about the execution of the program. De‐
2458 tails about each method invocation, including input parameters and
2459 returned values, are emitted.
2460 • --traceback
2462 Show traceback when an exception raised. This is useful for devel‐
2464 opers of the tool itself to know more exceptional errors.
2465 • --server <URL>
2467 Specifies the URL of the Koji XMLRPC service the tool talks to.
2469 The default value of this option is
2470 http://koji.fedoraproject.org/kojihub.
2471 • --topurl <URL>
2473 Specifies the URL of the package store the tool downloads RPMs
2475 from. The default value of this option is
2476 https://kojipkgs.fedoraproject.org.
2477 • --from <distro>
2479 Specifies the name of the baseline Fedora distribution in which to
2481 find the first build that is used for comparison. The distro value
2482 can be any valid value of the RPM macro %{?dist} for Fedora, for
2483 example, fc4, fc23, fc25.
2484 • --to <distro>
2486 Specifies the name of the Fedora distribution in which to find the
2488 build that is compared against the baseline specified by option
2489 --from. The distro value could be any valid value of the RPM
2490 macro %{?dist} for Fedora, for example, fc4, fc23.
2491 • --all-subpackages
2493 Instructs the tool to also compare the ABI of the binaries in the
2495 sub-packages of the packages specified.
2496 • --dso-only
2498 Compares the ABI of shared libraries only. If this option is not
2500 provided, the tool compares the ABI of all ELF binaries found in
2501 the packages.
2502 • --suppressions <path-to-suppresions>
2504 Use a suppression specification file located at path-to-suppres‐
2506 sions.
2507 • --no-default-suppression
2509 Do not load the default suppression specification files.
2511 • --no-devel-pkg
2513 Do not take associated development packages into account when per‐
2515 forming the ABI comparison. This makes the tool report ABI
2516 changes about all types that are reachable from functions and
2517 global variables which symbols are defined and publicly exported
2518 in the binaries being compared, even if those types are not de‐
2519 fined in public header files available from the packages being
2520 compared.
2521 • --show-identical-binaries
2523 Show the names of the all binaries compared, including the bina‐
2524 ries whose ABI compare equal. By default, when this option is
2525 not provided, only binaries with ABI changes are mentionned in
2526 the output.
2527 • --abipkgdiff <path/to/abipkgdiff>
2529 Specify an alternative abipkgdiff instead of the one installed in
2531 system.
2532 • --clean-cache-before
2534 Clean cache before ABI comparison.
2536 • --clean-cache-after
2538 Clean cache after ABI comparison.
2540 • --clean-cache
2542 If you want to clean cache both before and after ABI comparison,
2544 --clean-cache is the convenient way for you to save typing of two
2545 options at same time.
2546 Note that a build is a specific version and release of an RPM package.
2548 It’s specified by its the package name, version and release. These are
2549 specified by the Fedora Naming Guidelines
2550 Return value
2552 The exit code of the abipkgdiff command is either 0 if the ABI of the
2553 binaries compared are equivalent, or non-zero if they differ or if the
2554 tool encountered an error.
2555 In the later case, the value of the exit code is the same as for the
2557 abidiff tool.
2558 Use cases
2560 Below are some usage examples currently supported by fedabipkgdiff.
2561 1. Compare the ABI of binaries in a local package against the ABI of
2563 the latest stable package in Fedora 23.
2564 Suppose you have built just built the httpd package and you want
2566 to compare the ABI of the binaries in this locally built package
2567 against the ABI of the binaries in the latest http build from
2568 Fedora 23. The command line invocation would be:
2569 $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
2571 2. Compare the ABI of binaries in two local packages.
2573 Suppose you have built two versions of package httpd, and you
2575 want to see what ABI differences between these two versions of
2576 RPM files. The command line invocation would be:
2577 $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
2579 All what fedabipkgdiff does happens on local machine without the
2581 need of querying or downloading RPMs from Koji.
2582 3. Compare the ABI of binaries in the latest build of the httpd
2584 package in Fedora 23 against the ABI of the binaries in the lat‐
2585 est build of the same package in 24.
2586 In this case, note that neither of the two packages are available
2588 locally. The tool is going to talk with the Fedora Build System,
2589 determine what the versions and releases of the latest packages
2590 are, download them and perform the comparison locally. The com‐
2591 mand line invocation would be:
2592 $ fedabipkgdiff --from fc23 --to fc24 httpd
2594 4. Compare the ABI of binaries of two builds of the httpd package,
2596 designated their versions and releases.
2597 If we want to do perform the ABI comparison for all the processor
2599 architectures supported by Fedora the command line invocation
2600 would be:
2601 $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
2603 But if we want to perform the ABI comparison for a specific ar‐
2605 chitecture, say, x86_64, then the command line invocation would
2606 be:
2607 $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
2609 5. If the use wants to also compare the sub-packages of a given
2611 package, she can use the –all-subpackages option. The first com‐
2612 mand of the previous example would thus look like:
2613 $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
2615
2617 ABI artifacts
2618 An ABI artifact is a relevant part of the ABI of a shared library or
2619 program. Examples of ABI artifacts are exported types, variables,
2620 functions, or ELF symbols exported by a shared library.
2621 The set of ABI artifact for a binary is called an ABI Corpus.
2623 Harmful changes
2625 A change in the diff report is considered harmful if it might cause ABI
2626 compatibility issues. That is, it might prevent an application dynami‐
2627 cally linked against a given version of a library to keep working with
2628 the changed subsequent versions of the same library.
2629 Harmless changes
2631 A change in the diff report is considered harmless if it will not cause
2632 any ABI compatibility issue. That is, it will not prevent an applica‐
2633 tion dynamically linked against given version of a library to keep
2634 working with the changed subsequent versions of the same library.
2635 By default, abidiff filters harmless changes from the diff report.
2637 Suppression specifications
2639 Definition
2640 A suppression specification file is a way for a user to instruct
2641 abidiff, abipkgdiff or any other relevant libabigail tool to avoid
2642 emitting reports for changes involving certain ABI artifacts.
2643 It contains directives (or specifications) that describe the set of ABI
2645 artifacts to avoid emitting change reports about.
2646 Introductory examples
2648 Its syntax is based on a simplified and customized form of Ini File
2649 Syntax. For instance, to specify that change reports on a type named
2650 FooPrivateType should be suppressed, one could write this suppression
2651 specification:
2652 [suppress_type]
2654 name = FooPrivateType
2655 If we want to ensure that only change reports about structures named
2657 FooPrivateType should be suppressed, we could write:
2658 [suppress_type]
2660 type_kind = struct
2661 name = FooPrivateType
2662 But we could also want to suppress change reports avoid typedefs named
2664 FooPrivateType. In that case we would write:
2665 [suppress_type]
2667 type_kind = typedef
2668 name = FooPrivateType
2669 Or, we could want to suppress change reports about all struct which
2671 names end with the string “PrivateType”:
2672 [suppress_type]
2674 type_kind = struct
2675 name_regexp = ^.*PrivateType
2676 Let’s now look at the generic syntax of suppression specification
2678 files.
2679 Syntax
2681 Properties
2682 More generally, the format of suppression lists is organized around the
2683 concept of property. Every property has a name and a value, delimited
2684 by the = sign. E.g:
2685 name = value
2687 Leading and trailing white spaces are ignored around property names and
2689 values.
2690 Regular expressions
2692 The value of some properties might be a regular expression. In that
2693 case, they must comply with the syntax of extended POSIX regular ex‐
2694 pressions. Note that Libabigail uses the regular expression engine of
2695 the GNU C Library.
2696 Escaping a character in a regular expression
2698 When trying to match a string that contains a * character, like in the
2699 pointer type int*, one must be careful to notice that the character *
2700 is a special character in the extended POSIX regular expression syntax.
2701 And that character must be escaped for the regular expression engine.
2702 Thus the regular expression that would match the string int* in a sup‐
2703 pression file should be
2704 int\\*
2706 Wait; but then why the two \ characters? Well, because the \ character
2708 is a special character in the Ini File Syntax used for specifying sup‐
2709 pressions. So it must be escaped as well, so that the Ini File parser
2710 leaves a \ character intact in the data stream that is handed to the
2711 regular expression engine. Hence the \\ targeted at the Ini File
2712 parser.
2713 So, in short, to escape a character in a regular expression, always
2715 prefix the character with the \\ sequence.
2716 Modus operandi
2718 Suppression specifications can be applied at two different points of
2719 the processing pipeline of libabigail.
2720 In the default operating mode called “late suppression mode”, suppres‐
2722 sion specifications are applied to the result of comparing the in-mem‐
2723 ory internal representations of two ABIs. In this mode, if an ABI ar‐
2724 tifact matches a suppression specification, its changes are not men‐
2725 tioned in the ABI change report. The internal representation of the
2726 “suppressed” changed ABI artifact is still present in memory; it is
2727 just not mentioned in the ABI change report. The change report can
2728 still mention statistics about the number of changed ABI artifacts that
2729 were suppressed.
2730 There is another operating mode called the “early suppression mode”
2732 where suppression specifications are applied during the construction of
2733 the in-memory internal representation of a given ABI. In that mode, if
2734 an ABI artifact matches a suppression specification, no in-memory in‐
2735 ternal representation is built for it. As a result, no change about
2736 the matched ABI artifact is going to be mentioned in the ABI change re‐
2737 port and no statistic about the number of suppressed ABI changes is
2738 available. Also, please note that because suppressed ABI artifacts are
2739 removed from the in-memory internal representation in this mode, the
2740 amount memory used by the internal representation is potentially
2741 smaller than the memory consumption in the late suppression mode.
2742 Sections
2744 Properties are then grouped into arbitrarily named sections that shall
2745 not be nested. The name of the section is on a line by itself and is
2746 surrounded by square brackets, i.e:
2747 [section_name]
2749 property1_name = property1_value
2750 property2_name = property2_value
2751 A section might or might not have properties. Sections that expect to
2753 have properties and which are found nonetheless empty are just ignored.
2754 Properties that are not recognized by the reader are ignored as well.
2755 Section names
2757 Each different section can be thought of as being a directive to sup‐
2758 press ABI change reports for a particular kind of ABI artifact.
2759 [suppress_file]
2761 This directive prevents a given tool from loading a file (binary or
2762 abixml file) if its file name or other properties match certain proper‐
2763 ties. Thus, if the tool is meant to compare the ABIs of two files, and
2764 if the directive prevents it from loading either one of the files, then
2765 no comparison is performed.
2766 Note that for the [suppress_file] directive to work, at least one of
2768 the following properties must be provided:
2769 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2770 ame_not_regexp.
2771 If none of the above properties are provided, then the [suppress_file]
2773 directive is simply ignored.
2774 The potential properties of this sections are listed below:
2776 • file_name_regexp
2778 Usage:
2780 file_name_regexp = <regular-expression>
2781 Prevents the system from loading the file which name matches the reg‐
2783 ular expression specified as value of this property.
2784 • file_name_not_regexp
2786 Usage:
2788 file_name_not_regexp = <regular-expression>
2789 Prevents the system from loading the file which name does not match
2791 the regular expression specified as value of this property.
2792 • soname_regexp
2794 Usage:
2796 soname_regexp = <regular-expression>
2797 Prevents the system from loading the file which contains a SONAME
2799 property that matches the regular expression of this property. Note
2800 that this property also works on an abixml file if it contains a SON‐
2801 AME property.
2802 • soname_not_regexp
2804 Usage:
2806 soname_not_regexp = <regular-expression>
2807 Prevents the system from loading the file which contains a SONAME
2809 property that does NOT match the regular expression of this property.
2810 Note that this property also works on an abixml file if it contains a
2811 SONAME property.
2812 • label
2814 Usage:
2815 label = <some-value>
2816 Define a label for the section. A label is just an informative
2818 string that might be used by the tool to refer to a type suppression
2819 in error messages.
2820 [suppress_type]
2822 This directive suppresses report messages about a type change.
2823 Note that for the [suppress_type] directive to work, at least one of
2825 the following properties must be provided:
2826 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2827 ame_not_regexp, name, name_regexp, name_not_regexp, type_kind,
2828 source_location_not_in, source_location_not_regexp.
2829 If none of the above properties are provided, then the [suppress_type]
2831 directive is simply ignored.
2832 The potential properties of this sections are listed below:
2834 • file_name_regexp
2836 Usage:
2838 file_name_regexp = <regular-expression>
2839 Suppresses change reports about ABI artifacts that are defined in a
2841 binary file which name matches the regular expression specified as
2842 value of this property.
2843 • file_name_not_regexp
2845 Usage:
2847 file_name_not_regexp = <regular-expression>
2848 Suppresses change reports about ABI artifacts that are defined in a
2850 binary file which name does not match the regular expression speci‐
2851 fied as value of this property.
2852 • soname_regexp
2854 Usage:
2856 soname_regexp = <regular-expression>
2857 Suppresses change reports about ABI artifacts that are defined in a
2859 shared library which SONAME property matches the regular expression
2860 specified as value of this property.
2861 • soname_not_regexp
2863 Usage:
2865 soname_not_regexp = <regular-expression>
2866 Suppresses change reports about ABI artifacts that are defined in a
2868 shared library which SONAME property does not match the regular ex‐
2869 pression specified as value of this property.
2870 • name_regexp
2872 Usage:
2873 name_regexp = <regular-expression>
2874 Suppresses change reports involving types whose name matches the
2876 regular expression specified as value of this property.
2877 • name_not_regexp
2879 Usage:
2880 name_not_regexp = <regular-expression>
2881 Suppresses change reports involving types whose name does NOT match
2883 the regular expression specified as value of this property. Said
2884 otherwise, this property specifies which types to keep, rather than
2885 types to suppress from reports.
2886 • name
2888 Usage:
2889 name = <a-value>
2890 Suppresses change reports involving types whose name equals the
2892 value of this property.
2893 • type_kind
2895 Usage:
2896 type_kind = class | struct | union | enum |
2898 array | typedef | builtin
2899 Suppresses change reports involving a certain kind of type. The
2901 kind of type to suppress change reports for is specified by the pos‐
2902 sible values listed above:
2903 •
2905 class: suppress change reports for class types. Note that
2907 even if class types don’t exist for C, this value still
2908 triggers the suppression of change reports for struct
2909 types, in C. In C++ however, it should do what it sug‐
2910 gests.
2911 •
2913 struct: suppress change reports for struct types in C or C++.
2915 Note that the value class above is a super-set of this
2916 one.
2917 • union: suppress change reports for union types.
2919 • enum: suppress change reports for enum types.
2921 • array: suppress change reports for array types.
2923 • typedef: suppress change reports for typedef types.
2925 • builtin: suppress change reports for built-in (or native)
2927 types. Example of built-in types are char, int, unsigned int,
2928 etc.
2929 • source_location_not_in
2931 Usage:
2932 source_location_not_in = <list-of-file-paths>
2933 Suppresses change reports involving a type which is defined in a
2935 file which path is NOT listed in the value list-of-file-paths. Note
2936 that the value is a comma-separated list of file paths e.g, this
2937 property
2938 source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h
2940 suppresses change reports about all the types that are NOT defined
2942 in header files whose path end up with the strings libabi‐
2943 gail/abg-ir.h or libabigail/abg-dwarf-reader.h.
2944 • source_location_not_regexp
2946 Usage:
2947 source_location_not_regexp = <regular-expression>
2948 Suppresses change reports involving a type which is defined in a
2950 file which path does NOT match the regular expression provided as
2951 value of the property. E.g, this property
2952 source_location_not_regexp = libabigail/abg-.*\\.h
2954 suppresses change reports involving all the types that are NOT de‐
2956 fined in header files whose path match the regular expression pro‐
2957 vided a value of the property.
2958 • has_data_member_inserted_at
2960 Usage:
2961 has_data_member_inserted_at = <offset-in-bit>
2962 Suppresses change reports involving a type which has at least one
2964 data member inserted at an offset specified by the property value
2965 offset-in-bit. Please note that if a type has a change in which at
2966 least one of its data members is removed or its size is reduced, the
2967 type will NOT be suppressed by the evaluation of this property.
2968 The value offset-in-bit is either:
2970 • an integer value, expressed in bits, which denotes the off‐
2972 set of the insertion point of the data member, starting
2973 from the beginning of the relevant structure or class.
2974 • the keyword end which is a named constant which value
2976 equals the offset of the end of the of the structure or
2977 class.
2978 • the function call expression offset_of(data-member-name)
2980 where data-member-name is the name of a given data member
2981 of the relevant structure or class. The value of this
2982 function call expression is an integer that represents the
2983 offset of the data member denoted by data-member-name.
2984 • the function call expression offset_after(data-member-name)
2986 where data-member-name is the name of a given data member
2987 of the relevant structure or class. The value of this
2988 function call expression is an integer that represents the
2989 offset of the point that comes right after the region occu‐
2990 pied by the data member denoted by data-member-name.
2991 • has_data_member_inserted_between
2993 Usage:
2994 has_data_member_inserted_between = {<range-begin>, <range-end>}
2995 Suppresses change reports involving a type which has at least one
2997 data member inserted at an offset that is comprised in the range be‐
2998 tween range-begin and range-end. Please note that each of the val‐
2999 ues range-begin and range-end can be of the same form as the
3000 has_data_member_inserted_at property above. Please also note that
3001 if a type has a change in which at least one of its data members is
3002 removed or its size is reduced, the type will NOT be suppressed by
3003 the evaluation of this property.
3004 Usage examples of this properties are:
3006 has_data_member_inserted_between = {8, 64}
3008 or:
3010 has_data_member_inserted_between = {16, end}
3012 or:
3014 has_data_member_inserted_between = {offset_after(member1), end}
3016 • has_data_members_inserted_between
3018 Usage:
3019 has_data_members_inserted_between = {<sequence-of-ranges>}
3020 Suppresses change reports involving a type which has multiple data
3022 member inserted in various offset ranges. A usage example of this
3023 property is, for instance:
3024 has_data_members_inserted_between = {{8, 31}, {72, 95}}
3026 This usage example suppresses change reports involving a type which
3028 has data members inserted in bit offset ranges [8 31] and [72 95].
3029 The length of the sequence of ranges or this has_data_members_in‐
3030 serted_between is not bounded; it can be as long as the system can
3031 cope with. The values of the boundaries of the ranges are of the
3032 same kind as for the has_data_member_inserted_at property above.
3033 Please note that if a type has a change in which at least one of its
3034 data members is removed or its size is reduced, the type will NOT be
3035 suppressed by the evaluation of this property.
3036 Another usage example of this property is thus:
3038 has_data_members_inserted_between =
3040 {
3041 {offset_after(member0), offset_of(member1)},
3042 {72, end}
3043 }
3044 • accessed_through
3046 Usage:
3047 accessed_through = <some-predefined-values>
3048 Suppress change reports involving a type which is referred to either
3050 directly or through a pointer or a reference. The potential values
3051 of this property are the predefined keywords below:
3052 • direct
3054 So if the [suppress_type] contains the property description:
3056 accessed_through = direct
3058 then changes about a type that is referred-to directly (i.e,
3060 not through a pointer or a reference) are going to be sup‐
3061 pressed.
3062 • pointer
3064 If the accessed_through property is set to the value pointer
3066 then changes about a type that is referred-to through a
3067 pointer are going to be suppressed.
3068 • reference
3070 If the accessed_through property is set to the value reference
3072 then changes about a type that is referred-to through a refer‐
3073 ence are going to be suppressed.
3074 • reference-or-pointer
3076 If the accessed_through property is set to the value refer‐
3078 ence-or-pointer then changes about a type that is referred-to
3079 through either a reference or a pointer are going to be sup‐
3080 pressed.
3081 For an extensive example of how to use this property, please check
3083 out the example below about suppressing change reports about types
3084 accessed either directly or through pointers.
3085 • drop
3087 Usage:
3088 drop = yes | no
3089 If a type is matched by a suppression specification which contains
3091 the “drop” property set to “yes” (or to “true”) then the type is not
3092 even going to be represented in the internal representation of the
3093 ABI being analyzed. This property makes its enclosing suppression
3094 specification to be applied in the early suppression specification
3095 mode. The net effect is that it potentially reduces the memory used
3096 to represent the ABI being analyzed.
3097 Please note that for this property to be effective, the enclosing
3099 suppression specification must have at least one of the following
3100 properties specified: name_regexp, name, name_regexp, source_loca‐
3101 tion_not_in or source_location_not_regexp.
3102 • label
3104 Usage:
3105 label = <some-value>
3106 Define a label for the section. A label is just an informative
3108 string that might be used by a tool to refer to a type suppression
3109 in error messages.
3110 • changed_enumerators
3112 Usage:
3114 changed_enumerators = <list-of-enumerators>
3115 Suppresses change reports involving changes in the value of enumera‐
3117 tors of a given enum type. This property is applied if the type_kind
3118 property is set to the value enum, at least. The value of the
3119 changed_enumerators is a comma-separated list of the enumerators that
3120 the user expects to change. For instance:
3121 changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1
3123 [suppress_function]
3125 This directive suppresses report messages about changes on a set of
3126 functions.
3127 Note that for the [suppress_function] directive to work, at least one
3129 of the following properties must be provided:
3130 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
3131 ame_not_regexp, name, name_regexp, name_not_regexp, parameter, re‐
3132 turn_type_name, return_type_regexp, symbol_name, symbol_name_regexp,
3133 symbol_name_not_regexp, symbol_version, symbol_version_regexp.
3134 If none of the above properties are provided, then the [suppress_func‐
3136 tion] directive is simply ignored.
3137 The potential properties of this sections are:
3139 • label
3141 Usage:
3142 label = <some-value>
3143 This property is the same as the label property defined above.
3145 • file_name_regexp
3147 Usage:
3149 file_name_regexp = <regular-expression>
3151 Suppresses change reports about ABI artifacts that are defined in a
3153 binary file which name matches the regular expression specified as
3154 value of this property.
3155 • file_name_not_regexp
3157 Usage:
3159 file_name_not_regexp = <regular-expression>
3160 Suppresses change reports about ABI artifacts that are defined in a
3162 binary file which name does not match the regular expression speci‐
3163 fied as value of this property.
3164 • soname_regexp
3166 Usage:
3168 soname_regexp = <regular-expression>
3169 Suppresses change reports about ABI artifacts that are defined in a
3171 shared library which SONAME property matches the regular expression
3172 specified as value of this property.
3173 • soname_not_regexp
3175 Usage:
3177 soname_not_regexp = <regular-expression>
3178 Suppresses change reports about ABI artifacts that are defined in a
3180 shared library which SONAME property does not match the regular ex‐
3181 pression specified as value of this property.
3182 • name
3184 Usage:
3185 name = <some-value>
3186 Suppresses change reports involving functions whose name equals the
3188 value of this property.
3189 • name_regexp
3191 Usage:
3192 name_regexp = <regular-expression>
3193 Suppresses change reports involving functions whose name matches the
3195 regular expression specified as value of this property.
3196 Let’s consider the case of functions that have several symbol names.
3198 This happens when the underlying symbol for the function has
3199 aliases. Each symbol name is actually one alias name.
3200 In this case, if the regular expression matches the name of at least
3202 one of the aliases names, then it must match the names of all of the
3203 aliases of the function for the directive to actually suppress the
3204 diff reports for said function.
3205 • name_not_regexp
3207 Usage:
3208 name_not_regexp = <regular-expression>
3209 Suppresses change reports involving functions whose names don’t
3211 match the regular expression specified as value of this property.
3212 The rules for functions that have several symbol names are the same
3214 rules as for the name_regexp property above.
3215 • change_kind
3217 Usage:
3218 change_kind = <predefined-possible-values>
3219 Specifies the kind of changes this suppression specification should
3221 apply to. The possible values of this property as well as their
3222 meaning are listed below:
3223 • function-subtype-change
3225 This suppression specification applies to functions that which
3227 have at least one sub-type that has changed.
3228 • added-function
3230 This suppression specification applies to functions that have
3232 been added to the binary.
3233 • deleted-function
3235 This suppression specification applies to functions that have
3237 been removed from the binary.
3238 • all
3240 This suppression specification applies to functions that have
3242 all of the changes above. Note that not providing the
3243 change_kind property at all is equivalent to setting it to the
3244 value all.
3245 • parameter
3247 Usage:
3248 parameter = <function-parameter-specification>
3249 Suppresses change reports involving functions whose parameters match
3251 the parameter specification indicated as value of this property.
3252 The format of the function parameter specification is:
3254 ' <parameter-index> <space> <type-name-or-regular-expression>
3256 That is, an apostrophe followed by a number that is the index of the
3258 parameter, followed by one of several spaces, followed by either the
3259 name of the type of the parameter, or a regular expression describ‐
3260 ing a family of parameter type names.
3261 If the parameter type name is designated by a regular expression,
3263 then said regular expression must be enclosed between two slashes;
3264 like /some-regular-expression/.
3265 The index of the first parameter of the function is zero. Note that
3267 for member functions (methods of classes), the this is the first pa‐
3268 rameter that comes after the implicit “this” pointer parameter.
3269 Examples of function parameter specifications are:
3271 '0 int
3273 Which means, the parameter at index 0, whose type name is int.
3275 '4 unsigned char*
3277 Which means, the parameter at index 4, whose type name is unsigned
3279 char*.
3280 '2 /^foo.*&/
3282 Which means, the parameter at index 2, whose type name starts with
3284 the string “foo” and ends with an ‘&’. In other words, this is the
3285 third parameter and it’s a reference on a type that starts with the
3286 string “foo”.
3287 • return_type_name
3289 Usage:
3290 return_type_name = <some-value>
3291 Suppresses change reports involving functions whose return type name
3293 equals the value of this property.
3294 • return_type_regexp
3296 Usage:
3297 return_type_regexp = <regular-expression>
3298 Suppresses change reports involving functions whose return type name
3300 matches the regular expression specified as value of this property.
3301 • symbol_name
3303 Usage:
3304 symbol_name = <some-value>
3305 Suppresses change reports involving functions whose symbol name
3307 equals the value of this property.
3308 • symbol_name_regexp
3310 Usage:
3311 symbol_name_regexp = <regular-expression>
3312 Suppresses change reports involving functions whose symbol name
3314 matches the regular expression specified as value of this property.
3315 Let’s consider the case of functions that have several symbol names.
3317 This happens when the underlying symbol for the function has
3318 aliases. Each symbol name is actually one alias name.
3319 In this case, the regular expression must match the names of all of
3321 the aliases of the function for the directive to actually suppress
3322 the diff reports for said function.
3323 • symbol_name_not_regexp
3325 Usage:
3326 symbol_name_not_regexp = <regular-expression>
3327 Suppresses change reports involving functions whose symbol name does
3329 not match the regular expression specified as value of this prop‐
3330 erty.
3331 • symbol_version
3333 Usage:
3334 symbol_version = <some-value>
3335 Suppresses change reports involving functions whose symbol version
3337 equals the value of this property.
3338 • symbol_version_regexp
3340 Usage:
3341 symbol_version_regexp = <regular-expression>
3342 Suppresses change reports involving functions whose symbol version
3344 matches the regular expression specified as value of this property.
3345 • drop
3347 Usage:
3348 drop = yes | no
3349 If a function is matched by a suppression specification which con‐
3351 tains the “drop” property set to “yes” (or to “true”) then the func‐
3352 tion is not even going to be represented in the internal representa‐
3353 tion of the ABI being analyzed. This property makes its enclosing
3354 suppression specification to be applied in the early suppression
3355 specification mode. The net effect is that it potentially reduces
3356 the memory used to represent the ABI being analyzed.
3357 Please note that for this property to be effective, the enclosing
3359 suppression specification must have at least one of the following
3360 properties specified: name_regexp, name, name_regexp, source_loca‐
3361 tion_not_in or source_location_not_regexp.
3362 [suppress_variable]
3364 This directive suppresses report messages about changes on a set of
3365 variables.
3366 Note that for the [suppress_variable] directive to work, at least one
3368 of the following properties must be provided:
3369 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
3370 ame_not_regexp, name, name_regexp, name_not_regexp, symbol_name,
3371 symbol_name_regexp, symbol_name_not_regexp, symbol_version, sym‐
3372 bol_version_regexp, type_name, type_name_regexp.
3373 If none of the above properties are provided, then the [suppress_vari‐
3375 able] directive is simply ignored.
3376 The potential properties of this sections are:
3378 • label
3380 Usage:
3381 label = <some-value>
3382 This property is the same as the label property defined above.
3384 • file_name_regexp
3386 Usage:
3388 file_name_regexp = <regular-expression>
3390 Suppresses change reports about ABI artifacts that are defined in a
3392 binary file which name matches the regular expression specified as
3393 value of this property.
3394 • file_name_not_regexp
3396 Usage:
3398 file_name_not_regexp = <regular-expression>
3399 Suppresses change reports about ABI artifacts that are defined in a
3401 binary file which name does not match the regular expression speci‐
3402 fied as value of this property.
3403 • soname_regexp
3405 Usage:
3407 soname_regexp = <regular-expression>
3408 Suppresses change reports about ABI artifacts that are defined in a
3410 shared library which SONAME property matches the regular expression
3411 specified as value of this property.
3412 • soname_not_regexp
3414 Usage:
3416 soname_not_regexp = <regular-expression>
3417 Suppresses change reports about ABI artifacts that are defined in a
3419 shared library which SONAME property does not match the regular ex‐
3420 pression specified as value of this property.
3421 • name
3423 Usage:
3424 name = <some-value>
3425 Suppresses change reports involving variables whose name equals the
3427 value of this property.
3428 • name_regexp
3430 Usage:
3431 name_regexp = <regular-expression>
3432 Suppresses change reports involving variables whose name matches the
3434 regular expression specified as value of this property.
3435 • change_kind
3437 Usage:
3438 change_kind = <predefined-possible-values>
3439 Specifies the kind of changes this suppression specification should
3441 apply to. The possible values of this property as well as their
3442 meaning are the same as when it’s used in the [suppress_function]
3443 section.
3444 • symbol_name
3446 Usage:
3447 symbol_name = <some-value>
3448 Suppresses change reports involving variables whose symbol name
3450 equals the value of this property.
3451 • symbol_name_regexp
3453 Usage:
3454 symbol_name_regexp = <regular-expression>
3455 Suppresses change reports involving variables whose symbol name
3457 matches the regular expression specified as value of this property.
3458 • symbol_name_not_regexp
3460 Usage:
3461 symbol_name_not_regexp = <regular-expression>
3462 Suppresses change reports involving variables whose symbol name does
3464 not match the regular expression specified as value of this prop‐
3465 erty.
3466 • symbol_version
3468 Usage:
3469 symbol_version = <some-value>
3470 Suppresses change reports involving variables whose symbol version
3472 equals the value of this property.
3473 • symbol_version_regexp
3475 Usage:
3476 symbol_version_regexp = <regular-expression>
3477 Suppresses change reports involving variables whose symbol version
3479 matches the regular expression specified as value of this property.
3480 • type_name
3482 Usage:
3483 type_name = <some-value>
3484 Suppresses change reports involving variables whose type name equals
3486 the value of this property.
3487 • type_name_regexp
3489 Usage:
3490 type_name_regexp = <regular-expression>
3491 Suppresses change reports involving variables whose type name
3493 matches the regular expression specified as value of this property.
3494 Comments
3496 ; or # ASCII character at the beginning of a line indicates a comment.
3497 Comment lines are ignored.
3498 Code examples
3500 1. Suppressing change reports about types.
3501 Suppose we have a library named libtest1-v0.so which contains this
3503 very useful code:
3504 $ cat -n test1-v0.cc
3506 1 // A forward declaration for a type considered to be opaque to
3507 2 // function foo() below.
3508 3 struct opaque_type;
3509 4
3510 5 // This function cannot touch any member of opaque_type. Hence,
3511 6 // changes to members of opaque_type should not impact foo, as far as
3512 7 // ABI is concerned.
3513 8 void
3514 9 foo(opaque_type*)
3515 10 {
3516 11 }
3517 12
3518 13 struct opaque_type
3519 14 {
3520 15 int member0;
3521 16 char member1;
3522 17 };
3523 $
3524 Let’s change the layout of struct opaque_type by inserting a data mem‐
3526 ber around line 15, leading to a new version of the library, that we
3527 shall name libtest1-v1.so:
3528 $ cat -n test1-v1.cc
3530 1 // A forward declaration for a type considered to be opaque to
3531 2 // function foo() below.
3532 3 struct opaque_type;
3533 4
3534 5 // This function cannot touch any member of opaque_type; Hence,
3535 6 // changes to members of opaque_type should not impact foo, as far as
3536 7 // ABI is concerned.
3537 8 void
3538 9 foo(opaque_type*)
3539 10 {
3540 11 }
3541 12
3542 13 struct opaque_type
3543 14 {
3544 15 char added_member; // <-- a new member got added here now.
3545 16 int member0;
3546 17 char member1;
3547 18 };
3548 $
3549 Let’s compile both examples. We shall not forget to compile them with
3551 debug information generation turned on:
3552 $ g++ -shared -g -Wall -o libtest1-v0.so test1-v0.cc
3554 $ g++ -shared -g -Wall -o libtest1-v1.so test1-v1.cc
3555 Let’s ask abidiff which ABI differences it sees between libtest1-v0.so
3557 and libtest1-v1.so:
3558 $ abidiff libtest1-v0.so libtest1-v1.so
3560 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3561 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3562 1 function with some indirect sub-type change:
3564 [C]'function void foo(opaque_type*)' has some indirect sub-type changes:
3566 parameter 0 of type 'opaque_type*' has sub-type changes:
3567 in pointed to type 'struct opaque_type':
3568 size changed from 64 to 96 bits
3569 1 data member insertion:
3570 'char opaque_type::added_member', at offset 0 (in bits)
3571 2 data member changes:
3572 'int opaque_type::member0' offset changed from 0 to 32
3573 'char opaque_type::member1' offset changed from 32 to 64
3574 So abidiff reports that the opaque_type’s layout has changed in a sig‐
3576 nificant way, as far as ABI implications are concerned, in theory. Af‐
3577 ter all, a sub-type (struct opaque_type) of an exported function
3578 (foo()) has seen its layout change. This might have non negligible ABI
3579 implications. But in practice here, the programmer of the
3580 litest1-v1.so library knows that the “soft” contract between the func‐
3581 tion foo() and the type struct opaque_type is to stay away from the
3582 data members of the type. So layout changes of struct opaque_type
3583 should not impact foo().
3584 Now to teach abidiff about this soft contract and have it avoid emit‐
3586 ting what amounts to false positives in this case, we write the sup‐
3587 pression specification file below:
3588 $ cat test1.suppr
3590 [suppress_type]
3591 type_kind = struct
3592 name = opaque_type
3593 Translated in plain English, this suppression specification would read:
3595 “Do not emit change reports about a struct which name is opaque_type”.
3596 Let’s now invoke abidiff on the two versions of the library again, but
3598 this time with the suppression specification:
3599 $ abidiff --suppressions test1.suppr libtest1-v0.so libtest1-v1.so
3601 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3602 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3603 As you can see, abidiff does not report the change anymore; it tells us
3605 that it was filtered out instead.
3606 Suppressing change reports about types with data member insertions
3608 Suppose the first version of a library named libtest3-v0.so has this
3610 source code:
3611 /* Compile this with:
3613 gcc -g -Wall -shared -o libtest3-v0.so test3-v0.c
3614 */
3615 struct S
3617 {
3618 char member0;
3619 int member1; /*
3620 between member1 and member2, there is some padding,
3621 at least on some popular platforms. On
3622 these platforms, adding a small enough data
3623 member into that padding shouldn't change
3624 the offset of member1. Right?
3625 */
3626 };
3627 int
3629 foo(struct S* s)
3630 {
3631 return s->member0 + s->member1;
3632 }
3633 Now, suppose the second version of the library named libtest3-v1.so has
3635 this source code in which a data member has been added in the padding
3636 space of struct S and another data member has been added at its end:
3637 /* Compile this with:
3639 gcc -g -Wall -shared -o libtest3-v1.so test3-v1.c
3640 */
3641 struct S
3643 {
3644 char member0;
3645 char inserted1; /* <---- A data member has been added here... */
3646 int member1;
3647 char inserted2; /* <---- ... and another one has been added here. */
3648 };
3649 int
3651 foo(struct S* s)
3652 {
3653 return s->member0 + s->member1;
3654 }
3655 In libtest3-v1.so, adding char data members S::inserted1 and S::in‐
3657 serted2 can be considered harmless (from an ABI compatibility perspec‐
3658 tive), at least on the x86 platform, because that doesn’t change the
3659 offsets of the data members S::member0 and S::member1. But then run‐
3660 ning abidiff on these two versions of library yields:
3661 $ abidiff libtest3-v0.so libtest3-v1.so
3663 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3664 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3665 1 function with some indirect sub-type change:
3667 [C]'function int foo(S*)' has some indirect sub-type changes:
3669 parameter 0 of type 'S*' has sub-type changes:
3670 in pointed to type 'struct S':
3671 type size changed from 64 to 96 bits
3672 2 data member insertions:
3673 'char S::inserted1', at offset 8 (in bits)
3674 'char S::inserted2', at offset 64 (in bits)
3675 $
3676 That is, abidiff shows us the two changes, even though we (the develop‐
3678 ers of that very involved library) know that these changes are harmless
3679 in this particular context.
3680 Luckily, we can devise a suppression specification that essentially
3682 tells abidiff to filter out change reports about adding a data member
3683 between S::member0 and S::member1, and adding a data member at the end
3684 of struct S. We have written such a suppression specification in a
3685 file called test3-1.suppr and it unsurprisingly looks like:
3686 [suppress_type]
3688 name = S
3689 has_data_member_inserted_between = {offset_after(member0), offset_of(member1)}
3690 has_data_member_inserted_at = end
3691 Now running abidiff with this suppression specification yields:
3693 $ ../build/tools/abidiff --suppressions test3-1.suppr libtest3-v0.so libtest3-v1.so
3695 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3696 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3697 $
3699 Hooora! \o/ (I guess)
3701 Suppressing change reports about types accessed either directly or
3703 through pointers
3704 Suppose we have a first version of an object file which source code is
3706 the file widget-v0.cc below:
3707 // Compile with: g++ -g -c widget-v0.cc
3709 struct widget
3711 {
3712 int x;
3713 int y;
3714 widget()
3716 :x(), y()
3717 {}
3718 };
3719 void
3721 fun0(widget*)
3722 {
3723 // .. do stuff here.
3724 }
3725 void
3727 fun1(widget&)
3728 {
3729 // .. do stuff here ..
3730 }
3731 void
3733 fun2(widget w)
3734 {
3735 // ... do other stuff here ...
3736 }
3737 Now suppose in the second version of that file, named widget-v1.cc, we
3739 have added some data members at the end of the type struct widget; here
3740 is what the content of that file would look like:
3741 // Compile with: g++ -g -c widget-v1.cc
3743 struct widget
3745 {
3746 int x;
3747 int y;
3748 int w; // We have added these two new data members here ..
3749 int h; // ... and here.
3750 widget()
3752 : x(), y(), w(), h()
3753 {}
3754 };
3755 void
3757 fun0(widget*)
3758 {
3759 // .. do stuff here.
3760 }
3761 void
3763 fun1(widget&)
3764 {
3765 // .. do stuff here ..
3766 }
3767 void
3769 fun2(widget w)
3770 {
3771 // ... do other stuff here ...
3772 }
3773 When we invoke abidiff on the object files resulting from the compila‐
3775 tion of the two file above, here is what we get:
3776 $ abidiff widget-v0.o widget-v1.o
3778 Functions changes summary: 0 Removed, 2 Changed (1 filtered out), 0 Added functions
3779 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3780 2 functions with some indirect sub-type change:
3782 [C]'function void fun0(widget*)' has some indirect sub-type changes:
3784 parameter 1 of type 'widget*' has sub-type changes:
3785 in pointed to type 'struct widget':
3786 type size changed from 64 to 128 bits
3787 2 data member insertions:
3788 'int widget::w', at offset 64 (in bits)
3789 'int widget::h', at offset 96 (in bits)
3790 [C]'function void fun2(widget)' has some indirect sub-type changes:
3792 parameter 1 of type 'struct widget' has sub-type changes:
3793 details were reported earlier
3794 $
3795 I guess a little bit of explaining is due here. abidiff detects that
3797 two data member got added at the end of struct widget. it also tells
3798 us that the type change impacts the exported function fun0() which uses
3799 the type struct widget through a pointer, in its signature.
3800 Careful readers will notice that the change to struct widget also im‐
3802 pacts the exported function fun1(), that uses type struct widget
3803 through a reference. But then abidiff doesn’t tell us about the impact
3804 on that function fun1() because it has evaluated that change as being
3805 redundant with the change it reported on fun0(). It has thus filtered
3806 it out, to avoid cluttering the output with noise.
3807 Redundancy detection and filtering is fine and helpful to avoid burying
3809 the important information in a sea of noise. However, it must be
3810 treated with care, by fear of mistakenly filtering out relevant and im‐
3811 portant information.
3812 That is why abidiff tells us about the impact that the change to struct
3814 widget has on function fun2(). In this case, that function uses the
3815 type struct widget directly (in its signature). It does not use it via
3816 a pointer or a reference. In this case, the direct use of this type
3817 causes fun2() to be exposed to a potentially harmful ABI change.
3818 Hence, the report about fun2() is not filtered out, even though it’s
3819 about that same change on struct widget.
3820 To go further in suppressing reports about changes that are harmless
3822 and keeping only those that we know are harmful, we would like to go
3823 tell abidiff to suppress reports about this particular struct widget
3824 change when it impacts uses of struct widget through a pointer or ref‐
3825 erence. In other words, suppress the change reports about fun0() and
3826 fun1(). We would then write this suppression specification, in file
3827 widget.suppr:
3828 [suppress_type]
3830 name = widget
3831 type_kind = struct
3832 has_data_member_inserted_at = end
3833 accessed_through = reference-or-pointer
3834 # So this suppression specification says to suppress reports about
3836 # the type 'struct widget', if this type was added some data member
3837 # at its end, and if the change impacts uses of the type through a
3838 # reference or a pointer.
3839 Invoking abidiff on widget-v0.o and widget-v1.o with this suppression
3841 specification yields:
3842 $ abidiff --suppressions widget.suppr widget-v0.o widget-v1.o
3844 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
3845 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3846 1 function with some indirect sub-type change:
3848 [C]'function void fun2(widget)' has some indirect sub-type changes:
3850 parameter 1 of type 'struct widget' has sub-type changes:
3851 type size changed from 64 to 128 bits
3852 2 data member insertions:
3853 'int widget::w', at offset 64 (in bits)
3854 'int widget::h', at offset 96 (in bits)
3855 $
3856 As expected, I guess.
3858 Suppressing change reports about functions.
3860 Suppose we have a first version a library named libtest2-v0.so whose
3862 source code is:
3863 $ cat -n test2-v0.cc
3865 1 struct S1
3867 2 {
3868 3 int m0;
3869 4
3870 5 S1()
3871 6 : m0()
3872 7 {}
3873 8 };
3874 9
3875 10 struct S2
3876 11 {
3877 12 int m0;
3878 13
3879 14 S2()
3880 15 : m0()
3881 16 {}
3882 17 };
3883 18
3884 19 struct S3
3885 20 {
3886 21 int m0;
3887 22
3888 23 S3()
3889 24 : m0()
3890 25 {}
3891 26 };
3892 27
3893 28 int
3894 29 func(S1&)
3895 30 {
3896 31 // suppose the code does something with the argument.
3897 32 return 0;
3898 33
3899 34 }
3900 35
3901 36 char
3902 37 func(S2*)
3903 38 {
3904 39 // suppose the code does something with the argument.
3905 40 return 0;
3906 41 }
3907 42
3908 43 unsigned
3909 44 func(S3)
3910 45 {
3911 46 // suppose the code does something with the argument.
3912 47 return 0;
3913 48 }
3914 $
3915 And then we come up with a second version libtest2-v1.so of that li‐
3917 brary; the source code is modified by making the structures S1, S2, S3
3918 inherit another struct:
3919 $ cat -n test2-v1.cc
3921 1 struct base_type
3922 2 {
3923 3 int m_inserted;
3924 4 };
3925 5
3926 6 struct S1 : public base_type // <--- S1 now has base_type as its base
3927 7 // type.
3928 8 {
3929 9 int m0;
3930 10
3931 11 S1()
3932 12 : m0()
3933 13 {}
3934 14 };
3935 15
3936 16 struct S2 : public base_type // <--- S2 now has base_type as its base
3937 17 // type.
3938 18 {
3939 19 int m0;
3940 20
3941 21 S2()
3942 22 : m0()
3943 23 {}
3944 24 };
3945 25
3946 26 struct S3 : public base_type // <--- S3 now has base_type as its base
3947 27 // type.
3948 28 {
3949 29 int m0;
3950 30
3951 31 S3()
3952 32 : m0()
3953 33 {}
3954 34 };
3955 35
3956 36 int
3957 37 func(S1&)
3958 38 {
3959 39 // suppose the code does something with the argument.
3960 40 return 0;
3961 41
3962 42 }
3963 43
3964 44 char
3965 45 func(S2*)
3966 46 {
3967 47 // suppose the code does something with the argument.
3968 48 return 0;
3969 49 }
3970 50
3971 51 unsigned
3972 52 func(S3)
3973 53 {
3974 54 // suppose the code does something with the argument.
3975 55 return 0;
3976 56 }
3977 $
3978 Now let’s build the two libraries:
3980 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
3982 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
3983 Let’s look at the output of abidiff:
3985 $ abidiff libtest2-v0.so libtest2-v1.so
3987 Functions changes summary: 0 Removed, 3 Changed, 0 Added functions
3988 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3989 3 functions with some indirect sub-type change:
3991 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
3993 parameter 0 of type 'struct S3' has sub-type changes:
3994 size changed from 32 to 64 bits
3995 1 base class insertion:
3996 struct base_type
3997 1 data member change:
3998 'int S3::m0' offset changed from 0 to 32
3999 [C]'function char func(S2*)' has some indirect sub-type changes:
4001 parameter 0 of type 'S2*' has sub-type changes:
4002 in pointed to type 'struct S2':
4003 size changed from 32 to 64 bits
4004 1 base class insertion:
4005 struct base_type
4006 1 data member change:
4007 'int S2::m0' offset changed from 0 to 32
4008 [C]'function int func(S1&)' has some indirect sub-type changes:
4010 parameter 0 of type 'S1&' has sub-type changes:
4011 in referenced type 'struct S1':
4012 size changed from 32 to 64 bits
4013 1 base class insertion:
4014 struct base_type
4015 1 data member change:
4016 'int S1::m0' offset changed from 0 to 32
4017 $
4018 Let’s tell abidiff to avoid showing us the differences on the overloads
4020 of func that takes either a pointer or a reference. For that, we au‐
4021 thor this simple suppression specification:
4022 $ cat -n libtest2.suppr
4024 1 [suppress_function]
4025 2 name = func
4026 3 parameter = '0 S1&
4027 4
4028 5 [suppress_function]
4029 6 name = func
4030 7 parameter = '0 S2*
4031 $
4032 And then let’s invoke abidiff with the suppression specification:
4034 $ ../build/tools/abidiff --suppressions libtest2.suppr libtest2-v0.so libtest2-v1.so
4036 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
4037 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4038 1 function with some indirect sub-type change:
4040 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
4042 parameter 0 of type 'struct S3' has sub-type changes:
4043 size changed from 32 to 64 bits
4044 1 base class insertion:
4045 struct base_type
4046 1 data member change:
4047 'int S3::m0' offset changed from 0 to 32
4048 The suppression specification could be reduced using regular expres‐
4050 sions:
4051 $ cat -n libtest2-1.suppr
4053 1 [suppress_function]
4054 2 name = func
4055 3 parameter = '0 /^S.(&|\\*)/
4056 $
4057 $ ../build/tools/abidiff --suppressions libtest2-1.suppr libtest2-v0.so libtest2-v1.so
4059 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
4060 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4061 1 function with some indirect sub-type change:
4063 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
4065 parameter 0 of type 'struct S3' has sub-type changes:
4066 size changed from 32 to 64 bits
4067 1 base class insertion:
4068 struct base_type
4069 1 data member change:
4070 'int S3::m0' offset changed from 0 to 32
4071 $
4073
4075 Dodji Seketeli
4076
4078 2014-2022, Red Hat, Inc.
4079 Dec 02, 2022 LIBABIGAIL(7)