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 or BTF
66 formats, if present. Finally, if no debug info in these formats is
67 found, it only considers ELF symbols and report about their addition or
68 removal.
69 This tool uses the libabigail library to analyze the binary as well as
71 its associated debug information. Here is its general mode of opera‐
72 tion.
73 When instructed to do so, a binary and its associated debug information
75 is read and analyzed. To that effect, libabigail analyzes by default
76 the descriptions of the types reachable by the interfaces (functions
77 and variables) that are visible outside of their translation unit.
78 Once that analysis is done, an Application Binary Interface Corpus is
79 constructed by only considering the subset of types reachable from in‐
80 terfaces associated to ELF symbols that are defined and exported by the
81 binary. It’s that final ABI corpus which libabigail considers as rep‐
82 resenting the ABI of the analyzed binary.
83 Libabigail then has capabilities to generate textual representations of
85 ABI Corpora, compare them, analyze their changes and report about them.
86 Invocation
88 abidiff [options] <first-shared-library> <second-shared-library>
89 Environment
91 abidiff loads two default suppression specifications files, merges
92 their content and use it to filter out ABI change reports that might be
93 considered as false positives to users.
94 • Default system-wide suppression specification file
96 It’s located by the optional environment variable LIBABIGAIL_DE‐
98 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
99 set, then abidiff tries to load the suppression file $libdir/libabi‐
100 gail/libabigail-default.abignore. If that file is not present, then
101 no default system-wide suppression specification file is loaded.
102 • Default user suppression specification file.
104 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
106 PRESSION_FILE. If that environment variable is not set, then abidiff
107 tries to load the suppression file $HOME/.abignore. If that file is
108 not present, then no default user suppression specification is
109 loaded.
110 Options
112 • --help | -h
113 Display a short help about the command and exit.
115 • --debug-self-comparison
117 In this mode, error messages are emitted for types which fail type
119 canonicalization, in some circumstances, when comparing a binary
120 against itself.
121 When comparing a binary against itself, canonical types of the
123 second binary should be equal (as much as possible) to canonical
124 types of the first binary. When some discrepancies are detected
125 in this mode, an abort signal is emitted and execution is halted.
126 This option should be used while executing the tool in a debugger,
127 for troubleshooting purposes.
128 This is an optional debugging and sanity check option. To enable
130 it the libabigail package needs to be configured with the –en‐
131 able-debug-self-comparison configure option.
132 • --debug-tc
134 In this mode, the process of type canonicalization is put under
136 heavy scrutiny. Basically, during type canonicalization, each
137 type comparison is performed twice: once in a structural mode
138 (comparing every sub-type member-wise), and once using canonical
139 comparison. The two comparisons should yield the same result.
140 Otherwise, an abort signal is emitted and the process can be de‐
141 bugged to understand why the two kinds of comparison yield differ‐
142 ent results.
143 This is an optional debugging and sanity check option. To enable
145 it the libabigail package needs to be configured with the –en‐
146 able-debug-type-canonicalization configure option.
147 • --version | -v
149 Display the version of the program and exit.
151 • --debug-info-dir1 | --d1 <di-path1>
153 For cases where the debug information for first-shared-library is
155 split out into a separate file, tells abidiff where to find that
156 separate debug information file.
157 Note that di-path must point to the root directory under which the
159 debug information is arranged in a tree-like manner. Under Red
160 Hat based systems, that directory is usually <root>/usr/lib/debug.
161 This option can be provided several times with different root di‐
163 rectories. In that case, abidiff will potentially look into all
164 those root directories to find the split debug info for
165 first-shared-library.
166 Note also that this option is not mandatory for split debug infor‐
168 mation installed by your system’s package manager because then
169 abidiff knows where to find it.
170 • --debug-info-dir2 | --d2 <di-path2>
172 Like --debug-info-dir1, this options tells abidiff where to find
174 the split debug information for the second-shared-library file.
175 This option can be provided several times with different root di‐
177 rectories. In that case, abidiff will potentially look into all
178 those root directories to find the split debug info for sec‐
179 ond-shared-library.
180 • --headers-dir1 | --hd1 <headers-directory-path-1>
182 Specifies where to find the public headers of the first shared li‐
184 brary (or binary in general) that the tool has to consider. The
185 tool will thus filter out ABI changes on types that are not de‐
186 fined in public headers.
187 Note that several public header directories can be specified for
189 the first shared library. In that case the --headers-dir1 option
190 should be present several times on the command line, like in the
191 following example:
192 $ abidiff --headers-dir1 /some/path \
194 --headers-dir1 /some/other/path \
195 binary-version-1 binary-version-2
196 • --header-file1 | --hf1 <header-file-path-1>
198 Specifies where to find one public header of the first shared li‐
200 brary that the tool has to consider. The tool will thus filter
201 out ABI changes on types that are not defined in public headers.
202 • --headers-dir2 | --hd2 <headers-directory-path-2>
204 Specifies where to find the public headers of the second shared
206 library that the tool has to consider. The tool will thus filter
207 out ABI changes on types that are not defined in public headers.
208 Note that several public header directories can be specified for
210 the second shared library. In that case the --headers-dir2 option
211 should be present several times like in the following example:
212 $ abidiff --headers-dir2 /some/path \
214 --headers-dir2 /some/other/path \
215 binary-version-1 binary-version-2
216 • --header-file2 | --hf2 <header-file-path-2>
218 Specifies where to find one public header of the second shared li‐
220 brary that the tool has to consider. The tool will thus filter
221 out ABI changes on types that are not defined in public headers.
222 • --add-binaries1 <bin1,bin2,bin3,..>
224 For each of the comma-separated binaries given in argument to this
226 option, if the binary is found in the directory specified by the
227 --added-binaries-dir1 option, then abidiff loads the ABI corpus of
228 the binary and adds it to a set of corpora (called an ABI Corpus
229 Group) that includes the first argument of abidiff.
230 That ABI corpus group is then compared against the second corpus
232 group given in argument to abidiff.
233 • --add-binaries2 <bin1,bin2,bin3,..>
235 For each of the comma-separated binaries given in argument to this
237 option, if the binary is found in the directory specified by the
238 --added-binaries-dir2 option, then abidiff loads the ABI corpus of
239 the binary and adds it to a set of corpora(called an ABI Corpus
240 Group) that includes the second argument of abidiff.
241 That ABI corpus group is then compared against the first corpus
243 group given in argument to abidiff.
244 • --follow-dependencies | --fdeps
246 For each dependency of the first argument of abidiff, if it’s
248 found in the directory specified by the --added-binaries-dir1 op‐
249 tion, then construct an ABI corpus out of the dependency, add it
250 to a set of corpora (called an ABI Corpus Group) that includes the
251 first argument of abidiff.
252 Similarly, for each dependency of the second argument of abidiff,
254 if it’s found in the directory specified by the --added-bina‐
255 ries-dir2 option, then construct an ABI corpus out of the depen‐
256 dency, add it to an ABI corpus group that includes the second ar‐
257 gument of abidiff.
258 These two ABI corpus groups are then compared against each other.
260 Said otherwise, this makes abidiff compare the set of its first
262 input and its dependencies against the set of its second input and
263 its dependencies.
264 • list-dependencies | --ldeps
266 This option lists all the dependencies of the input arguments of
268 abidiff that are found in the directories specified by the options
269 --added-binaries-dir1 and --added-binaries-dir2
270 • --added-binaries-dir1 | --abd1 <added-binaries-directory-1>
272 This option is to be used in conjunction with the --add-binaries1,
274 --follow-dependencies and --list-dependencies options. Binaries
275 referred to by these options, if found in the directory added-bi‐
276 naries-directory-1, are loaded as ABI corpus and are added to the
277 first ABI corpus group that is to be used in the comparison.
278 • --added-binaries-dir2 | --abd2 <added-binaries-directory-2>
280 This option is to be used in conjunction with the --add-binaries2,
282 --follow-dependencies and --list-dependencies options. Binaries
283 referred to by these options, if found in the directory added-bi‐
284 naries-directory-2, are loaded as ABI corpus and are added to the
285 second ABI corpus group to be used in the comparison.
286 • --no-linux-kernel-mode
288 Without this option, if abidiff detects that the binaries it is
290 looking at are Linux Kernel binaries (either vmlinux or modules)
291 then it only considers functions and variables which ELF symbols
292 are listed in the __ksymtab and __ksymtab_gpl sections.
293 With this option, abidiff considers the binary as a non-special
295 ELF binary. It thus considers functions and variables which are
296 defined and exported in the ELF sense.
297 • --kmi-whitelist | -kaw <path-to-whitelist>
299 When analyzing a Linux kernel binary, this option points to the
301 white list of names of ELF symbols of functions and variables
302 which ABI must be considered. That white list is called a “Kernel
303 Module Interface white list”. This is because for the Kernel, we
304 don’t talk about ABI; we rather talk about the interface between
305 the Kernel and its module. Hence the term KMI rather than ABI.
306 Any other function or variable which ELF symbol are not present in
308 that white list will not be considered by this tool.
309 If this option is not provided – thus if no white list is provided
311 – then the entire KMI, that is, the set of all publicly defined
312 and exported functions and global variables by the Linux Kernel
313 binaries, is considered.
314 • --drop-private-types
316 This option is to be used with the --headers-dir1, header-file1,
318 header-file2 and --headers-dir2 options. With this option, types
319 that are NOT defined in the headers are entirely dropped from the
320 internal representation build by Libabigail to represent the ABI.
321 They thus don’t have to be filtered out from the final ABI change
322 report because they are not even present in Libabigail’s represen‐
323 tation.
324 Without this option however, those private types are kept in the
326 internal representation and later filtered out from the report.
327 This options thus potentially makes Libabigail consume less mem‐
329 ory. It’s meant to be mainly used to optimize the memory consump‐
330 tion of the tool on binaries with a lot of publicly defined and
331 exported types.
332 • --exported-interfaces-only
334 By default, when looking at the debug information accompanying a
336 binary, this tool analyzes the descriptions of the types reachable
337 by the interfaces (functions and variables) that are visible out‐
338 side of their translation unit. Once that analysis is done, an
339 ABI corpus is constructed by only considering the subset of types
340 reachable from interfaces associated to ELF symbols that are de‐
341 fined and exported by the binary. It’s those final ABI Corpora
342 that are compared by this tool.
343 The problem with that approach however is that analyzing all the
345 interfaces that are visible from outside their translation unit
346 can amount to a lot of data, especially when those binaries are
347 applications, as opposed to shared libraries. One example of such
348 applications is the Linux Kernel. Analyzing massive ABI corpora
349 like these can be extremely slow.
350 To mitigate that performance issue, this option allows libabigail
352 to only analyze types that are reachable from interfaces associ‐
353 ated with defined and exported ELF symbols.
354 Note that this option is turned on by default when analyzing the
356 Linux Kernel. Otherwise, it’s turned off by default.
357 • --allow-non-exported-interfaces
359 When looking at the debug information accompanying a binary, this
361 tool analyzes the descriptions of the types reachable by the in‐
362 terfaces (functions and variables) that are visible outside of
363 their translation unit. Once that analysis is done, an ABI corpus
364 is constructed by only considering the subset of types reachable
365 from interfaces associated to ELF symbols that are defined and ex‐
366 ported by the binary. It’s those final ABI Corpora that are com‐
367 pared by this tool.
368 The problem with that approach however is that analyzing all the
370 interfaces that are visible from outside their translation unit
371 can amount to a lot of data, especially when those binaries are
372 applications, as opposed to shared libraries. One example of such
373 applications is the Linux Kernel. Analyzing massive ABI Corpora
374 like these can be extremely slow.
375 In the presence of an “average sized” binary however one can af‐
377 ford having libabigail analyze all interfaces that are visible
378 outside of their translation unit, using this option.
379 Note that this option is turned on by default, unless we are in
381 the presence of the Linux Kernel.
382 • --stat
384 Rather than displaying the detailed ABI differences between
386 first-shared-library and second-shared-library, just display some
387 summary statistics about these differences.
388 • --symtabs
390 Only display the symbol tables of the first-shared-library and
392 second-shared-library.
393 • --deleted-fns
395 In the resulting report about the differences between
397 first-shared-library and second-shared-library, only display the
398 globally defined functions that got deleted from first-shared-li‐
399 brary.
400 • --changed-fns
402 In the resulting report about the differences between
404 first-shared-library and second-shared-library, only display the
405 changes in sub-types of the global functions defined in
406 first-shared-library.
407 • --added-fns
409 In the resulting report about the differences between
411 first-shared-library and second-shared-library, only display the
412 globally defined functions that were added to second-shared-li‐
413 brary.
414 • --deleted-vars
416 In the resulting report about the differences between
418 first-shared-library and second-shared-library, only display the
419 globally defined variables that were deleted from first-shared-li‐
420 brary.
421 • --changed-vars
423 In the resulting report about the differences between
425 first-shared-library and second-shared-library, only display the
426 changes in the sub-types of the global variables defined in
427 first-shared-library
428 • --added-vars
430 In the resulting report about the differences between
432 first-shared-library and second-shared-library, only display the
433 global variables that were added (defined) to second-shared-li‐
434 brary.
435 • --non-reachable-types|-t
437 Analyze and emit change reports for all the types of the binary,
439 including those that are not reachable from global functions and
440 variables.
441 This option might incur some serious performance degradation as
443 the number of types analyzed can be huge. However, if paired with
444 the --headers-dir{1,2} and/or header-file{1,2} options, the addi‐
445 tional non-reachable types analyzed are restricted to those de‐
446 fined in public headers files, thus hopefully making the perfor‐
447 mance hit acceptable.
448 Also, using this option alongside suppression specifications (by
450 also using the --suppressions option) might help keep the number
451 of analyzed types (and the potential performance degradation) in
452 control.
453 Note that without this option, only types that are reachable from
455 global functions and variables are analyzed, so the tool detects
456 and reports changes on these reachable types only.
457 • --no-added-syms
459 In the resulting report about the differences between
461 first-shared-library and second-shared-library, do not display
462 added functions or variables. Do not display added functions or
463 variables ELF symbols either. All other kinds of changes are dis‐
464 played unless they are explicitely forbidden by other options on
465 the command line.
466 • --no-linkage-name
468 In the resulting report, do not display the linkage names of the
470 added, removed, or changed functions or variables.
471 • --no-show-locs
473 Do not show information about where in the second shared library
474 the respective type was changed.
475 • --show-bytes
477 Show sizes and offsets in bytes, not bits. By default, sizes and
479 offsets are shown in bits.
480 • --show-bits
482 Show sizes and offsets in bits, not bytes. This option is acti‐
484 vated by default.
485 • --show-hex
487 Show sizes and offsets in hexadecimal base.
489 • --show-dec
491 Show sizes and offsets in decimal base. This option is activated
493 by default.
494 • --ignore-soname
496 Ignore differences in the SONAME when doing a comparison
498 • --no-show-relative-offset-changes
500 Without this option, when the offset of a data member changes, the
502 change report not only mentions the older and newer offset, but it
503 also mentions by how many bits the data member changes. With this
504 option, the latter is not shown.
505 • --no-unreferenced-symbols
507 In the resulting report, do not display change information about
509 function and variable symbols that are not referenced by any debug
510 information. Note that for these symbols not referenced by any
511 debug information, the change information displayed is either
512 added or removed symbols.
513 • --no-default-suppression
515 Do not load the default suppression specification files.
517 • --suppressions | --suppr <path-to-suppressions>
519 Use a suppression specification file located at path-to-suppres‐
521 sions. Note that this option can appear multiple times on the
522 command line. In that case, all of the provided suppression spec‐
523 ification files are taken into account.
524 Please note that, by default, if this option is not provided, then
526 the default suppression specification files are loaded .
527 • --drop <regex>
529 When reading the first-shared-library and second-shared-library
531 ELF input files, drop the globally defined functions and variables
532 which name match the regular expression regex. As a result, no
533 change involving these functions or variables will be emitted in
534 the diff report.
535 • --drop-fn <regex>
537 When reading the first-shared-library and second-shared-library
539 ELF input files, drop the globally defined functions which name
540 match the regular expression regex. As a result, no change in‐
541 volving these functions will be emitted in the diff report.
542 • --drop-var <regex>
544 When reading the first-shared-library and second-shared-library
546 ELF input files, drop the globally defined variables matching a
547 the regular expression regex.
548 • --keep <regex>
550 When reading the first-shared-library and second-shared-library
552 ELF input files, keep the globally defined functions and variables
553 which names match the regular expression regex. All other func‐
554 tions and variables are dropped on the floor and will thus not ap‐
555 pear in the resulting diff report.
556 • --keep-fn <regex>
558 When reading the first-shared-library and second-shared-library
560 ELF input files, keep the globally defined functions which name
561 match the regular expression regex. All other functions are
562 dropped on the floor and will thus not appear in the resulting
563 diff report.
564 • --keep-var <regex>
566 When reading the first-shared-library and second-shared-library
568 ELF input files, keep the globally defined which names match the
569 regular expression regex. All other variables are dropped on the
570 floor and will thus not appear in the resulting diff report.
571 • --harmless
573 In the diff report, display only the harmless changes. By de‐
575 fault, the harmless changes are filtered out of the diff report
576 keep the clutter to a minimum and have a greater chance to spot
577 real ABI issues.
578 • --no-harmful
580 In the diff report, do not display the harmful changes. By de‐
582 fault, only the harmful changes are displayed in diff report.
583 • --redundant
585 In the diff report, do display redundant changes. A redundant
587 change is a change that has been displayed elsewhere in the re‐
588 port.
589 • --no-redundant
591 In the diff report, do NOT display redundant changes. A redundant
593 change is a change that has been displayed elsewhere in the re‐
594 port. This option is switched on by default.
595 • --no-architecture
597 Do not take architecture in account when comparing ABIs.
599 • --no-corpus-path
601 Do not emit the path attribute for the ABI corpus.
603 • --fail-no-debug-info
605 If no debug info was found, then this option makes the program to
607 fail. Otherwise, without this option, the program will attempt to
608 compare properties of the binaries that are not related to debug
609 info, like pure ELF properties.
610 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
612 pact analysis report. This option implies --redundant.
613 The typical output of abidiff when comparing two binaries looks
615 like this
616 $ abidiff libtest-v0.so libtest-v1.so
618 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
619 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
620 1 function with some indirect sub-type change:
622 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
624 parameter 1 of type 'C&' has sub-type changes:
625 in referenced type 'struct C' at test-v1.cc:7:1:
626 type size hasn't changed
627 1 data member change:
628 type of 'leaf* C::m0' changed:
629 in pointed to type 'struct leaf' at test-v1.cc:1:1:
630 type size changed from 32 to 64 bits
631 1 data member insertion:
632 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
633 $
635 So in that example the report emits information about how the data
637 member insertion change of “struct leaf” is reachable from func‐
638 tion “void fn(C&)”. In other words, the report not only shows the
639 data member change on “struct leaf”, but it also shows the impact
640 of that change on the function “void fn(C&)”.
641 In abidiff parlance, the change on “struct leaf” is called a leaf
643 change. So the --leaf-changes-only --impacted-interfaces options
644 show, well, only the leaf change. And it goes like this:
645 $ abidiff -l libtest-v0.so libtest-v1.so
647 'struct leaf' changed:
648 type size changed from 32 to 64 bits
649 1 data member insertion:
650 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
651 one impacted interface:
653 function void fn(C&)
654 $
655 Note how the report ends by showing the list of interfaces im‐
657 pacted by the leaf change.
658 Now if you don’t want to see that list of impacted interfaces,
660 then you can just avoid using the --impacted-interface option.
661 You can learn about that option below, in any case.
662 • --impacted-interfaces
664 When showing leaf changes, this option instructs abidiff to show
666 the list of impacted interfaces. This option is thus to be used
667 in addition the --leaf-changes-only option, otherwise, it’s ig‐
668 nored.
669 • --dump-diff-tree
671 After the diff report, emit a textual representation of the diff
672 nodes tree used by the comparison engine to represent the
673 changed functions and variables. That representation is emitted
674 to the error output for debugging purposes. Note that this diff
675 tree is relevant only to functions and variables that have some
676 sub-type changes. Added or removed functions and variables do
677 not have any diff nodes tree associated to them.
678 • --no-assume-odr-for-cplusplus
680 When analysing a binary originating from C++ code using DWARF de‐
682 bug information, libabigail assumes the One Definition Rule to
683 speed-up the analysis. In that case, when several types have the
684 same name in the binary, they are assumed to all be equal.
685 This option disables that assumption and instructs libabigail to
687 actually actually compare the types to determine if they are
688 equal.
689 • --no-leverage-dwarf-factorization
691 When analysing a binary which DWARF debug information was pro‐
693 cessed with the DWZ tool, the type information is supposed to be
694 already factorized. That context is used by libabigail to perform
695 some speed optimizations.
696 This option disables those optimizations.
698 • --no-change-categorization | -x
700 This option disables the categorization of changes into harmless
702 and harmful changes. Note that this categorization is a pre-req‐
703 uisite for the filtering of changes so this option disables that
704 filtering. The goal of this option is to speed-up the execution
705 of the program for cases where the graph of changes is huge and
706 where the user is just interested in looking at, for instance,
707 leaf node changes without caring about their possible impact on
708 interfaces. In that case, this option would be used along with
709 the --leaf-changes-only one.
710 • --ctf
712 When comparing binaries, extract ABI information from CTF debug
714 information, if present.
715 • --btf
717 When comparing binaries, extract ABI information from BTF debug
719 information, if present.
720 • --stats
722 Emit statistics about various internal things.
724 • --verbose
726 Emit verbose logs about the progress of miscellaneous internal
728 things.
729 Return values
731 The exit code of the abidiff command is either 0 if the ABI of the bi‐
732 naries being compared are equal, or non-zero if they differ or if the
733 tool encountered an error.
734 In the later case, the exit code is a 8-bits-wide bit field in which
736 each bit has a specific meaning.
737 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
739 ror.
740 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
742 an error in the way the user invoked the tool. It might be set, for
743 instance, if the user invoked the tool with an unknown command line
744 switch, with a wrong number or argument, etc. If this bit is set, then
745 the ABIDIFF_ERROR bit must be set as well.
746 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
748 the binaries being compared are different.
749 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
751 the ABI of the binaries compared are different in an incompatible way.
752 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
753 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
754 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
755 or might not be compatible. In that case, a human being needs to re‐
756 view the ABI changes to decide if they are compatible or not.
757 Note that, at the moment, there are only a few kinds of ABI changes
759 that would result in setting the flag ABIDIFF_ABI_INCOMPATIBLE_CHANGE.
760 Those ABI changes are either:
761 • the removal of the symbol of a function or variable that has been
763 defined and exported.
764 • the modification of the index of a member of a virtual function
766 table (for C++ programs and libraries).
767 With time, when more ABI change patterns are found to always constitute
769 incompatible ABI changes, we will adapt the code to recognize those
770 cases and set the ABIDIFF_ABI_INCOMPATIBLE_CHANGE accordingly. So, if
771 you find such patterns, please let us know.
772 The remaining bits are not used for the moment.
774 Usage examples
776 1. Detecting a change in a sub-type of a function:
777 $ cat -n test-v0.cc
779 1 // Compile this with:
780 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
781 3
782 4 struct S0
783 5 {
784 6 int m0;
785 7 };
786 8
787 9 void
788 10 foo(S0* /*parameter_name*/)
789 11 {
790 12 // do something with parameter_name.
791 13 }
792 $
793 $ cat -n test-v1.cc
794 1 // Compile this with:
795 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
796 3
797 4 struct type_base
798 5 {
799 6 int inserted;
800 7 };
801 8
802 9 struct S0 : public type_base
803 10 {
804 11 int m0;
805 12 };
806 13
807 14 void
808 15 foo(S0* /*parameter_name*/)
809 16 {
810 17 // do something with parameter_name.
811 18 }
812 $
813 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
814 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
815 $
816 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
817 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
818 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
819 1 function with some indirect sub-type change:
821 [C]'function void foo(S0*)' has some indirect sub-type changes:
823 parameter 0 of type 'S0*' has sub-type changes:
824 in pointed to type 'struct S0':
825 size changed from 32 to 64 bits
826 1 base class insertion:
827 struct type_base
828 1 data member change:
829 'int S0::m0' offset changed from 0 to 32
830 $
831 2. Detecting another change in a sub-type of a function:
833 $ cat -n test-v0.cc
835 1 // Compile this with:
836 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
837 3
838 4 struct S0
839 5 {
840 6 int m0;
841 7 };
842 8
843 9 void
844 10 foo(S0& /*parameter_name*/)
845 11 {
846 12 // do something with parameter_name.
847 13 }
848 $
849 $ cat -n test-v1.cc
850 1 // Compile this with:
851 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
852 3
853 4 struct S0
854 5 {
855 6 char inserted_member;
856 7 int m0;
857 8 };
858 9
859 10 void
860 11 foo(S0& /*parameter_name*/)
861 12 {
862 13 // do something with parameter_name.
863 14 }
864 $
865 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
866 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
867 $
868 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
869 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
870 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
871 1 function with some indirect sub-type change:
873 [C]'function void foo(S0&)' has some indirect sub-type changes:
875 parameter 0 of type 'S0&' has sub-type changes:
876 in referenced type 'struct S0':
877 size changed from 32 to 64 bits
878 1 data member insertion:
879 'char S0::inserted_member', at offset 0 (in bits)
880 1 data member change:
881 'int S0::m0' offset changed from 0 to 32
882 $
885 3. Detecting that functions got removed or added to a library:
887 $ cat -n test-v0.cc
889 1 // Compile this with:
890 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
891 3
892 4 struct S0
893 5 {
894 6 int m0;
895 7 };
896 8
897 9 void
898 10 foo(S0& /*parameter_name*/)
899 11 {
900 12 // do something with parameter_name.
901 13 }
902 $
903 $ cat -n test-v1.cc
904 1 // Compile this with:
905 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
906 3
907 4 struct S0
908 5 {
909 6 char inserted_member;
910 7 int m0;
911 8 };
912 9
913 10 void
914 11 bar(S0& /*parameter_name*/)
915 12 {
916 13 // do something with parameter_name.
917 14 }
918 $
919 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
920 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
921 $
922 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
923 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
924 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
925 1 Removed function:
927 'function void foo(S0&)' {_Z3fooR2S0}
928 1 Added function:
930 'function void bar(S0&)' {_Z3barR2S0}
931 $
933 4. Comparing two sets of binaries that are passed on the command
935 line:
936 $ abidiff --add-binaries1=file2-v1 \
938 --add-binaries2=file2-v2,file2-v1 \
939 --added-binaries-dir1 dir1 \
940 --added-binaries-dir2 dir2 \
941 file1-v1 file1-v2
942 Note that the files file2-v1, and file2-v2 are to be found in
944 dir1 and dir2 or in the current directory.
945 5. Compare two libraries and their dependencies:
947 $ abidiff --follow-dependencies \
949 --added-binaries-dir1 /some/where \
950 --added-binaries-dir2 /some/where/else \
951 foo bar
952 This compares the set of binaries comprised by foo and its depen‐
954 dencies against the set of binaries comprised by bar and its de‐
955 pendencies.
956 abipkgdiff
958 abipkgdiff compares the Application Binary Interfaces (ABI) of the ELF
959 binaries contained in two software packages. The software package for‐
960 mats currently supported are Deb, RPM, tar archives (either compressed
961 or not) and plain directories that contain binaries.
962 For a comprehensive ABI change report that includes changes about func‐
964 tion and variable sub-types, the two input packages must be accompanied
965 with their debug information packages that contain debug information
966 either in DWARF, CTF or in BTF formats. Please note however that some
967 packages contain binaries that embed the debug information directly in
968 a section of said binaries. In those cases, obviously, no separate de‐
969 bug information package is needed as the tool will find the debug in‐
970 formation inside the binaries.
971 By default, abipkgdiff uses debug information in DWARF format, if
973 present, otherwise it compares binaries interfaces using debug informa‐
974 tion in CTF or in BTF formats, if present. Finally, if no debug info in
975 these formats is found, it only considers ELF symbols and report about
976 their addition or removal.
977 This tool uses the libabigail library to analyze the binary as well as
979 its associated debug information. Here is its general mode of opera‐
980 tion.
981 When instructed to do so, a binary and its associated debug information
983 is read and analyzed. To that effect, libabigail analyzes by default
984 the descriptions of the types reachable by the interfaces (functions
985 and variables) that are visible outside of their translation unit.
986 Once that analysis is done, an Application Binary Interface Corpus is
987 constructed by only considering the subset of types reachable from in‐
988 terfaces associated to ELF symbols that are defined and exported by the
989 binary. It’s that final ABI corpus which libabigail considers as rep‐
990 resenting the ABI of the analyzed binary.
991 Libabigail then has capabilities to generate textual representations of
993 ABI Corpora, compare them, analyze their changes and report about them.
994 Invocation
996 abipkgdiff [option] <package1> <package2>
997 package1 and package2 are the packages that contain the binaries to be
999 compared.
1000 Environment
1002 abipkgdiff loads two default suppression specifications files, merges
1003 their content and use it to filter out ABI change reports that might be
1004 considered as false positives to users.
1005 • Default system-wide suppression specification file
1007 It’s located by the optional environment variable LIBABIGAIL_DE‐
1009 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
1010 set, then abipkgdiff tries to load the suppression file $lib‐
1011 dir/libabigail/libabigail-default.abignore. If that file is not
1012 present, then no default system-wide suppression specification file
1013 is loaded.
1014 • Default user suppression specification file.
1016 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
1018 PRESSION_FILE. If that environment variable is not set, then abip‐
1019 kgdiff tries to load the suppression file $HOME/.abignore. If that
1020 file is not present, then no default user suppression specification
1021 is loaded.
1022 In addition to those default suppression specification files, abip‐
1024 kgdiff will also look inside the packages being compared and if it sees
1025 a file that ends with the extension .abignore, then it will consider it
1026 as a suppression specification and it will combine it to the default
1027 suppression specification that might be already loaded.
1028 The user might as well use the --suppressions option (that is docu‐
1030 mented further below) to provide a suppression specification.
1031 Options
1033 • --help | -h
1034 Display a short help about the command and exit.
1036 • –version | -v
1038 Display the version of the program and exit.
1040 • --debug-info-pkg1 | --d1 <path>
1042 For cases where the debug information for package1 is split out
1044 into a separate file, tells abipkgdiff where to find that separate
1045 debug information package.
1046 Note that the debug info for package1 can have been split into
1048 several different debug info packages. In that case, several in‐
1049 stances of this options can be provided, along with those several
1050 different debug info packages.
1051 • --debug-info-pkg2 | --d2 <path>
1053 For cases where the debug information for package2 is split out
1055 into a separate file, tells abipkgdiff where to find that separate
1056 debug information package.
1057 Note that the debug info for package2 can have been split into
1059 several different debug info packages. In that case, several in‐
1060 stances of this options can be provided, along with those several
1061 different debug info packages.
1062 • --devel-pkg1 | --devel1 <path>
1064 Specifies where to find the Development Package associated with
1066 the first package to be compared. That Development Package at
1067 path should at least contain header files in which public types
1068 exposed by the libraries (of the first package to be compared) are
1069 defined. When this option is provided, the tool filters out re‐
1070 ports about ABI changes to types that are NOT defined in these
1071 header files.
1072 • --devel-pkg2 | --devel2 <path>
1074 Specifies where to find the Development Package associated with
1076 the second package to be compared. That Development Package at
1077 path should at least contains header files in which public types
1078 exposed by the libraries (of the second package to be compared)
1079 are defined. When this option is provided, the tool filters out
1080 reports about ABI changes to types that are NOT defined in these
1081 header files.
1082 • --drop-private-types
1084 This option is to be used with the --devel-pkg1 and --devel-pkg2
1086 options. With this option, types that are NOT defined in the
1087 headers are entirely dropped from the internal representation
1088 build by Libabigail to represent the ABI. They thus don’t have to
1089 be filtered out from the final ABI change report because they are
1090 not even present in Libabigail’s representation.
1091 Without this option however, those private types are kept in the
1093 internal representation and later filtered out from the report.
1094 This options thus potentially makes Libabigail consume less mem‐
1096 ory. It’s meant to be mainly used to optimize the memory consump‐
1097 tion of the tool on binaries with a lot of publicly defined and
1098 exported types.
1099 • --dso-only
1101 Compare ELF files that are shared libraries, only. Do not compare
1103 executable files, for instance.
1104 • --private-dso
1106 By default, abipkgdiff does not compare DSOs that are private to
1108 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
1109 vertised in the “provides” property of the RPM.
1110 This option instructs abipkgdiff to also compare DSOs that are NOT
1112 advertised in the “provides” property of the RPM.
1113 Please note that the fact that (by default) abipkgdiff skips pri‐
1115 vate DSO is a feature that is available only for RPMs, at the mo‐
1116 ment. We would happily accept patches adding that feature for
1117 other package formats.
1118 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
1120 pact analysis report. This option implies --redundant
1121 The typical output of abipkgdiff and abidiff when comparing two
1123 binaries, that we shall call full impact report, looks like this
1124 $ abidiff libtest-v0.so libtest-v1.so
1126 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
1127 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1128 1 function with some indirect sub-type change:
1130 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
1132 parameter 1 of type 'C&' has sub-type changes:
1133 in referenced type 'struct C' at test-v1.cc:7:1:
1134 type size hasn't changed
1135 1 data member change:
1136 type of 'leaf* C::m0' changed:
1137 in pointed to type 'struct leaf' at test-v1.cc:1:1:
1138 type size changed from 32 to 64 bits
1139 1 data member insertion:
1140 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1141 $
1143 So in that example the report emits information about how the data
1145 member insertion change of “struct leaf” is reachable from func‐
1146 tion “void fn(C&)”. In other words, the report not only shows the
1147 data member change on “struct leaf”, but it also shows the impact
1148 of that change on the function “void fn(C&)”.
1149 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
1151 is called a leaf change. So the --leaf-changes-only --im‐
1152 pacted-interfaces options show, well, only the leaf change. And
1153 it goes like this:
1154 $ abidiff -l libtest-v0.so libtest-v1.so
1156 'struct leaf' changed:
1157 type size changed from 32 to 64 bits
1158 1 data member insertion:
1159 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1160 one impacted interface:
1162 function void fn(C&)
1163 $
1164 Note how the report ends up by showing the list of interfaces im‐
1166 pacted by the leaf change. That’s the effect of the additional
1167 --impacted-interfaces option.
1168 Now if you don’t want to see that list of impacted interfaces,
1170 then you can just avoid using the --impacted-interface option.
1171 You can learn about that option below, in any case.
1172 Please note that when comparing two Linux Kernel packages, it’s
1174 this leaf changes report that is emitted, by default. The normal
1175 so-called full impact report can be emitted with the option
1176 --full-impact which is documented later below.
1177 • --impacted-interfaces
1179 When showing leaf changes, this option instructs abipkgdiff to
1181 show the list of impacted interfaces. This option is thus to be
1182 used in addition to the --leaf-changes-only option, or, when com‐
1183 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
1184 • --full-impact|-f
1186 When comparing two Linux Kernel packages, this function instructs
1188 abipkgdiff to emit the so-called full impact report, which is the
1189 default report kind emitted by the abidiff tool:
1190 $ abidiff libtest-v0.so libtest-v1.so
1192 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
1193 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1194 1 function with some indirect sub-type change:
1196 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
1198 parameter 1 of type 'C&' has sub-type changes:
1199 in referenced type 'struct C' at test-v1.cc:7:1:
1200 type size hasn't changed
1201 1 data member change:
1202 type of 'leaf* C::m0' changed:
1203 in pointed to type 'struct leaf' at test-v1.cc:1:1:
1204 type size changed from 32 to 64 bits
1205 1 data member insertion:
1206 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
1207 $
1209 • --non-reachable-types|-t
1211 Analyze and emit change reports for all the types of the binary,
1213 including those that are not reachable from global functions and
1214 variables.
1215 This option might incur some serious performance degradation as
1217 the number of types analyzed can be huge. However, if paired with
1218 the --devel-pkg{1,2} options, the additional non-reachable types
1219 analyzed are restricted to those defined in the public headers
1220 files carried by the referenced development packages, thus hope‐
1221 fully making the performance hit acceptable.
1222 Also, using this option alongside suppression specifications (by
1224 also using the --suppressions option) might help keep the number
1225 of analyzed types (and the potential performance degradation) in
1226 control.
1227 Note that without this option, only types that are reachable from
1229 global functions and variables are analyzed, so the tool detects
1230 and reports changes on these reachable types only.
1231 • --exported-interfaces-only
1233 By default, when looking at the debug information accompanying a
1235 binary, this tool analyzes the descriptions of the types reachable
1236 by the interfaces (functions and variables) that are visible out‐
1237 side of their translation unit. Once that analysis is done, an
1238 ABI corpus is constructed by only considering the subset of types
1239 reachable from interfaces associated to ELF symbols that are de‐
1240 fined and exported by the binary. It’s those final ABI Corpora
1241 that are compared by this tool.
1242 The problem with that approach however is that analyzing all the
1244 interfaces that are visible from outside their translation unit
1245 can amount to a lot of data, especially when those binaries are
1246 applications, as opposed to shared libraries. One example of such
1247 applications is the Linux Kernel. Analyzing massive ABI corpora
1248 like these can be extremely slow.
1249 To mitigate that performance issue, this option allows libabigail
1251 to only analyze types that are reachable from interfaces associ‐
1252 ated with defined and exported ELF symbols.
1253 Note that this option is turned on by default when analyzing the
1255 Linux Kernel. Otherwise, it’s turned off by default.
1256 • --allow-non-exported-interfaces
1258 When looking at the debug information accompanying a binary, this
1260 tool analyzes the descriptions of the types reachable by the in‐
1261 terfaces (functions and variables) that are visible outside of
1262 their translation unit. Once that analysis is done, an ABI corpus
1263 is constructed by only considering the subset of types reachable
1264 from interfaces associated to ELF symbols that are defined and ex‐
1265 ported by the binary. It’s those final ABI Corpora that are com‐
1266 pared by this tool.
1267 The problem with that approach however is that analyzing all the
1269 interfaces that are visible from outside their translation unit
1270 can amount to a lot of data, especially when those binaries are
1271 applications, as opposed to shared libraries. One example of such
1272 applications is the Linux Kernel. Analyzing massive ABI Corpora
1273 like these can be extremely slow.
1274 In the presence of an “average sized” binary however one can af‐
1276 ford having libabigail analyze all interfaces that are visible
1277 outside of their translation unit, using this option.
1278 Note that this option is turned on by default, unless we are in
1280 the presence of the Linux Kernel.
1281 • --redundant
1283 In the diff reports, do display redundant changes. A redundant
1284 change is a change that has been displayed elsewhere in a given
1285 report.
1286 • --harmless
1288 In the diff report, display only the harmless changes. By de‐
1290 fault, the harmless changes are filtered out of the diff report
1291 keep the clutter to a minimum and have a greater chance to spot
1292 real ABI issues.
1293 • --no-linkage-name
1295 In the resulting report, do not display the linkage names of the
1297 added, removed, or changed functions or variables.
1298 • --no-added-syms
1300 Do not show the list of functions, variables, or any symbol that
1302 was added.
1303 • --no-added-binaries
1305 Do not show the list of binaries that got added to the second
1307 package.
1308 Please note that the presence of such added binaries is not con‐
1310 sidered like an ABI change by this tool; as such, it doesn’t have
1311 any impact on the exit code of the tool. It does only have an in‐
1312 formational value. Removed binaries are, however, considered as
1313 an ABI change.
1314 • --no-abignore
1316 Do not search the package for the presence of suppression files.
1318 • --no-parallel
1320 By default, abipkgdiff will use all the processors it has avail‐
1322 able to execute concurrently. This option tells it not to extract
1323 packages or run comparisons in parallel.
1324 • --no-default-suppression
1326 Do not load the default suppression specification files.
1328 • --suppressions | --suppr <path-to-suppressions>
1330 Use a suppression specification file located at path-to-suppres‐
1332 sions. Note that this option can appear multiple times on the
1333 command line. In that case, all of the suppression specification
1334 files are taken into account.
1335 Please note that, by default, if this option is not provided, then
1337 the default suppression specification files are loaded .
1338 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
1340 When comparing two Linux kernel RPM packages, this option points
1342 to the white list of names of ELF symbols of functions and vari‐
1343 ables that must be compared for ABI changes. That white list is
1344 called a “Linux kernel ABI white list”.
1345 Any other function or variable which ELF symbol are not present in
1347 that white list will not be considered by the ABI comparison
1348 process.
1349 If this option is not provided – thus if no white list is provided
1351 – then the ABI of all publicly defined and exported functions and
1352 global variables by the Linux Kernel binaries are compared.
1353 Please note that if a white list package is given in parameter,
1355 this option handles it just fine, like if the –wp option was used.
1356 • --wp <path-to-whitelist-package>
1358 When comparing two Linux kernel RPM packages, this option points
1360 an RPM package containining several white lists of names of ELF
1361 symbols of functions and variables that must be compared for ABI
1362 changes. Those white lists are called “Linux kernel ABI white
1363 lists”.
1364 From the content of that white list package, this program then
1366 chooses the appropriate Linux kernel ABI white list to consider
1367 when comparing the ABI of Linux kernel binaries contained in the
1368 Linux kernel packages provided on the command line.
1369 That choosen Linux kernel ABI white list contains the list of
1371 names of ELF symbols of functions and variables that must be com‐
1372 pared for ABI changes.
1373 Any other function or variable which ELF symbol are not present in
1375 that white list will not be considered by the ABI comparison
1376 process.
1377 Note that this option can be provided twice (not mor than twice),
1379 specifying one white list package for each Linux Kernel package
1380 that is provided on the command line.
1381 If this option is not provided – thus if no white list is provided
1383 – then the ABI of all publicly defined and exported functions and
1384 global variables by the Linux Kernel binaries are compared.
1385 • --no-unreferenced-symbols
1387 In the resulting report, do not display change information about
1389 function and variable symbols that are not referenced by any debug
1390 information. Note that for these symbols not referenced by any
1391 debug information, the change information displayed is either
1392 added or removed symbols.
1393 • --no-show-locs
1395 Do not show information about where in the second shared library
1396 the respective type was changed.
1397 • --show-bytes
1399 Show sizes and offsets in bytes, not bits. By default, sizes and
1401 offsets are shown in bits.
1402 • --show-bits
1404 Show sizes and offsets in bits, not bytes. This option is acti‐
1406 vated by default.
1407 • --show-hex
1409 Show sizes and offsets in hexadecimal base.
1411 • --show-dec
1413 Show sizes and offsets in decimal base. This option is activated
1415 by default.
1416 • --no-show-relative-offset-changes
1418 Without this option, when the offset of a data member changes, the
1420 change report not only mentions the older and newer offset, but it
1421 also mentions by how many bits the data member changes. With this
1422 option, the latter is not shown.
1423 • --show-identical-binaries
1425 Show the names of the all binaries compared, including the bina‐
1426 ries whose ABI compare equal. By default, when this option is
1427 not provided, only binaries with ABI changes are mentionned in
1428 the output.
1429 • --fail-no-dbg
1431 Make the program fail and return a non-zero exit code if couldn’t
1433 read any of the debug information that comes from the debug info
1434 packages that were given on the command line. If no debug info
1435 package were provided on the command line then this option is not
1436 active.
1437 Note that the non-zero exit code returned by the program as a re‐
1439 sult of this option is the constant ABIDIFF_ERROR. To know the
1440 numerical value of that constant, please refer to the exit code
1441 documentation.
1442 • --keep-tmp-files
1444 Do not erase the temporary directory files that are created during
1446 the execution of the tool.
1447 • --verbose
1449 Emit verbose progress messages.
1451 • --self-check
1453 This is used to test the underlying Libabigail library. When in
1455 used, the command expects only on input package, along with its
1456 associated debug info packages. The command then compares each
1457 binary inside the package against its own ABIXML representation.
1458 The result of the comparison should yield the empty set if Libabi‐
1459 gail behaves correctly. Otherwise, it means there is an issue
1460 that ought to be fixed. This option is used by people interested
1461 in Libabigail development for regression testing purposes. Here
1462 is an example of the use of this option:
1463 $ 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
1465 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
1466 $
1467 • --no-assume-odr-for-cplusplus
1469 When analysing a binary originating from C++ code using DWARF de‐
1471 bug information, libabigail assumes the One Definition Rule to
1472 speed-up the analysis. In that case, when several types have the
1473 same name in the binary, they are assumed to all be equal.
1474 This option disables that assumption and instructs libabigail to
1476 actually actually compare the types to determine if they are
1477 equal.
1478 • --no-leverage-dwarf-factorization
1480 When analysing a binary which DWARF debug information was pro‐
1482 cessed with the DWZ tool, the type information is supposed to be
1483 already factorized. That context is used by libabigail to perform
1484 some speed optimizations.
1485 This option disables those optimizations.
1487 • --ctf
1489 This is used to compare packages with CTF debug information,
1490 if present.
1491 • --btf
1493 This is used to compare packages with BTF debug information,
1494 if present.
1495 Return value
1497 The exit code of the abipkgdiff command is either 0 if the ABI of the
1498 binaries compared are equal, or non-zero if they differ or if the tool
1499 encountered an error.
1500 In the later case, the value of the exit code is the same as for the
1502 abidiff tool.
1503 kmidiff
1505 kmidiff compares the binary Kernel Module Interfaces of two Linux Ker‐
1506 nel trees. The binary KMI is the interface that the Linux Kernel ex‐
1507 poses to its modules. The trees we are interested in here are the re‐
1508 sult of the build of the Linux Kernel source tree.
1509 General approach
1511 And example of how to build your kernel if you want to compare it to
1512 another one using kmidiff is:
1513 git clone -b v4.5 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux/v4.5
1515 cd linux/v4.5
1516 make allyesconfig all
1517 Then install the modules into a directory, for instance, the build/mod‐
1519 ules sub-directory of the your kernel source tree:
1520 mkdir build/modules
1522 make modules_install INSTALL_MOD_DIR=build/modules
1523 Then construct a list of interfaces exported by the kernel, that you
1525 want to compare:
1526 cat > kmi-whitelist << EOF
1528 [kernel_4.5_kmi_whitelist]
1529 init_task
1530 schedule
1531 dev_queue_xmit
1532 __kmalloc
1533 printk
1534 EOF
1535 Suppose you’ve done something similar for the v4.6 branch of the Linux
1537 kernel, you now have these two directories: linux/v4.5 and linux/v4.6.
1538 Their modules are present under the directories linux/v4.5/build/mod‐
1539 ules and linux/v4.6/build/modules.
1540 To Comparing their KMI kmidiff needs to know where to find the vmlinux
1542 binaries and their associated modules. Here would be what the command
1543 line looks like:
1544 kmidiff \
1546 --kmi-whitelist linux/v4.6/kmi-whitelist \
1547 --vmlinux1 linux/v4.5/vmlinux \
1548 --vmlinux2 linux/v4.6/vmlinux \
1549 linux/v4.5/build/modules \
1550 linux/v4.6/build/modules
1551 This tool uses the libabigail library to analyze the binary as well as
1553 its associated debug information. Here is its general mode of opera‐
1554 tion.
1555 When instructed to do so, a binary and its associated debug information
1557 is read and analyzed. To that effect, libabigail analyzes by default
1558 the descriptions of the types reachable by the interfaces (functions
1559 and variables) that are visible outside of their translation unit.
1560 Once that analysis is done, an Application Binary Interface Corpus is
1561 constructed by only considering the subset of types reachable from in‐
1562 terfaces associated to ELF symbols that are defined and exported by the
1563 binary. It’s that final ABI corpus which libabigail considers as rep‐
1564 resenting the ABI of the analyzed binary.
1565 Libabigail then has capabilities to generate textual representations of
1567 ABI Corpora, compare them, analyze their changes and report about them.
1568 Invocation
1570 More generally, kmidiff is invoked under the form:
1571 kmidiff [options] <first-modules-dir> <second-modules-dir>
1573 Environment
1575 By default, kmidiff compares all the interfaces (exported functions and
1576 variables) between the Kernel and its modules. In practice, though,
1577 some users might want to compare a subset of the those interfaces.
1578 By default, kmidiff uses debug information in the DWARF debug info for‐
1580 mat, if present, otherwise it compares interfaces using CTF or BTF de‐
1581 bug info formats, if present. Finally, if no debug info in these for‐
1582 mats is found, it only considers ELF symbols and report about their ad‐
1583 dition or removal.
1584 Users can then define a “white list” of the interfaces to compare.
1586 Such a white list is a just a file in the “INI” format that looks like:
1587 [kernel_version_x86_64_whitelist]
1589 function1_name
1590 function2_name
1591 global_variable1_name
1592 ....
1593 Note that the name of the section (the name that is between the two
1595 brackets) of that INI file just has to end with the string “whitelist”.
1596 So you can define the name you want, for instance [ker‐
1597 nel_46_x86_64_whitelist].
1598 Then each line of that whitelist file is the name of an exported func‐
1600 tion or variable. Only those interfaces along with the types reachable
1601 from their signatures are going to be compared by kmidiff recursively.
1602 Note that by default kmidiff analyzes the types reachable from the in‐
1604 terfaces associated with ELF symbols that are defined and exported by
1605 the Linux Kernel as being the union of the vmlinux binary and all its
1606 compiled modules. It then compares those interfaces (along with their
1607 types).
1608 Options
1610 • --help | -h
1611 Display a short help about the command and exit.
1613 • --version | -v
1615 Display the version of the program and exit.
1617 • --verbose
1619 Display some verbose messages while executing.
1621 • --debug-info-dir1 | --d1 <di-path1>
1623 For cases where the debug information for the binaries of the
1625 first Linux kernel is split out into separate files, tells kmidiff
1626 where to find those separate debug information files.
1627 Note that di-path must point to the root directory under which the
1629 debug information is arranged in a tree-like manner. Under Red
1630 Hat based systems, that directory is usually <root>/usr/lib/debug.
1631 • --debug-info-dir2 | --d2 <di-path2>
1633 Like --debug-info-dir1, this options tells kmidiff where to find
1635 the split debug information for the binaries of the second Linux
1636 kernel.
1637 • --vmlinux1 | --l1 <path-to-first-vmlinux>
1639 Sets the path to the first vmlinux binary to consider. This has
1641 to be the uncompressed vmlinux binary compiled with debug info.
1642 • --vmlinux2 | --l2 <path-to-first-vmlinux>
1644 Sets the path to the second vmlinux binary to consider. This has
1646 to be the uncompressed vmlinux binary compiled with debug info.
1647 • --kmi-whitelist | -w <path-to-interface-whitelist>
1649 Set the path to the white list of interfaces to compare while com‐
1651 paring the Kernel Module Interface of the first kernel against the
1652 one of the second kernel.
1653 If this option is not provided, all the exported interfaces of the
1655 two kernels are compared. That takes a lot of times and is not
1656 necessarily meaningful because many interface are probably meant
1657 to see their reachable types change.
1658 So please, make sure you always use this option unless you really
1660 know what you are doing.
1661 • --suppressions | --suppr <path-to-suppressions>
1663 Use a suppression specification file located at path-to-suppres‐
1665 sions. Note that this option can appear multiple times on the
1666 command line. In that case, all of the provided suppression spec‐
1667 ification files are taken into account.
1668 Please note that, by default, if this option is not provided, then
1670 the default suppression specification files are loaded .
1671 • --no-change-categorization | -x
1673 This option disables the categorization of changes into harmless
1675 and harmful changes. Note that this categorization is a pre-req‐
1676 uisite for the filtering of changes so this option disables that
1677 filtering. The goal of this option is to speed-up the execution
1678 of the program for cases where the graph of changes is huge and
1679 where the user is just interested in looking at, for instance,
1680 leaf node changes without caring about their possible impact on
1681 interfaces.
1682 • --ctf
1684 Extract ABI information from CTF debug information, if present, in
1686 the Kernel and Modules.
1687 • --btf
1689 Extract ABI information from BTF debug information, if present, in
1691 the Kernel and Modules.
1692 • --impacted-interfaces | -i
1694 Tell what interfaces got impacted by each individual ABI change.
1696 • --full-impact | -f
1698 Emit a change report that shows the full impact of each change on
1700 exported interfaces. This is the default kind of report emitted
1701 by tools like abidiff or abipkgdiff.
1702 • --exported-interfaces-only
1704 When using this option, this tool analyzes the descriptions of the
1706 types reachable by the interfaces (functions and variables) asso‐
1707 ciated with ELF symbols that are defined and exported by the Linux
1708 Kernel.
1709 Otherwise, the tool also has the ability to analyze the descrip‐
1711 tions of the types reachable by the interfaces associated with ELF
1712 symbols that are visible outside their translation unit. This
1713 later possibility is however much more resource intensive and re‐
1714 sults in much slower operations.
1715 That is why this option is enabled by default.
1717 • --allow-non-exported-interfaces
1719 When using this option, this tool analyzes the descriptions of the
1721 types reachable by the interfaces (functions and variables) that
1722 are visible outside of their translation unit. Once that analysis
1723 is done, an ABI Corpus is constructed by only considering the sub‐
1724 set of types reachable from interfaces associated to ELF symbols
1725 that are defined and exported by the binary. It’s that final ABI
1726 corpus which is compared against another one.
1727 The problem with that approach however is that analyzing all the
1729 interfaces that are visible from outside their translation unit
1730 can amount to a lot of data, leading to very slow operations.
1731 Note that this option is turned off by default.
1733 • --show-bytes
1735 Show sizes and offsets in bytes, not bits. This option is acti‐
1737 vated by default.
1738 • --show-bits
1740 Show sizes and offsets in bits, not bytes. By default, sizes and
1742 offsets are shown in bytes.
1743 • --show-hex
1745 Show sizes and offsets in hexadecimal base. This option is acti‐
1747 vated by default.
1748 • --show-dec
1750 Show sizes and offsets in decimal base.
1752 abidw
1754 abidw reads a shared library in ELF format and emits an XML representa‐
1755 tion of its ABI to standard output. The emitted representation format,
1756 named ABIXML, includes all the globally defined functions and vari‐
1757 ables, along with a complete representation of their types. It also
1758 includes a representation of the globally defined ELF symbols of the
1759 file.
1760 When given the --linux-tree option, this program can also handle a
1762 Linux kernel tree. That is, a directory tree that contains both the
1763 vmlinux binary and Linux Kernel modules. It analyses those Linux Ker‐
1764 nel binaries and emits an XML representation of the interface between
1765 the kernel and its module, to standard output. In this case, we don’t
1766 call it an ABI, but a KMI (Kernel Module Interface). The emitted KMI
1767 includes all the globally defined functions and variables, along with a
1768 complete representation of their types.
1769 To generate either ABI or KMI representation, by default abidw uses de‐
1771 bug information in the DWARF format, if present, otherwise it looks for
1772 debug information in CTF or BTF formats, if present. Finally, if no
1773 debug info in these formats is found, it only considers ELF symbols and
1774 report about their addition or removal.
1775 This tool uses the libabigail library to analyze the binary as well as
1777 its associated debug information. Here is its general mode of opera‐
1778 tion.
1779 When instructed to do so, a binary and its associated debug information
1781 is read and analyzed. To that effect, libabigail analyzes by default
1782 the descriptions of the types reachable by the interfaces (functions
1783 and variables) that are visible outside of their translation unit.
1784 Once that analysis is done, an Application Binary Interface Corpus is
1785 constructed by only considering the subset of types reachable from in‐
1786 terfaces associated to ELF symbols that are defined and exported by the
1787 binary. It’s that final ABI corpus which libabigail considers as rep‐
1788 resenting the ABI of the analyzed binary.
1789 Libabigail then has capabilities to generate textual representations of
1791 ABI Corpora, compare them, analyze their changes and report about them.
1792 Invocation
1794 abidw [options] [<path-to-elf-file>]
1795 Options
1797 • --help | -h
1798 Display a short help about the command and exit.
1800 • --version | -v
1802 Display the version of the program and exit.
1804 • --abixml-version
1806 Display the version of the ABIXML format emitted by this program
1808 and exit.
1809 • --add-binaries <bin1,bin2,…>
1811 For each of the comma-separated binaries given in argument to this
1813 option, if the binary is found in the directory specified by the
1814 –added-binaries-dir option, then load the ABI corpus of the binary
1815 and add it to a set of ABI corpora (called a ABI Corpus Group)
1816 made of the binary denoted by the Argument of abidw. That corpus
1817 group is then serialized out.
1818 • --follow-dependencies
1820 For each dependency of the input binary of abidw, if it is found
1822 in the directory specified by the --added-binaries-dir option,
1823 then construct an ABI corpus out of the dependency and add it to a
1824 set of ABI corpora (called an ABI Corpus Group) along with the ABI
1825 corpus of the input binary of the program. The ABI Corpus Group
1826 is then serialized out.
1827 • --list-dependencies
1829 For each dependency of the input binary of``abidw``, if it’s found
1831 in the directory specified by the --added-binaries-dir option,
1832 then the name of the dependency is printed out.
1833 • --added-binaries-dir | --abd <dir-path>
1835 This option is to be used in conjunction with the --add-binaries,
1837 the --follow-dependencies or the --list-dependencies option. Bi‐
1838 naries listed as arguments of the --add-binaries option or being
1839 dependencies of the input binary in the case of the --follow-de‐
1840 pendencies option and found in the directory <dir-path> are going
1841 to be loaded as ABI corpus and added to the set of ABI corpora
1842 (called an ABI corpus group) built and serialized.
1843 • --debug-info-dir | -d <dir-path>
1845 In cases where the debug info for path-to-elf-file is in a sepa‐
1847 rate file that is located in a non-standard place, this tells
1848 abidw where to look for that debug info file.
1849 Note that dir-path must point to the root directory under which
1851 the debug information is arranged in a tree-like manner. Under
1852 Red Hat based systems, that directory is usually
1853 <root>/usr/lib/debug.
1854 This option can be provided several times with different root di‐
1856 rectories. In that case, abidw will potentially look into all
1857 those root directories to find the split debug info for the elf
1858 file.
1859 Note that this option is not mandatory for split debug information
1861 installed by your system’s package manager because then abidw
1862 knows where to find it.
1863 • --out-file <file-path>
1865 This option instructs abidw to emit the XML representation of
1867 path-to-elf-file into the file file-path, rather than emitting it
1868 to its standard output.
1869 • --noout
1871 This option instructs abidw to not emit the XML representation of
1873 the ABI. So it only reads the ELF and debug information, builds
1874 the internal representation of the ABI and exits. This option is
1875 usually useful for debugging purposes.
1876 • --no-corpus-path
1878 Do not emit the path attribute for the ABI corpus.
1880 • --suppressions | suppr <path-to-suppression-specifications-file>
1882 Use a suppression specification file located at path-to-suppres‐
1884 sion-specifications-file. Note that this option can appear multi‐
1885 ple times on the command line. In that case, all of the provided
1886 suppression specification files are taken into account. ABI arti‐
1887 facts matched by the suppression specifications are suppressed
1888 from the output of this tool.
1889 • --kmi-whitelist | -kaw <path-to-whitelist>
1891 When analyzing a Linux Kernel binary, this option points to the
1893 white list of names of ELF symbols of functions and variables
1894 which ABI must be written out. That white list is called a ” Ker‐
1895 nel Module Interface white list”. This is because for the Kernel,
1896 we don’t talk about the ABI; we rather talk about the interface
1897 between the Kernel and its module. Hence the term KMI rather than
1898 ABI
1899 Any other function or variable which ELF symbol are not present in
1901 that white list will not be considered by the KMI writing process.
1902 If this option is not provided – thus if no white list is provided
1904 – then the entire KMI, that is, all publicly defined and exported
1905 functions and global variables by the Linux Kernel binaries is
1906 emitted.
1907 • --linux-tree | --lt
1909 Make abidw to consider the input path as a path to a directory
1911 containing the vmlinux binary as several kernel modules binaries.
1912 In that case, this program emits the representation of the Kernel
1913 Module Interface (KMI) on the standard output.
1914 Below is an example of usage of abidw on a Linux Kernel tree.
1916 First, checkout a Linux Kernel source tree and build it. Then in‐
1918 stall the kernel modules in a directory somewhere. Copy the vm‐
1919 linux binary into that directory too. And then serialize the KMI
1920 of that kernel to disk, using abidw:
1921 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
1923 $ cd linux && git checkout v4.5
1924 $ make allyesconfig all
1925 $ mkdir build-output
1926 $ make INSTALL_MOD_PATH=./build-output modules_install
1927 $ cp vmlinux build-output/modules/4.5.0
1928 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
1929 • --headers-dir | --hd <headers-directory-path-1>
1931 Specifies where to find the public headers of the binary that the
1933 tool has to consider. The tool will thus filter out types that
1934 are not defined in public headers.
1935 Note that several public header directories can be specified for
1937 the binary to consider. In that case the --header-dir option
1938 should be present several times on the command line, like in the
1939 following example:
1940 $ abidw --header-dir /some/path \
1942 --header-dir /some/other/path \
1943 binary > binary.abi
1944 • --header-file | --hf <header-file-path>
1946 Specifies where to find one of the public headers of the abi file
1948 that the tool has to consider. The tool will thus filter out
1949 types that are not defined in public headers.
1950 • --drop-private-types
1952 This option is to be used with the --headers-dir and/or
1954 header-file options. With this option, types that are NOT defined
1955 in the headers are entirely dropped from the internal representa‐
1956 tion build by Libabigail to represent the ABI and will not end up
1957 in the abi XML file.
1958 • --no-elf-needed
1960 Do not include the list of DT_NEEDED dependency names in the cor‐
1962 pus.
1963 • --drop-undefined-syms
1965 With this option functions or variables for which the (exported)
1967 ELF symbol is undefined are dropped from the internal representa‐
1968 tion build by Libabigail to represent the ABI and will not end up
1969 in the abi XML file.
1970 • --exported-interfaces-only
1972 By default, when looking at the debug information accompanying a
1974 binary, this tool analyzes the descriptions of the types reachable
1975 by the interfaces (functions and variables) that are visible out‐
1976 side of their translation unit. Once that analysis is done, an
1977 ABI corpus is constructed by only considering the subset of types
1978 reachable from interfaces associated to ELF symbols that are de‐
1979 fined and exported by the binary. It’s that final ABI corpus
1980 which textual representation is saved as ABIXML.
1981 The problem with that approach however is that analyzing all the
1983 interfaces that are visible from outside their translation unit
1984 can amount to a lot of data, especially when those binaries are
1985 applications, as opposed to shared libraries. One example of such
1986 applications is the Linux Kernel. Analyzing massive ABI corpora
1987 like these can be extremely slow.
1988 To mitigate that performance issue, this option allows libabigail
1990 to only analyze types that are reachable from interfaces associ‐
1991 ated with defined and exported ELF symbols.
1992 Note that this option is turned on by default when analyzing the
1994 Linux Kernel. Otherwise, it’s turned off by default.
1995 • --allow-non-exported-interfaces
1997 When looking at the debug information accompanying a binary, this
1999 tool analyzes the descriptions of the types reachable by the in‐
2000 terfaces (functions and variables) that are visible outside of
2001 their translation unit. Once that analysis is done, an ABI corpus
2002 is constructed by only considering the subset of types reachable
2003 from interfaces associated to ELF symbols that are defined and ex‐
2004 ported by the binary. It’s that final ABI corpus which textual
2005 representation is saved as ABIXML.
2006 The problem with that approach however is that analyzing all the
2008 interfaces that are visible from outside their translation unit
2009 can amount to a lot of data, especially when those binaries are
2010 applications, as opposed to shared libraries. One example of such
2011 applications is the Linux Kernel. Analyzing massive ABI corpora
2012 like these can be extremely slow.
2013 In the presence of an “average sized” binary however one can af‐
2015 ford having libabigail analyze all interfaces that are visible
2016 outside of their translation unit, using this option.
2017 Note that this option is turned on by default, unless we are in
2019 the presence of the Linux Kernel.
2020 • --no-linux-kernel-mode
2022 Without this option, if abipkgiff detects that the binaries it is
2024 looking at are Linux Kernel binaries (either vmlinux or modules)
2025 then it only considers functions and variables which ELF symbols
2026 are listed in the __ksymtab and __ksymtab_gpl sections.
2027 With this option, abipkgdiff considers the binary as a non-special
2029 ELF binary. It thus considers functions and variables which are
2030 defined and exported in the ELF sense.
2031 • --check-alternate-debug-info <elf-path>
2033 If the debug info for the file elf-path contains a reference to an
2035 alternate debug info file, abidw checks that it can find that al‐
2036 ternate debug info file. In that case, it emits a meaningful suc‐
2037 cess message mentioning the full path to the alternate debug info
2038 file found. Otherwise, it emits an error code.
2039 • --no-show-locs
2041 In the emitted ABI representation, do not show file, line or
2042 column where ABI artifacts are defined.
2043 • --no-parameter-names
2045 In the emitted ABI representation, do not show names of function
2047 parameters, just the types.
2048 • --no-write-default-sizes
2050 In the XML ABI representation, do not write the size-in-bits for
2052 pointer type definitions, reference type definitions, function
2053 declarations and function types when they are equal to the default
2054 address size of the translation unit. Note that libabigail before
2055 1.8 will not set the default size and will interpret types without
2056 a size-in-bits attribute as zero sized.
2057 • --type-id-style <sequence``|``hash>
2059 This option controls how types are idenfied in the generated XML
2061 files. The default sequence style just numbers (with type-id- as
2062 prefix) the types in the order they are encountered. The hash
2063 style uses a (stable, portable) hash of libabigail’s internal type
2064 names and is intended to make the XML files easier to diff.
2065 • --check-alternate-debug-info-base-name <elf-path>
2067 Like --check-alternate-debug-info, but in the success message,
2069 only mention the base name of the debug info file; not its full
2070 path.
2071 • --load-all-types
2073 By default, libabigail (and thus abidw) only loads types that are
2075 reachable from functions and variables declarations that are pub‐
2076 licly defined and exported by the binary. So only those types are
2077 present in the output of abidw. This option however makes abidw
2078 load all the types defined in the binaries, even those that are
2079 not reachable from public declarations.
2080 • --abidiff
2082 Load the ABI of the ELF binary given in argument, save it in
2083 libabigail’s XML format in a temporary file; read the ABI from
2084 the temporary XML file and compare the ABI that has been read
2085 back against the ABI of the ELF binary given in argument. The
2086 ABIs should compare equal. If they don’t, the program emits a
2087 diagnostic and exits with a non-zero code.
2088 This is a debugging and sanity check option.
2090 • --debug-abidiff
2092 Same as --abidiff but in debug mode. In this mode, error mes‐
2094 sages are emitted for types which fail type canonicalization.
2095 This is an optional debugging and sanity check option. To en‐
2097 able it the libabigail package needs to be configured with the
2098 –enable-debug-self-comparison option.
2099 • --debug-type-canonicalization | --debug-tc
2101 Debug the type canonicalization process. This is done by using
2103 structural and canonical equality when canonicalizing every sin‐
2104 gle type. Structural and canonical equality should yield the
2105 same result. If they don’t yield the same result for a given
2106 type, then it means that the canonicalization of that type went
2107 wrong. In that case, an error message is emitted and the execu‐
2108 tion of the program is aborted.
2109 This option is available only if the package was configured with
2111 the –enable-debug-type-canonicalization option.
2112 • --no-assume-odr-for-cplusplus
2114 When analysing a binary originating from C++ code using DWARF de‐
2116 bug information, libabigail assumes the One Definition Rule to
2117 speed-up the analysis. In that case, when several types have the
2118 same name in the binary, they are assumed to all be equal.
2119 This option disables that assumption and instructs libabigail to
2121 actually actually compare the types to determine if they are
2122 equal.
2123 • --no-leverage-dwarf-factorization
2125 When analysing a binary which DWARF debug information was pro‐
2127 cessed with the DWZ tool, the type information is supposed to be
2128 already factorized. That context is used by libabigail to perform
2129 some speed optimizations.
2130 This option disables those optimizations.
2132 • --ctf
2134 Extract ABI information from CTF debug information, if present in
2136 the given object.
2137 • --annotate
2139 Annotate the ABIXML output with comments above most elements.
2140 The comments are made of the pretty-printed form types, declara‐
2141 tion or even ELF symbols. The purpose is to make the ABIXML
2142 output more human-readable for debugging or documenting pur‐
2143 poses.
2144 • --stats
2146 Emit statistics about various internal things.
2148 • --verbose
2150 Emit verbose logs about the progress of miscellaneous internal
2152 things.
2153 Usage examples
2155 1. Emitting an ABIXML representation of a binary:
2156 $ abidw binary > binary.abi
2158 2. Emitting an ABIXML representation of a set of binaries specified
2160 on the command line:
2161 $ abidw --added-binaries=bin1,bin2,bin3 \
2163 --added-binaries-dir /some/where \
2164 binary > binaries.abi
2165 Note that the binaries bin1, bin2 and bin3 are to be found in the
2167 directory /some/where. A representation of the ABI of the set of
2168 binaries binary, bin1, bin2 and bin3 called an ABI corpus group
2169 is serialized in the file binaries.abi.
2170 3. Emitting an ABIXML representation of a binary and its dependen‐
2172 cies:
2173 $ abidw --follow-dependencies \
2175 --added-binaries-dir /some/where \
2176 binary > binary.abi
2177 Note that only the dependencies that are found in the directory
2179 /some/where are analysed. Their ABIs, along with the ABI the bi‐
2180 nary named binary are represented as an ABI corpus group and se‐
2181 rialized in the file binary.abi, in the ABIXML format.
2182 Notes
2184 Alternate debug info files
2185 As of the version 4 of the DWARF specification, Alternate debug infor‐
2186 mation is a GNU extension to the DWARF specification. It has however
2187 been proposed for inclusion into the upcoming version 5 of the DWARF
2188 standard. You can read more about the GNU extensions to the DWARF
2189 standard here.
2190 abicompat
2192 abicompat checks that an application that links against a given shared
2193 library is still ABI compatible with a subsequent version of that li‐
2194 brary. If the new version of the library introduces an ABI incompati‐
2195 bility, then abicompat hints the user at what exactly that incompati‐
2196 bility is.
2197 Invocation
2199 abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
2200 Options
2202 • --help
2203 Display a short help about the command and exit.
2205 • –version | -v
2207 Display the version of the program and exit.
2209 • --list-undefined-symbols | -u
2211 Display the list of undefined symbols of the application and exit.
2213 • --show-base-names | -b
2215 In the resulting report emitted by the tool, this option makes the
2217 application and libraries be referred to by their base names only;
2218 not by a full absolute name. This can be useful for use in
2219 scripts that wants to compare names of the application and li‐
2220 braries independently of what their directory names are.
2221 • --app-debug-info-dir | --appd <path-to-app-debug-info-directory>
2223 Set the path to the directory under which the debug information of
2225 the application is supposed to be laid out. This is useful for
2226 application binaries for which the debug info is in a separate set
2227 of files.
2228 • --lib-debug-info-dir1 | --libd1 <path-to-lib1-debug-info>
2230 Set the path to the directory under which the debug information of
2232 the first version of the shared library is supposed to be laid
2233 out. This is useful for shared library binaries for which the de‐
2234 bug info is in a separate set of files.
2235 • --lib-debug-info-dir2 | --libd2 <path-to-lib1-debug-info>
2237 Set the path to the directory under which the debug information of
2239 the second version of the shared library is supposed to be laid
2240 out. This is useful for shared library binaries for which the de‐
2241 bug info is in a separate set of files.
2242 • --suppressions | --suppr <path-to-suppressions>
2244 Use a suppression specification file located at path-to-suppres‐
2246 sions. Note that this option can appear multiple times on the
2247 command line; all the suppression specification files are then
2248 taken into account.
2249 • --no-show-locs
2251 Do not show information about where in the second shared library
2252 the respective type was changed.
2253 • --ctf
2255 When comparing binaries, extract ABI information from CTF debug
2257 information, if present.
2258 • --fail-no-debug-info
2260 If no debug info was found, then this option makes the program to
2262 fail. Otherwise, without this option, the program will attempt to
2263 compare properties of the binaries that are not related to debug
2264 info, like pure ELF properties.
2265 • --ignore-soname
2267 Ignore differences in the SONAME when doing a comparison
2269 • --weak-mode
2271 This triggers the weak mode of abicompat. In this mode, only one
2273 version of the library is required. That is, abicompat is invoked
2274 like this:
2275 abicompat --weak-mode <the-application> <the-library>
2277 Note that the --weak-mode option can even be omitted if only one
2279 version of the library is given, along with the application; in
2280 that case, abicompat automatically switches to operate in weak
2281 mode:
2282 abicompat <the-application> <the-library>
2284 In this weak mode, the types of functions and variables exported
2286 by the library and consumed by the application (as in, the symbols
2287 of the these functions and variables are undefined in the applica‐
2288 tion and are defined and exported by the library) are compared to
2289 the version of these types as expected by the application. And if
2290 these two versions of types are different, abicompat tells the
2291 user what the differences are.
2292 In other words, in this mode, abicompat checks that the types of
2294 the functions and variables exported by the library mean the same
2295 thing as what the application expects, as far as the ABI is con‐
2296 cerned.
2297 Note that in this mode, abicompat doesn’t detect exported func‐
2299 tions or variables (symbols) that are expected by the application
2300 but that are removed from the library. That is why it is called
2301 weak mode.
2302 Return values
2304 The exit code of the abicompat command is either 0 if the ABI of the
2305 binaries being compared are equal, or non-zero if they differ or if the
2306 tool encountered an error.
2307 In the later case, the exit code is a 8-bits-wide bit field in which
2309 each bit has a specific meaning.
2310 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
2312 ror.
2313 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
2315 an error in the way the user invoked the tool. It might be set, for
2316 instance, if the user invoked the tool with an unknown command line
2317 switch, with a wrong number or argument, etc. If this bit is set, then
2318 the ABIDIFF_ERROR bit must be set as well.
2319 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
2321 the binaries being compared are different.
2322 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
2324 the ABI of the binaries compared are different in an incompatible way.
2325 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
2326 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
2327 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
2328 or might not be compatible. In that case, a human being needs to re‐
2329 view the ABI changes to decide if they are compatible or not.
2330 The remaining bits are not used for the moment.
2332 Usage examples
2334 • Detecting a possible ABI incompatibility in a new shared library
2335 version:
2336 $ cat -n test0.h
2338 1 struct foo
2339 2 {
2340 3 int m0;
2341 4
2342 5 foo()
2343 6 : m0()
2344 7 {}
2345 8 };
2346 9
2347 10 foo*
2348 11 first_func();
2349 12
2350 13 void
2351 14 second_func(foo&);
2352 15
2353 16 void
2354 17 third_func();
2355 $
2356 $ cat -n test-app.cc
2358 1 // Compile with:
2359 2 // g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
2360 3
2361 4 #include "test0.h"
2362 5
2363 6 int
2364 7 main()
2365 8 {
2366 9 foo* f = first_func();
2367 10 second_func(*f);
2368 11 return 0;
2369 12 }
2370 $
2371 $ cat -n test0.cc
2373 1 // Compile this with:
2374 2 // g++ -g -Wall -shared -o libtest-0.so test0.cc
2375 3
2376 4 #include "test0.h"
2377 5
2378 6 foo*
2379 7 first_func()
2380 8 {
2381 9 foo* f = new foo();
2382 10 return f;
2383 11 }
2384 12
2385 13 void
2386 14 second_func(foo&)
2387 15 {
2388 16 }
2389 17
2390 18 void
2391 19 third_func()
2392 20 {
2393 21 }
2394 $
2395 $ cat -n test1.h
2397 1 struct foo
2398 2 {
2399 3 int m0;
2400 4 char m1; /* <-- a new member got added here! */
2401 5
2402 6 foo()
2403 7 : m0(),
2404 8 m1()
2405 9 {}
2406 10 };
2407 11
2408 12 foo*
2409 13 first_func();
2410 14
2411 15 void
2412 16 second_func(foo&);
2413 17
2414 18 void
2415 19 third_func();
2416 $
2417 $ cat -n test1.cc
2419 1 // Compile this with:
2420 2 // g++ -g -Wall -shared -o libtest-1.so test1.cc
2421 3
2422 4 #include "test1.h"
2423 5
2424 6 foo*
2425 7 first_func()
2426 8 {
2427 9 foo* f = new foo();
2428 10 return f;
2429 11 }
2430 12
2431 13 void
2432 14 second_func(foo&)
2433 15 {
2434 16 }
2435 17
2436 18 /* Let's comment out the definition of third_func()
2437 19 void
2438 20 third_func()
2439 21 {
2440 22 }
2441 23 */
2442 $
2443 • Compile the first and second versions of the libraries:
2445 libtest-0.so and libtest-1.so:
2446 $ g++ -g -Wall -shared -o libtest-0.so test0.cc
2448 $ g++ -g -Wall -shared -o libtest-1.so test1.cc
2449 • Compile the application and link it against the first version of
2451 the library, creating the test-app binary:
2452 $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
2454 • Now, use abicompat to see if libtest-1.so is ABI compatible with
2456 app, with respect to the ABI of libtest-0.so:
2457 $ abicompat test-app libtest-0.so libtest-1.so
2459 ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
2460 Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
2461 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
2462 2 functions with some indirect sub-type change:
2464 [C]'function foo* first_func()' has some indirect sub-type changes:
2466 return type changed:
2467 in pointed to type 'struct foo':
2468 size changed from 32 to 64 bits
2469 1 data member insertion:
2470 'char foo::m1', at offset 32 (in bits)
2471 [C]'function void second_func(foo&)' has some indirect sub-type changes:
2472 parameter 0 of type 'foo&' has sub-type changes:
2473 referenced type 'struct foo' changed, as reported earlier
2474 $
2476 • Now use the weak mode of abicompat, that is, providing just the
2478 application and the new version of the library:
2479 $ abicompat --weak-mode test-app libtest-1.so
2481 functions defined in library
2482 'libtest-1.so'
2483 have sub-types that are different from what application
2484 'test-app'
2485 expects:
2486 function foo* first_func():
2488 return type changed:
2489 in pointed to type 'struct foo':
2490 size changed from 32 to 64 bits
2491 1 data member insertion:
2492 'char foo::m1', at offset 32 (in bits)
2493 $
2495 abilint
2497 abilint parses the native XML representation of an ABI as emitted by
2498 abidw. Once it has parsed the XML representation of the ABI, abilint
2499 builds and in-memory model from it. It then tries to save it back to
2500 an XML form, to standard output. If that read-write operation succeeds
2501 chances are the input XML ABI representation is meaningful.
2502 Note that the main intent of this tool to help debugging issues in the
2504 underlying Libabigail library.
2505 Note also that abilint can also read an ELF input file, build the
2507 in-memory model for its ABI, and serialize that model back into XML to
2508 standard output. In that case, the ELF input file must be accompanied
2509 with its debug information in the DWARF format.
2510 Invocation
2512 abilint [options] [<abi-file1>]
2513 Options
2515 • --help
2516 Display a short help message and exits.
2518 • –version | -v
2520 Display the version of the program and exit.
2522 • --debug-info-dir <path>
2524 When reading an ELF input file which debug information is split
2526 out into a separate file, this options tells abilint where to find
2527 that separate debug information file.
2528 Note that path must point to the root directory under which the
2530 debug information is arranged in a tree-like manner. Under Red
2531 Hat based systems, that directory is usually <root>/usr/lib/debug.
2532 Note also that this option is not mandatory for split debug infor‐
2534 mation installed by your system’s package manager because then
2535 abidiff knows where to find it.
2536 • --diff
2538 For XML inputs, perform a text diff between the input and the mem‐
2540 ory model saved back to disk. This can help to spot issues in the
2541 handling of the XML format by the underlying Libabigail library.
2542 • --noout
2544 Do not display anything on standard output. The return code of
2546 the command is the only way to know if the command succeeded.
2547 • --suppressions | suppr <path-to-suppression-specifications-file>
2549 Use a suppression specification file located at path-to-suppres‐
2551 sion-specifications-file. Note that this option can appear multi‐
2552 ple times on the command line. In that case, all of the provided
2553 suppression specification files are taken into account. ABI arti‐
2554 facts matched by the suppression specifications are suppressed
2555 from the output of this tool.
2556 • --headers-dir | --hd <headers-directory-path-1>
2558 Specifies where to find the public headers of the first shared li‐
2560 brary that the tool has to consider. The tool will thus filter
2561 out types that are not defined in public headers.
2562 • --header-file | --hf <header-file-path>
2564 Specifies where to find one of the public headers of the abi file
2566 that the tool has to consider. The tool will thus filter out
2567 types that are not defined in public headers.
2568 • --stdin | --
2570 Read the input content from standard input.
2572 • --tu
2574 Expect the input XML to represent a single translation unit.
2576 • --ctf
2578 Extract ABI information from CTF debug information, if present in
2580 the given object.
2581 fedabipkgdiff
2583 fedabipkgdiff compares the ABI of shared libraries in Fedora packages.
2584 It’s a convenient way to do so without having to manually download
2585 packages from the Fedora Build System.
2586 fedabipkgdiff knows how to talk with the Fedora Build System to find
2588 the right packages versions, their associated debug information and de‐
2589 velopment packages, download them, compare their ABI locally, and re‐
2590 port about the possible ABI changes.
2591 Note that by default, this tool reports ABI changes about types that
2593 are defined in public header files found in the development packages
2594 associated with the packages being compared. It also reports ABI
2595 changes about functions and global variables whose symbols are defined
2596 and exported in the ELF binaries found in the packages being compared.
2597 Invocation
2599 fedabipkgdiff [option] <NVR> ...
2600 Environment
2602 fedabipkgdiff loads two default suppression specifications files,
2603 merges their content and use it to filter out ABI change reports that
2604 might be considered as false positives to users.
2605 • Default system-wide suppression specification file
2607 It’s located by the optional environment variable LIBABIGAIL_DE‐
2609 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
2610 set, then fedabipkgdiff tries to load the suppression file $lib‐
2611 dir/libabigail/libabigail-default.abignore. If that file is not
2612 present, then no default system-wide suppression specification file
2613 is loaded.
2614 • Default user suppression specification file.
2616 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
2618 PRESSION_FILE. If that environment variable is not set, then fed‐
2619 abipkgdiff tries to load the suppression file $HOME/.abignore. If
2620 that file is not present, then no default user suppression specifica‐
2621 tion is loaded.
2622 Options
2624 • --help | -h
2625 Display a short help about the command and exit.
2627 • --dry-run
2629 Don’t actually perform the ABI comparison. Details about what is
2631 going to be done are emitted on standard output.
2632 • --debug
2634 Emit debugging messages about the execution of the program. De‐
2636 tails about each method invocation, including input parameters and
2637 returned values, are emitted.
2638 • --traceback
2640 Show traceback when an exception raised. This is useful for devel‐
2642 opers of the tool itself to know more exceptional errors.
2643 • --server <URL>
2645 Specifies the URL of the Koji XMLRPC service the tool talks to.
2647 The default value of this option is
2648 http://koji.fedoraproject.org/kojihub.
2649 • --topurl <URL>
2651 Specifies the URL of the package store the tool downloads RPMs
2653 from. The default value of this option is
2654 https://kojipkgs.fedoraproject.org.
2655 • --from <distro>
2657 Specifies the name of the baseline Fedora distribution in which to
2659 find the first build that is used for comparison. The distro value
2660 can be any valid value of the RPM macro %{?dist} for Fedora, for
2661 example, fc4, fc23, fc25.
2662 • --to <distro>
2664 Specifies the name of the Fedora distribution in which to find the
2666 build that is compared against the baseline specified by option
2667 --from. The distro value could be any valid value of the RPM
2668 macro %{?dist} for Fedora, for example, fc4, fc23.
2669 • --all-subpackages
2671 Instructs the tool to also compare the ABI of the binaries in the
2673 sub-packages of the packages specified.
2674 • --dso-only
2676 Compares the ABI of shared libraries only. If this option is not
2678 provided, the tool compares the ABI of all ELF binaries found in
2679 the packages.
2680 • --suppressions <path-to-suppresions>
2682 Use a suppression specification file located at path-to-suppres‐
2684 sions.
2685 • --no-default-suppression
2687 Do not load the default suppression specification files.
2689 • --no-devel-pkg
2691 Do not take associated development packages into account when per‐
2693 forming the ABI comparison. This makes the tool report ABI
2694 changes about all types that are reachable from functions and
2695 global variables which symbols are defined and publicly exported
2696 in the binaries being compared, even if those types are not de‐
2697 fined in public header files available from the packages being
2698 compared.
2699 • --show-identical-binaries
2701 Show the names of the all binaries compared, including the bina‐
2702 ries whose ABI compare equal. By default, when this option is
2703 not provided, only binaries with ABI changes are mentionned in
2704 the output.
2705 • --abipkgdiff <path/to/abipkgdiff>
2707 Specify an alternative abipkgdiff instead of the one installed in
2709 system.
2710 • --clean-cache-before
2712 Clean cache before ABI comparison.
2714 • --clean-cache-after
2716 Clean cache after ABI comparison.
2718 • --clean-cache
2720 If you want to clean cache both before and after ABI comparison,
2722 --clean-cache is the convenient way for you to save typing of two
2723 options at same time.
2724 Note that a build is a specific version and release of an RPM package.
2726 It’s specified by its the package name, version and release. These are
2727 specified by the Fedora Naming Guidelines
2728 Return value
2730 The exit code of the abipkgdiff command is either 0 if the ABI of the
2731 binaries compared are equivalent, or non-zero if they differ or if the
2732 tool encountered an error.
2733 In the later case, the value of the exit code is the same as for the
2735 abidiff tool.
2736 Use cases
2738 Below are some usage examples currently supported by fedabipkgdiff.
2739 1. Compare the ABI of binaries in a local package against the ABI of
2741 the latest stable package in Fedora 23.
2742 Suppose you have built just built the httpd package and you want
2744 to compare the ABI of the binaries in this locally built package
2745 against the ABI of the binaries in the latest http build from
2746 Fedora 23. The command line invocation would be:
2747 $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
2749 2. Compare the ABI of binaries in two local packages.
2751 Suppose you have built two versions of package httpd, and you
2753 want to see what ABI differences between these two versions of
2754 RPM files. The command line invocation would be:
2755 $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
2757 All what fedabipkgdiff does happens on local machine without the
2759 need of querying or downloading RPMs from Koji.
2760 3. Compare the ABI of binaries in the latest build of the httpd
2762 package in Fedora 23 against the ABI of the binaries in the lat‐
2763 est build of the same package in 24.
2764 In this case, note that neither of the two packages are available
2766 locally. The tool is going to talk with the Fedora Build System,
2767 determine what the versions and releases of the latest packages
2768 are, download them and perform the comparison locally. The com‐
2769 mand line invocation would be:
2770 $ fedabipkgdiff --from fc23 --to fc24 httpd
2772 4. Compare the ABI of binaries of two builds of the httpd package,
2774 designated their versions and releases.
2775 If we want to do perform the ABI comparison for all the processor
2777 architectures supported by Fedora the command line invocation
2778 would be:
2779 $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
2781 But if we want to perform the ABI comparison for a specific ar‐
2783 chitecture, say, x86_64, then the command line invocation would
2784 be:
2785 $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
2787 5. If the use wants to also compare the sub-packages of a given
2789 package, she can use the –all-subpackages option. The first com‐
2790 mand of the previous example would thus look like:
2791 $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
2793
2795 ABI artifacts
2796 An ABI artifact is a relevant part of the ABI of a shared library or
2797 program. Examples of ABI artifacts are exported types, variables,
2798 functions, or ELF symbols exported by a shared library.
2799 The set of ABI artifact for a binary is called an ABI Corpus.
2801 Harmful changes
2803 A change in the diff report is considered harmful if it might cause ABI
2804 compatibility issues. That is, it might prevent an application dynami‐
2805 cally linked against a given version of a library to keep working with
2806 the changed subsequent versions of the same library.
2807 Harmless changes
2809 A change in the diff report is considered harmless if it will not cause
2810 any ABI compatibility issue. That is, it will not prevent an applica‐
2811 tion dynamically linked against given version of a library to keep
2812 working with the changed subsequent versions of the same library.
2813 By default, abidiff filters harmless changes from the diff report.
2815 Suppression specifications
2817 Definition
2818 A suppression specification file is a way for a user to instruct
2819 abidiff, abipkgdiff or any other relevant libabigail tool to avoid
2820 emitting reports for changes involving certain ABI artifacts.
2821 It contains directives (or specifications) that describe the set of ABI
2823 artifacts to avoid emitting change reports about.
2824 Introductory examples
2826 Its syntax is based on a simplified and customized form of Ini File
2827 Syntax. For instance, to specify that change reports on a type named
2828 FooPrivateType should be suppressed, one could write this suppression
2829 specification:
2830 [suppress_type]
2832 name = FooPrivateType
2833 If we want to ensure that only change reports about structures named
2835 FooPrivateType should be suppressed, we could write:
2836 [suppress_type]
2838 type_kind = struct
2839 name = FooPrivateType
2840 But we could also want to suppress change reports avoid typedefs named
2842 FooPrivateType. In that case we would write:
2843 [suppress_type]
2845 type_kind = typedef
2846 name = FooPrivateType
2847 Or, we could want to suppress change reports about all struct which
2849 names end with the string “PrivateType”:
2850 [suppress_type]
2852 type_kind = struct
2853 name_regexp = ^.*PrivateType
2854 Let’s now look at the generic syntax of suppression specification
2856 files.
2857 Syntax
2859 Properties
2860 More generally, the format of suppression lists is organized around the
2861 concept of property. Every property has a name and a value, delimited
2862 by the = sign. E.g:
2863 name = value
2865 Leading and trailing white spaces are ignored around property names and
2867 values.
2868 Regular expressions
2870 The value of some properties might be a regular expression. In that
2871 case, they must comply with the syntax of extended POSIX regular ex‐
2872 pressions. Note that Libabigail uses the regular expression engine of
2873 the GNU C Library.
2874 Escaping a character in a regular expression
2876 When trying to match a string that contains a * character, like in the
2877 pointer type int*, one must be careful to notice that the character *
2878 is a special character in the extended POSIX regular expression syntax.
2879 And that character must be escaped for the regular expression engine.
2880 Thus the regular expression that would match the string int* in a sup‐
2881 pression file should be
2882 int\\*
2884 Wait; but then why the two \ characters? Well, because the \ character
2886 is a special character in the Ini File Syntax used for specifying sup‐
2887 pressions. So it must be escaped as well, so that the Ini File parser
2888 leaves a \ character intact in the data stream that is handed to the
2889 regular expression engine. Hence the \\ targeted at the Ini File
2890 parser.
2891 So, in short, to escape a character in a regular expression, always
2893 prefix the character with the \\ sequence.
2894 Modus operandi
2896 Suppression specifications can be applied at two different points of
2897 the processing pipeline of libabigail.
2898 In the default operating mode called “late suppression mode”, suppres‐
2900 sion specifications are applied to the result of comparing the in-mem‐
2901 ory internal representations of two ABIs. In this mode, if an ABI ar‐
2902 tifact matches a suppression specification, its changes are not men‐
2903 tioned in the ABI change report. The internal representation of the
2904 “suppressed” changed ABI artifact is still present in memory; it is
2905 just not mentioned in the ABI change report. The change report can
2906 still mention statistics about the number of changed ABI artifacts that
2907 were suppressed.
2908 There is another operating mode called the “early suppression mode”
2910 where suppression specifications are applied during the construction of
2911 the in-memory internal representation of a given ABI. In that mode, if
2912 an ABI artifact matches a suppression specification, no in-memory in‐
2913 ternal representation is built for it. As a result, no change about
2914 the matched ABI artifact is going to be mentioned in the ABI change re‐
2915 port and no statistic about the number of suppressed ABI changes is
2916 available. Also, please note that because suppressed ABI artifacts are
2917 removed from the in-memory internal representation in this mode, the
2918 amount memory used by the internal representation is potentially
2919 smaller than the memory consumption in the late suppression mode.
2920 Sections
2922 Properties are then grouped into arbitrarily named sections that shall
2923 not be nested. The name of the section is on a line by itself and is
2924 surrounded by square brackets, i.e:
2925 [section_name]
2927 property1_name = property1_value
2928 property2_name = property2_value
2929 A section might or might not have properties. Sections that expect to
2931 have properties and which are found nonetheless empty are just ignored.
2932 Properties that are not recognized by the reader are ignored as well.
2933 Section names
2935 Each different section can be thought of as being a directive to sup‐
2936 press ABI change reports for a particular kind of ABI artifact.
2937 [suppress_file]
2939 This directive prevents a given tool from loading a file (binary or
2940 abixml file) if its file name or other properties match certain proper‐
2941 ties. Thus, if the tool is meant to compare the ABIs of two files, and
2942 if the directive prevents it from loading either one of the files, then
2943 no comparison is performed.
2944 Note that for the [suppress_file] directive to work, at least one of
2946 the following properties must be provided:
2947 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
2948 ame_not_regexp.
2949 If none of the above properties are provided, then the [suppress_file]
2951 directive is simply ignored.
2952 The potential properties of this sections are listed below:
2954 • file_name_not_regexp
2956 Usage:
2958 file_name_not_regexp = <regular-expression>
2959 Prevents the system from loading the file which name does not match
2961 the regular expression specified as value of this property.
2962 • file_name_regexp
2964 Usage:
2966 file_name_regexp = <regular-expression>
2967 Prevents the system from loading the file which name matches the reg‐
2969 ular expression specified as value of this property.
2970 • label
2972 Usage:
2973 label = <some-value>
2974 Define a label for the section. A label is just an informative
2976 string that might be used by the tool to refer to a type suppression
2977 in error messages.
2978 • soname_regexp
2980 Usage:
2982 soname_regexp = <regular-expression>
2983 Prevents the system from loading the file which contains a SONAME
2985 property that matches the regular expression of this property. Note
2986 that this property also works on an abixml file if it contains a SON‐
2987 AME property.
2988 • soname_not_regexp
2990 Usage:
2992 soname_not_regexp = <regular-expression>
2993 Prevents the system from loading the file which contains a SONAME
2995 property that does NOT match the regular expression of this property.
2996 Note that this property also works on an abixml file if it contains a
2997 SONAME property.
2998 [suppress_type]
3000 This directive suppresses report messages about a type change.
3001 Note that for the [suppress_type] directive to work, at least one of
3003 the following properties must be provided:
3004 file_name_regexp, file_name_not_regexp, soname_regexp, son‐
3005 ame_not_regexp, name, name_regexp, name_not_regexp, source_loca‐
3006 tion_not_in, source_location_not_regexp, type_kind.
3007 If none of the above properties are provided, then the [suppress_type]
3009 directive is simply ignored.
3010 The potential properties of this sections are listed below:
3012 • accessed_through
3014 Usage:
3015 accessed_through = <some-predefined-values>
3016 Suppress change reports involving a type which is referred to either
3018 directly or through a pointer or a reference. The potential values
3019 of this property are the predefined keywords below:
3020 • direct
3022 So if the [suppress_type] contains the property description:
3024 accessed_through = direct
3026 then changes about a type that is referred-to directly (i.e,
3028 not through a pointer or a reference) are going to be sup‐
3029 pressed.
3030 • pointer
3032 If the accessed_through property is set to the value pointer
3034 then changes about a type that is referred-to through a
3035 pointer are going to be suppressed.
3036 • reference
3038 If the accessed_through property is set to the value reference
3040 then changes about a type that is referred-to through a refer‐
3041 ence are going to be suppressed.
3042 • reference-or-pointer
3044 If the accessed_through property is set to the value refer‐
3046 ence-or-pointer then changes about a type that is referred-to
3047 through either a reference or a pointer are going to be sup‐
3048 pressed.
3049 For an extensive example of how to use this property, please check
3051 out the example below about suppressing change reports about types
3052 accessed either directly or through pointers.
3053 • changed_enumerators
3055 Usage:
3057 changed_enumerators = <list-of-enumerators>
3058 Suppresses change reports involving changes in the value of enumera‐
3060 tors of a given enum type. This property is applied if the type_kind
3061 property is set to the value enum, at least. The value of the
3062 changed_enumerators is a comma-separated list of the enumerators that
3063 the user expects to change. For instance:
3064 changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1
3066 • changed_enumerators_regexp
3068 Usage:
3070 changed_enumerators_regexp = <list-of-enumerator-regular-expres‐
3071 sions>
3072 Suppresses change reports involving changes in the value of enumera‐
3074 tors of a given enum type. This property is applied if the type_kind
3075 property is set to the value enum, at least. The value of the
3076 changed_enumerators_regexp property is a comma-separated list of reg‐
3077 ular expressions that should match the names of the enumerators that
3078 the user expects to change. For instance:
3079 changed_enumerators_regexp = .*_MAX$, .*_LAST$, .*_NUM$, .*_NBITS$
3081 In the example above, change reports to any enumerator which name
3083 ends with _MAX, _LAST, _NUM or _NBITS will be suppressed.
3084 Note that for this property to be applied to changes to an enum type,
3086 the size of the enum type must NOT have changed.
3087 • drop
3089 Usage:
3090 drop = yes | no
3091 If a type is matched by a suppression specification which contains
3093 the “drop” property set to “yes” (or to “true”) then the type is not
3094 even going to be represented in the internal representation of the
3095 ABI being analyzed. This property makes its enclosing suppression
3096 specification to be applied in the early suppression specification
3097 mode. The net effect is that it potentially reduces the memory used
3098 to represent the ABI being analyzed.
3099 Please note that for this property to be effective, the enclosing
3101 suppression specification must have at least one of the following
3102 properties specified: name_regexp, name, name_regexp, source_loca‐
3103 tion_not_in or source_location_not_regexp.
3104 • file_name_not_regexp
3106 Usage:
3108 file_name_not_regexp = <regular-expression>
3109 Suppresses change reports about ABI artifacts that are defined in a
3111 binary file which name does not match the regular expression speci‐
3112 fied as value of this property.
3113 • file_name_regexp
3115 Usage:
3117 file_name_regexp = <regular-expression>
3118 Suppresses change reports about ABI artifacts that are defined in a
3120 binary file which name matches the regular expression specified as
3121 value of this property.
3122 • has_data_member
3124 Usage:
3126 has_data_member = <list-of-data-member-names>
3127 Suppresses change reports involving a type which contains data members
3129 whose names are provided in the list value of this property.
3130 A usage examples of this property would be:
3132 has_data_member = {private_data_member0, private_data_member1}
3134 The property above would match any type which contains at least two
3136 data members whose names are private_data_member0 and private_data_mem‐
3137 ber1.
3138 Another usage examples of this property would be:
3140 has_data_member = another_private_data_member
3142 The property above would match any type which contains a data member
3144 which name is another_private_data_member0.
3145 • has_data_member_regexp
3147 Usage:
3149 has_data_member_regexp = <a-regular-expression>
3150 Suppresses change reports involving a type which contains data members
3152 whose names match the regular expression provided as the value of this
3153 property.
3154 A usage examples of this property would be:
3156 has_data_member_regexp = ^private_data_member
3158 The property above would match any type which contains data members
3160 whose names match the regular expression ^private_data_member. In
3161 other words, it would match any type which contains data members whose
3162 names start with the string “private_data_member”.
3163 • has_data_member_inserted_at
3165 Usage:
3166 has_data_member_inserted_at = <offset-in-bit>
3167 Suppresses change reports involving a type which has at least one
3169 data member inserted at an offset specified by the property value
3170 offset-in-bit. Please note that if the size of the type changed,
3171 then the type change will NOT be suppressed by the evaluation of
3172 this property, unless the has_size_change property is present and
3173 set to yes.
3174 The value offset-in-bit is either:
3176 • an integer value, expressed in bits, which denotes the offset
3178 of the insertion point of the data member, starting from the
3179 beginning of the relevant structure or class.
3180 • data member offset selector expressions, such as:
3182 • the keyword end which is a named constant which value
3184 equals the offset of the end of the structure or class.
3185 • the keyword offset_of_flexible_array_data_member which is
3187 a named constant that evaluates to the offset of the
3188 flexible array data member contained in the relevant
3189 structure.
3190 • the function call expression offset_of(data-member-name)
3192 where data-member-name is the name of a given data member
3193 of the relevant structure or class. The value of this
3194 function call expression is an integer that represents
3195 the offset of the data member denoted by data-mem‐
3196 ber-name.
3197 • the function call expression offset_after(data-mem‐
3199 ber-name) where data-member-name is the name of a given
3200 data member of the relevant structure or class. The
3201 value of this function call expression is an integer that
3202 represents the offset of the point that comes right after
3203 the region occupied by the data member denoted by
3204 data-member-name.
3205 • the function call expression offset_of_first_data_mem‐
3207 ber_regexp(data-member-name-regexp) where data-mem‐
3208 ber-name-regexp is a regular expression matching a data
3209 member. The value of this function call expression is an
3210 integer that represents the offset of the first data mem‐
3211 ber which name matches the regular expression argument.
3212 If no data member of a given class type matches the regu‐
3213 lar expression, then the class type won’t match the cur‐
3214 rent directive.
3215 • the function call expression offset_of_last_data_mem‐
3217 ber_regexp(data-member-name-regexp) where data-mem‐
3218 ber-name-regexp is a regular expression matching a data
3219 member. The value of this function call expression is an
3220 integer that represents the offset of the last data mem‐
3221 ber which name matches the regular expression argument.
3222 If no data member of a given class type matches the regu‐
3223 lar expression, then the class type won’t match the cur‐
3224 rent directive.
3225 • has_data_member_inserted_between
3227 Usage:
3228 has_data_member_inserted_between = {<range-begin>, <range-end>}
3229 Suppresses change reports involving a type which has at least one
3231 data member inserted at an offset that is comprised in the range be‐
3232 tween range-begin and range-end. Please note that each of the val‐
3233 ues range-begin and range-end can be of the same form as the
3234 has_data_member_inserted_at property above. Please also note that
3235 if the size of the type changed, then the type change will NOT be
3236 suppressed by the evaluation of this property, unless the
3237 has_size_change property is present and set to yes. Note that data
3238 member deletions happening in the range between range-begin and
3239 range-end won’t prevent the type change from being suppressed by the
3240 evaluation of this property if the size of the type doesn’t change
3241 or if the has_size_change property is present and set to yes.
3242 Usage examples of this properties are:
3244 has_data_member_inserted_between = {8, 64}
3246 or:
3248 has_data_member_inserted_between = {16, end}
3250 or:
3252 has_data_member_inserted_between = {offset_after(member1), end}
3254 • has_data_members_inserted_between
3256 Usage:
3257 has_data_members_inserted_between = {<sequence-of-ranges>}
3258 Suppresses change reports involving a type which has multiple data
3260 member inserted in various offset ranges. A usage example of this
3261 property is, for instance:
3262 has_data_members_inserted_between = {{8, 31}, {72, 95}}
3264 This usage example suppresses change reports involving a type which
3266 has data members inserted in bit offset ranges [8 31] and [72 95].
3267 The length of the sequence of ranges or this has_data_members_in‐
3268 serted_between is not bounded; it can be as long as the system can
3269 cope with. The values of the boundaries of the ranges are of the
3270 same kind as for the has_data_member_inserted_at property above.
3271 Please also note that if the size of the type changed, then the type
3272 will NOT be suppressed by the evaluation of this property, unless
3273 the has_size_change property is present and set to yes. Note that
3274 data member deletions happening in the defined ranges won’t prevent
3275 the type change from being suppressed by the evaluation of this
3276 property if the size of the type doesn’t change or if the
3277 has_size_change property is present and set to yes.
3278 Another usage example of this property is thus:
3280 has_data_members_inserted_between =
3282 {
3283 {offset_after(member0), offset_of(member1)},
3284 {72, end}
3285 }
3286 • has_strict_flexible_array_data_member_conversion
3288 Usage:
3289 has_strict_flexible_array_data_member_conversion = yes | no
3290 Suppresses change reports involving a type which has a “fake” flexi‐
3292 ble array member at the end of the struct which is converted to a
3293 real flexible array member. This would be a member like data[1] be‐
3294 ing converted to data[].
3295 Please note that if the size of the type changed, then the type
3297 change will NOT be suppressed by the evaluation of this property,
3298 unless the has_size_change property is present and set to yes.
3299 • has_size_change
3301 Usage:
3302 has_size_change = yes | no
3303 This property is to be used in conjunction with the properties
3305 has_data_member_inserted_between, has_data_members_inserted_between,
3306 and has_strict_flexible_array_data_member_conversion Those properties
3307 will not match a type change if the size of the type changes, unless
3308 the has_size_changes property is set to yes.
3309 • label
3311 Usage:
3312 label = <some-value>
3313 Define a label for the section. A label is just an informative
3315 string that might be used by a tool to refer to a type suppression
3316 in error messages.
3317 • name
3319 Usage:
3320 name = <a-value>
3321 Suppresses change reports involving types whose name equals the
3323 value of this property.
3324 • name_not_regexp
3326 Usage:
3327 name_not_regexp = <regular-expression>
3328 Suppresses change reports involving types whose name does NOT match
3330 the regular expression specified as value of this property. Said
3331 otherwise, this property specifies which types to keep, rather than
3332 types to suppress from reports.
3333 • name_regexp
3335 Usage:
3336 name_regexp = <regular-expression>
3337 Suppresses change reports involving types whose name matches the
3339 regular expression specified as value of this property.
3340 • soname_not_regexp
3342 Usage:
3344 soname_not_regexp = <regular-expression>
3345 Suppresses change reports about ABI artifacts that are defined in a
3347 shared library which SONAME property does not match the regular ex‐
3348 pression specified as value of this property.
3349 • soname_regexp
3351 Usage:
3353 soname_regexp = <regular-expression>
3354 Suppresses change reports about ABI artifacts that are defined in a
3356 shared library which SONAME property matches the regular expression
3357 specified as value of this property.
3358 • source_location_not_in
3360 Usage:
3361 source_location_not_in = <list-of-file-paths>
3362 Suppresses change reports involving a type which is defined in a
3364 file which path is NOT listed in the value list-of-file-paths. Note
3365 that the value is a comma-separated list of file paths e.g, this
3366 property
3367 source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h
3369 suppresses change reports about all the types that are NOT defined
3371 in header files whose path end up with the strings libabi‐
3372 gail/abg-ir.h or libabigail/abg-dwarf-reader.h.
3373 • source_location_not_regexp
3375 Usage:
3376 source_location_not_regexp = <regular-expression>
3377 Suppresses change reports involving a type which is defined in a
3379 file which path does NOT match the regular expression provided as
3380 value of the property. E.g, this property
3381 source_location_not_regexp = libabigail/abg-.*\\.h
3383 suppresses change reports involving all the types that are NOT de‐
3385 fined in header files whose path match the regular expression pro‐
3386 vided a value of the property.
3387 • type_kind
3389 Usage:
3390 type_kind = class | struct | union | enum |
3392 array | typedef | builtin
3393 Suppresses change reports involving a certain kind of type. The
3395 kind of type to suppress change reports for is specified by the pos‐
3396 sible values listed above:
3397 •
3399 class: suppress change reports for class types. Note that
3401 even if class types don’t exist for C, this value still
3402 triggers the suppression of change reports for struct
3403 types, in C. In C++ however, it should do what it sug‐
3404 gests.
3405 •
3407 struct: suppress change reports for struct types in C or C++.
3409 Note that the value class above is a super-set of this
3410 one.
3411 • union: suppress change reports for union types.
3413 • enum: suppress change reports for enum types.
3415 • array: suppress change reports for array types.
3417 • typedef: suppress change reports for typedef types.
3419 • builtin: suppress change reports for built-in (or native)
3421 types. Example of built-in types are char, int, unsigned int,
3422 etc.
3423 [suppress_function]
3425 This directive suppresses report messages about changes on a set of
3426 functions.
3427 Note that for the [suppress_function] directive to work, at least one
3429 of the following properties must be provided:
3430 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
3431 ame_not_regexp, name, name_regexp, name_not_regexp, parameter, re‐
3432 turn_type_name, return_type_regexp, symbol_name, symbol_name_regexp,
3433 symbol_name_not_regexp, symbol_version, symbol_version_regexp.
3434 If none of the above properties are provided, then the [suppress_func‐
3436 tion] directive is simply ignored.
3437 The potential properties of this sections are:
3439 • change_kind
3441 Usage:
3442 change_kind = <predefined-possible-values>
3443 Specifies the kind of changes this suppression specification should
3445 apply to. The possible values of this property as well as their
3446 meaning are listed below:
3447 • function-subtype-change
3449 This suppression specification applies to functions that which
3451 have at least one sub-type that has changed.
3452 • added-function
3454 This suppression specification applies to functions that have
3456 been added to the binary.
3457 • deleted-function
3459 This suppression specification applies to functions that have
3461 been removed from the binary.
3462 • all
3464 This suppression specification applies to functions that have
3466 all of the changes above. Note that not providing the
3467 change_kind property at all is equivalent to setting it to the
3468 value all.
3469 • drop
3471 Usage:
3472 drop = yes | no
3473 If a function is matched by a suppression specification which con‐
3475 tains the “drop” property set to “yes” (or to “true”) then the func‐
3476 tion is not even going to be represented in the internal representa‐
3477 tion of the ABI being analyzed. This property makes its enclosing
3478 suppression specification to be applied in the early suppression
3479 specification mode. The net effect is that it potentially reduces
3480 the memory used to represent the ABI being analyzed.
3481 Please note that for this property to be effective, the enclosing
3483 suppression specification must have at least one of the following
3484 properties specified: name_regexp, name, name_regexp, source_loca‐
3485 tion_not_in or source_location_not_regexp.
3486 • file_name_not_regexp
3488 Usage:
3490 file_name_not_regexp = <regular-expression>
3491 Suppresses change reports about ABI artifacts that are defined in a
3493 binary file which name does not match the regular expression speci‐
3494 fied as value of this property.
3495 • file_name_regexp
3497 Usage:
3499 file_name_regexp = <regular-expression>
3501 Suppresses change reports about ABI artifacts that are defined in a
3503 binary file which name matches the regular expression specified as
3504 value of this property.
3505 • label
3507 Usage:
3508 label = <some-value>
3509 This property is the same as the label property defined above.
3511 • name
3513 Usage:
3514 name = <some-value>
3515 Suppresses change reports involving functions whose name equals the
3517 value of this property.
3518 • name_not_regexp
3520 Usage:
3521 name_not_regexp = <regular-expression>
3522 Suppresses change reports involving functions whose names don’t
3524 match the regular expression specified as value of this property.
3525 The rules for functions that have several symbol names are the same
3527 rules as for the name_regexp property above.
3528 • name_regexp
3530 Usage:
3531 name_regexp = <regular-expression>
3532 Suppresses change reports involving functions whose name matches the
3534 regular expression specified as value of this property.
3535 Let’s consider the case of functions that have several symbol names.
3537 This happens when the underlying symbol for the function has
3538 aliases. Each symbol name is actually one alias name.
3539 In this case, if the regular expression matches the name of at least
3541 one of the aliases names, then it must match the names of all of the
3542 aliases of the function for the directive to actually suppress the
3543 diff reports for said function.
3544 • parameter
3546 Usage:
3547 parameter = <function-parameter-specification>
3548 Suppresses change reports involving functions whose parameters match
3550 the parameter specification indicated as value of this property.
3551 The format of the function parameter specification is:
3553 ' <parameter-index> <space> <type-name-or-regular-expression>
3555 That is, an apostrophe followed by a number that is the index of the
3557 parameter, followed by one of several spaces, followed by either the
3558 name of the type of the parameter, or a regular expression describ‐
3559 ing a family of parameter type names.
3560 If the parameter type name is designated by a regular expression,
3562 then said regular expression must be enclosed between two slashes;
3563 like /some-regular-expression/.
3564 The index of the first parameter of the function is zero. Note that
3566 for member functions (methods of classes), the this is the first pa‐
3567 rameter that comes after the implicit “this” pointer parameter.
3568 Examples of function parameter specifications are:
3570 '0 int
3572 Which means, the parameter at index 0, whose type name is int.
3574 '4 unsigned char*
3576 Which means, the parameter at index 4, whose type name is unsigned
3578 char*.
3579 '2 /^foo.*&/
3581 Which means, the parameter at index 2, whose type name starts with
3583 the string “foo” and ends with an ‘&’. In other words, this is the
3584 third parameter and it’s a reference on a type that starts with the
3585 string “foo”.
3586 • return_type_name
3588 Usage:
3589 return_type_name = <some-value>
3590 Suppresses change reports involving functions whose return type name
3592 equals the value of this property.
3593 • return_type_regexp
3595 Usage:
3596 return_type_regexp = <regular-expression>
3597 Suppresses change reports involving functions whose return type name
3599 matches the regular expression specified as value of this property.
3600 • soname_regexp
3602 Usage:
3604 soname_regexp = <regular-expression>
3605 Suppresses change reports about ABI artifacts that are defined in a
3607 shared library which SONAME property matches the regular expression
3608 specified as value of this property.
3609 • soname_not_regexp
3611 Usage:
3613 soname_not_regexp = <regular-expression>
3614 Suppresses change reports about ABI artifacts that are defined in a
3616 shared library which SONAME property does not match the regular ex‐
3617 pression specified as value of this property.
3618 • symbol_name
3620 Usage:
3621 symbol_name = <some-value>
3622 Suppresses change reports involving functions whose symbol name
3624 equals the value of this property.
3625 • symbol_name_regexp
3627 Usage:
3628 symbol_name_regexp = <regular-expression>
3629 Suppresses change reports involving functions whose symbol name
3631 matches the regular expression specified as value of this property.
3632 Let’s consider the case of functions that have several symbol names.
3634 This happens when the underlying symbol for the function has
3635 aliases. Each symbol name is actually one alias name.
3636 In this case, the regular expression must match the names of all of
3638 the aliases of the function for the directive to actually suppress
3639 the diff reports for said function.
3640 • symbol_name_not_regexp
3642 Usage:
3643 symbol_name_not_regexp = <regular-expression>
3644 Suppresses change reports involving functions whose symbol name does
3646 not match the regular expression specified as value of this prop‐
3647 erty.
3648 • symbol_version
3650 Usage:
3651 symbol_version = <some-value>
3652 Suppresses change reports involving functions whose symbol version
3654 equals the value of this property.
3655 • symbol_version_regexp
3657 Usage:
3658 symbol_version_regexp = <regular-expression>
3659 Suppresses change reports involving functions whose symbol version
3661 matches the regular expression specified as value of this property.
3662 [suppress_variable]
3664 This directive suppresses report messages about changes on a set of
3665 variables.
3666 Note that for the [suppress_variable] directive to work, at least one
3668 of the following properties must be provided:
3669 label, file_name_regexp, file_name_not_regexp, soname_regexp, son‐
3670 ame_not_regexp, name, name_regexp, name_not_regexp, symbol_name,
3671 symbol_name_regexp, symbol_name_not_regexp, symbol_version, sym‐
3672 bol_version_regexp, type_name, type_name_regexp.
3673 If none of the above properties are provided, then the [suppress_vari‐
3675 able] directive is simply ignored.
3676 The potential properties of this sections are:
3678 • label
3680 Usage:
3681 label = <some-value>
3682 This property is the same as the label property defined above.
3684 • file_name_regexp
3686 Usage:
3688 file_name_regexp = <regular-expression>
3690 Suppresses change reports about ABI artifacts that are defined in a
3692 binary file which name matches the regular expression specified as
3693 value of this property.
3694 • file_name_not_regexp
3696 Usage:
3698 file_name_not_regexp = <regular-expression>
3699 Suppresses change reports about ABI artifacts that are defined in a
3701 binary file which name does not match the regular expression speci‐
3702 fied as value of this property.
3703 • soname_regexp
3705 Usage:
3707 soname_regexp = <regular-expression>
3708 Suppresses change reports about ABI artifacts that are defined in a
3710 shared library which SONAME property matches the regular expression
3711 specified as value of this property.
3712 • soname_not_regexp
3714 Usage:
3716 soname_not_regexp = <regular-expression>
3717 Suppresses change reports about ABI artifacts that are defined in a
3719 shared library which SONAME property does not match the regular ex‐
3720 pression specified as value of this property.
3721 • name
3723 Usage:
3724 name = <some-value>
3725 Suppresses change reports involving variables whose name equals the
3727 value of this property.
3728 • name_regexp
3730 Usage:
3731 name_regexp = <regular-expression>
3732 Suppresses change reports involving variables whose name matches the
3734 regular expression specified as value of this property.
3735 • change_kind
3737 Usage:
3738 change_kind = <predefined-possible-values>
3739 Specifies the kind of changes this suppression specification should
3741 apply to. The possible values of this property as well as their
3742 meaning are the same as when it’s used in the [suppress_function]
3743 section.
3744 • symbol_name
3746 Usage:
3747 symbol_name = <some-value>
3748 Suppresses change reports involving variables whose symbol name
3750 equals the value of this property.
3751 • symbol_name_regexp
3753 Usage:
3754 symbol_name_regexp = <regular-expression>
3755 Suppresses change reports involving variables whose symbol name
3757 matches the regular expression specified as value of this property.
3758 • symbol_name_not_regexp
3760 Usage:
3761 symbol_name_not_regexp = <regular-expression>
3762 Suppresses change reports involving variables whose symbol name does
3764 not match the regular expression specified as value of this prop‐
3765 erty.
3766 • symbol_version
3768 Usage:
3769 symbol_version = <some-value>
3770 Suppresses change reports involving variables whose symbol version
3772 equals the value of this property.
3773 • symbol_version_regexp
3775 Usage:
3776 symbol_version_regexp = <regular-expression>
3777 Suppresses change reports involving variables whose symbol version
3779 matches the regular expression specified as value of this property.
3780 • type_name
3782 Usage:
3783 type_name = <some-value>
3784 Suppresses change reports involving variables whose type name equals
3786 the value of this property.
3787 • type_name_regexp
3789 Usage:
3790 type_name_regexp = <regular-expression>
3791 Suppresses change reports involving variables whose type name
3793 matches the regular expression specified as value of this property.
3794 Comments
3796 ; or # ASCII character at the beginning of a line indicates a comment.
3797 Comment lines are ignored.
3798 Code examples
3800 1. Suppressing change reports about types.
3801 Suppose we have a library named libtest1-v0.so which contains this
3803 very useful code:
3804 $ cat -n test1-v0.cc
3806 1 // A forward declaration for a type considered to be opaque to
3807 2 // function foo() below.
3808 3 struct opaque_type;
3809 4
3810 5 // This function cannot touch any member of opaque_type. Hence,
3811 6 // changes to members of opaque_type should not impact foo, as far as
3812 7 // ABI is concerned.
3813 8 void
3814 9 foo(opaque_type*)
3815 10 {
3816 11 }
3817 12
3818 13 struct opaque_type
3819 14 {
3820 15 int member0;
3821 16 char member1;
3822 17 };
3823 $
3824 Let’s change the layout of struct opaque_type by inserting a data mem‐
3826 ber around line 15, leading to a new version of the library, that we
3827 shall name libtest1-v1.so:
3828 $ cat -n test1-v1.cc
3830 1 // A forward declaration for a type considered to be opaque to
3831 2 // function foo() below.
3832 3 struct opaque_type;
3833 4
3834 5 // This function cannot touch any member of opaque_type; Hence,
3835 6 // changes to members of opaque_type should not impact foo, as far as
3836 7 // ABI is concerned.
3837 8 void
3838 9 foo(opaque_type*)
3839 10 {
3840 11 }
3841 12
3842 13 struct opaque_type
3843 14 {
3844 15 char added_member; // <-- a new member got added here now.
3845 16 int member0;
3846 17 char member1;
3847 18 };
3848 $
3849 Let’s compile both examples. We shall not forget to compile them with
3851 debug information generation turned on:
3852 $ g++ -shared -g -Wall -o libtest1-v0.so test1-v0.cc
3854 $ g++ -shared -g -Wall -o libtest1-v1.so test1-v1.cc
3855 Let’s ask abidiff which ABI differences it sees between libtest1-v0.so
3857 and libtest1-v1.so:
3858 $ abidiff libtest1-v0.so libtest1-v1.so
3860 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3861 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3862 1 function with some indirect sub-type change:
3864 [C]'function void foo(opaque_type*)' has some indirect sub-type changes:
3866 parameter 0 of type 'opaque_type*' has sub-type changes:
3867 in pointed to type 'struct opaque_type':
3868 size changed from 64 to 96 bits
3869 1 data member insertion:
3870 'char opaque_type::added_member', at offset 0 (in bits)
3871 2 data member changes:
3872 'int opaque_type::member0' offset changed from 0 to 32
3873 'char opaque_type::member1' offset changed from 32 to 64
3874 So abidiff reports that the opaque_type’s layout has changed in a sig‐
3876 nificant way, as far as ABI implications are concerned, in theory. Af‐
3877 ter all, a sub-type (struct opaque_type) of an exported function
3878 (foo()) has seen its layout change. This might have non negligible ABI
3879 implications. But in practice here, the programmer of the
3880 litest1-v1.so library knows that the “soft” contract between the func‐
3881 tion foo() and the type struct opaque_type is to stay away from the
3882 data members of the type. So layout changes of struct opaque_type
3883 should not impact foo().
3884 Now to teach abidiff about this soft contract and have it avoid emit‐
3886 ting what amounts to false positives in this case, we write the sup‐
3887 pression specification file below:
3888 $ cat test1.suppr
3890 [suppress_type]
3891 type_kind = struct
3892 name = opaque_type
3893 Translated in plain English, this suppression specification would read:
3895 “Do not emit change reports about a struct which name is opaque_type”.
3896 Let’s now invoke abidiff on the two versions of the library again, but
3898 this time with the suppression specification:
3899 $ abidiff --suppressions test1.suppr libtest1-v0.so libtest1-v1.so
3901 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3902 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3903 As you can see, abidiff does not report the change anymore; it tells us
3905 that it was filtered out instead.
3906 Suppressing change reports about types with data member insertions
3908 Suppose the first version of a library named libtest3-v0.so has this
3910 source code:
3911 /* Compile this with:
3913 gcc -g -Wall -shared -o libtest3-v0.so test3-v0.c
3914 */
3915 struct S
3917 {
3918 char member0;
3919 int member1; /*
3920 between member1 and member2, there is some padding,
3921 at least on some popular platforms. On
3922 these platforms, adding a small enough data
3923 member into that padding shouldn't change
3924 the offset of member1. Right?
3925 */
3926 };
3927 int
3929 foo(struct S* s)
3930 {
3931 return s->member0 + s->member1;
3932 }
3933 Now, suppose the second version of the library named libtest3-v1.so has
3935 this source code in which a data member has been added in the padding
3936 space of struct S and another data member has been added at its end:
3937 /* Compile this with:
3939 gcc -g -Wall -shared -o libtest3-v1.so test3-v1.c
3940 */
3941 struct S
3943 {
3944 char member0;
3945 char inserted1; /* <---- A data member has been added here... */
3946 int member1;
3947 char inserted2; /* <---- ... and another one has been added here. */
3948 };
3949 int
3951 foo(struct S* s)
3952 {
3953 return s->member0 + s->member1;
3954 }
3955 In libtest3-v1.so, adding char data members S::inserted1 and S::in‐
3957 serted2 can be considered harmless (from an ABI compatibility perspec‐
3958 tive), at least on the x86 platform, because that doesn’t change the
3959 offsets of the data members S::member0 and S::member1. But then run‐
3960 ning abidiff on these two versions of library yields:
3961 $ abidiff libtest3-v0.so libtest3-v1.so
3963 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
3964 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3965 1 function with some indirect sub-type change:
3967 [C]'function int foo(S*)' has some indirect sub-type changes:
3969 parameter 0 of type 'S*' has sub-type changes:
3970 in pointed to type 'struct S':
3971 type size changed from 64 to 96 bits
3972 2 data member insertions:
3973 'char S::inserted1', at offset 8 (in bits)
3974 'char S::inserted2', at offset 64 (in bits)
3975 $
3976 That is, abidiff shows us the two changes, even though we (the develop‐
3978 ers of that very involved library) know that these changes are harmless
3979 in this particular context.
3980 Luckily, we can devise a suppression specification that essentially
3982 tells abidiff to filter out change reports about adding a data member
3983 between S::member0 and S::member1, and adding a data member at the end
3984 of struct S. We have written such a suppression specification in a
3985 file called test3-1.suppr and it unsurprisingly looks like:
3986 [suppress_type]
3988 name = S
3989 has_data_member_inserted_between = {offset_after(member0), offset_of(member1)}
3990 has_data_member_inserted_at = end
3991 Now running abidiff with this suppression specification yields:
3993 $ ../build/tools/abidiff --suppressions test3-1.suppr libtest3-v0.so libtest3-v1.so
3995 Functions changes summary: 0 Removed, 0 Changed (1 filtered out), 0 Added function
3996 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
3997 $
3999 Hooora! \o/ (I guess)
4001 Suppressing change reports about types accessed either directly or
4003 through pointers
4004 Suppose we have a first version of an object file which source code is
4006 the file widget-v0.cc below:
4007 // Compile with: g++ -g -c widget-v0.cc
4009 struct widget
4011 {
4012 int x;
4013 int y;
4014 widget()
4016 :x(), y()
4017 {}
4018 };
4019 void
4021 fun0(widget*)
4022 {
4023 // .. do stuff here.
4024 }
4025 void
4027 fun1(widget&)
4028 {
4029 // .. do stuff here ..
4030 }
4031 void
4033 fun2(widget w)
4034 {
4035 // ... do other stuff here ...
4036 }
4037 Now suppose in the second version of that file, named widget-v1.cc, we
4039 have added some data members at the end of the type struct widget; here
4040 is what the content of that file would look like:
4041 // Compile with: g++ -g -c widget-v1.cc
4043 struct widget
4045 {
4046 int x;
4047 int y;
4048 int w; // We have added these two new data members here ..
4049 int h; // ... and here.
4050 widget()
4052 : x(), y(), w(), h()
4053 {}
4054 };
4055 void
4057 fun0(widget*)
4058 {
4059 // .. do stuff here.
4060 }
4061 void
4063 fun1(widget&)
4064 {
4065 // .. do stuff here ..
4066 }
4067 void
4069 fun2(widget w)
4070 {
4071 // ... do other stuff here ...
4072 }
4073 When we invoke abidiff on the object files resulting from the compila‐
4075 tion of the two file above, here is what we get:
4076 $ abidiff widget-v0.o widget-v1.o
4078 Functions changes summary: 0 Removed, 2 Changed (1 filtered out), 0 Added functions
4079 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4080 2 functions with some indirect sub-type change:
4082 [C]'function void fun0(widget*)' has some indirect sub-type changes:
4084 parameter 1 of type 'widget*' has sub-type changes:
4085 in pointed to type 'struct widget':
4086 type size changed from 64 to 128 bits
4087 2 data member insertions:
4088 'int widget::w', at offset 64 (in bits)
4089 'int widget::h', at offset 96 (in bits)
4090 [C]'function void fun2(widget)' has some indirect sub-type changes:
4092 parameter 1 of type 'struct widget' has sub-type changes:
4093 details were reported earlier
4094 $
4095 I guess a little bit of explaining is due here. abidiff detects that
4097 two data member got added at the end of struct widget. it also tells
4098 us that the type change impacts the exported function fun0() which uses
4099 the type struct widget through a pointer, in its signature.
4100 Careful readers will notice that the change to struct widget also im‐
4102 pacts the exported function fun1(), that uses type struct widget
4103 through a reference. But then abidiff doesn’t tell us about the impact
4104 on that function fun1() because it has evaluated that change as being
4105 redundant with the change it reported on fun0(). It has thus filtered
4106 it out, to avoid cluttering the output with noise.
4107 Redundancy detection and filtering is fine and helpful to avoid burying
4109 the important information in a sea of noise. However, it must be
4110 treated with care, by fear of mistakenly filtering out relevant and im‐
4111 portant information.
4112 That is why abidiff tells us about the impact that the change to struct
4114 widget has on function fun2(). In this case, that function uses the
4115 type struct widget directly (in its signature). It does not use it via
4116 a pointer or a reference. In this case, the direct use of this type
4117 causes fun2() to be exposed to a potentially harmful ABI change.
4118 Hence, the report about fun2() is not filtered out, even though it’s
4119 about that same change on struct widget.
4120 To go further in suppressing reports about changes that are harmless
4122 and keeping only those that we know are harmful, we would like to go
4123 tell abidiff to suppress reports about this particular struct widget
4124 change when it impacts uses of struct widget through a pointer or ref‐
4125 erence. In other words, suppress the change reports about fun0() and
4126 fun1(). We would then write this suppression specification, in file
4127 widget.suppr:
4128 [suppress_type]
4130 name = widget
4131 type_kind = struct
4132 has_data_member_inserted_at = end
4133 accessed_through = reference-or-pointer
4134 # So this suppression specification says to suppress reports about
4136 # the type 'struct widget', if this type was added some data member
4137 # at its end, and if the change impacts uses of the type through a
4138 # reference or a pointer.
4139 Invoking abidiff on widget-v0.o and widget-v1.o with this suppression
4141 specification yields:
4142 $ abidiff --suppressions widget.suppr widget-v0.o widget-v1.o
4144 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
4145 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4146 1 function with some indirect sub-type change:
4148 [C]'function void fun2(widget)' has some indirect sub-type changes:
4150 parameter 1 of type 'struct widget' has sub-type changes:
4151 type size changed from 64 to 128 bits
4152 2 data member insertions:
4153 'int widget::w', at offset 64 (in bits)
4154 'int widget::h', at offset 96 (in bits)
4155 $
4156 As expected, I guess.
4158 Suppressing change reports about functions.
4160 Suppose we have a first version a library named libtest2-v0.so whose
4162 source code is:
4163 $ cat -n test2-v0.cc
4165 1 struct S1
4167 2 {
4168 3 int m0;
4169 4
4170 5 S1()
4171 6 : m0()
4172 7 {}
4173 8 };
4174 9
4175 10 struct S2
4176 11 {
4177 12 int m0;
4178 13
4179 14 S2()
4180 15 : m0()
4181 16 {}
4182 17 };
4183 18
4184 19 struct S3
4185 20 {
4186 21 int m0;
4187 22
4188 23 S3()
4189 24 : m0()
4190 25 {}
4191 26 };
4192 27
4193 28 int
4194 29 func(S1&)
4195 30 {
4196 31 // suppose the code does something with the argument.
4197 32 return 0;
4198 33
4199 34 }
4200 35
4201 36 char
4202 37 func(S2*)
4203 38 {
4204 39 // suppose the code does something with the argument.
4205 40 return 0;
4206 41 }
4207 42
4208 43 unsigned
4209 44 func(S3)
4210 45 {
4211 46 // suppose the code does something with the argument.
4212 47 return 0;
4213 48 }
4214 $
4215 And then we come up with a second version libtest2-v1.so of that li‐
4217 brary; the source code is modified by making the structures S1, S2, S3
4218 inherit another struct:
4219 $ cat -n test2-v1.cc
4221 1 struct base_type
4222 2 {
4223 3 int m_inserted;
4224 4 };
4225 5
4226 6 struct S1 : public base_type // <--- S1 now has base_type as its base
4227 7 // type.
4228 8 {
4229 9 int m0;
4230 10
4231 11 S1()
4232 12 : m0()
4233 13 {}
4234 14 };
4235 15
4236 16 struct S2 : public base_type // <--- S2 now has base_type as its base
4237 17 // type.
4238 18 {
4239 19 int m0;
4240 20
4241 21 S2()
4242 22 : m0()
4243 23 {}
4244 24 };
4245 25
4246 26 struct S3 : public base_type // <--- S3 now has base_type as its base
4247 27 // type.
4248 28 {
4249 29 int m0;
4250 30
4251 31 S3()
4252 32 : m0()
4253 33 {}
4254 34 };
4255 35
4256 36 int
4257 37 func(S1&)
4258 38 {
4259 39 // suppose the code does something with the argument.
4260 40 return 0;
4261 41
4262 42 }
4263 43
4264 44 char
4265 45 func(S2*)
4266 46 {
4267 47 // suppose the code does something with the argument.
4268 48 return 0;
4269 49 }
4270 50
4271 51 unsigned
4272 52 func(S3)
4273 53 {
4274 54 // suppose the code does something with the argument.
4275 55 return 0;
4276 56 }
4277 $
4278 Now let’s build the two libraries:
4280 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
4282 g++ -Wall -g -shared -o libtest2-v0.so test2-v0.cc
4283 Let’s look at the output of abidiff:
4285 $ abidiff libtest2-v0.so libtest2-v1.so
4287 Functions changes summary: 0 Removed, 3 Changed, 0 Added functions
4288 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4289 3 functions with some indirect sub-type change:
4291 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
4293 parameter 0 of type 'struct S3' has sub-type changes:
4294 size changed from 32 to 64 bits
4295 1 base class insertion:
4296 struct base_type
4297 1 data member change:
4298 'int S3::m0' offset changed from 0 to 32
4299 [C]'function char func(S2*)' has some indirect sub-type changes:
4301 parameter 0 of type 'S2*' has sub-type changes:
4302 in pointed to type 'struct S2':
4303 size changed from 32 to 64 bits
4304 1 base class insertion:
4305 struct base_type
4306 1 data member change:
4307 'int S2::m0' offset changed from 0 to 32
4308 [C]'function int func(S1&)' has some indirect sub-type changes:
4310 parameter 0 of type 'S1&' has sub-type changes:
4311 in referenced type 'struct S1':
4312 size changed from 32 to 64 bits
4313 1 base class insertion:
4314 struct base_type
4315 1 data member change:
4316 'int S1::m0' offset changed from 0 to 32
4317 $
4318 Let’s tell abidiff to avoid showing us the differences on the overloads
4320 of func that takes either a pointer or a reference. For that, we au‐
4321 thor this simple suppression specification:
4322 $ cat -n libtest2.suppr
4324 1 [suppress_function]
4325 2 name = func
4326 3 parameter = '0 S1&
4327 4
4328 5 [suppress_function]
4329 6 name = func
4330 7 parameter = '0 S2*
4331 $
4332 And then let’s invoke abidiff with the suppression specification:
4334 $ ../build/tools/abidiff --suppressions libtest2.suppr libtest2-v0.so libtest2-v1.so
4336 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
4337 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4338 1 function with some indirect sub-type change:
4340 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
4342 parameter 0 of type 'struct S3' has sub-type changes:
4343 size changed from 32 to 64 bits
4344 1 base class insertion:
4345 struct base_type
4346 1 data member change:
4347 'int S3::m0' offset changed from 0 to 32
4348 The suppression specification could be reduced using regular expres‐
4350 sions:
4351 $ cat -n libtest2-1.suppr
4353 1 [suppress_function]
4354 2 name = func
4355 3 parameter = '0 /^S.(&|\\*)/
4356 $
4357 $ ../build/tools/abidiff --suppressions libtest2-1.suppr libtest2-v0.so libtest2-v1.so
4359 Functions changes summary: 0 Removed, 1 Changed (2 filtered out), 0 Added function
4360 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4361 1 function with some indirect sub-type change:
4363 [C]'function unsigned int func(S3)' has some indirect sub-type changes:
4365 parameter 0 of type 'struct S3' has sub-type changes:
4366 size changed from 32 to 64 bits
4367 1 base class insertion:
4368 struct base_type
4369 1 data member change:
4370 'int S3::m0' offset changed from 0 to 32
4371 $
4373
4375 Dodji Seketeli
4376
4378 2014-2023, Red Hat, Inc.
4379 Nov 20, 2023 LIBABIGAIL(7)