1ABIPKGDIFF(1) Libabigail ABIPKGDIFF(1)
2
6 abipkgdiff - compare ABIs of ELF files in software packages
7 abipkgdiff compares the Application Binary Interfaces (ABI) of the ELF
9 binaries contained in two software packages. The software package for‐
10 mats currently supported are Deb, RPM, tar archives (either compressed
11 or not) and plain directories that contain binaries.
12 For a comprehensive ABI change report that includes changes about func‐
14 tion and variable sub-types, the two input packages must be accompanied
15 with their debug information packages that contain debug information
16 either in DWARF or in CTF formats. Please note however that some pack‐
17 ages contain binaries that embed the debug information directly in a
18 section of said binaries. In those cases, obviously, no separate debug
19 information package is needed as the tool will find the debug informa‐
20 tion inside the binaries.
21 By default, abipkgdiff uses debug information in DWARF format, if
23 present, otherwise it compares binaries interfaces using debug informa‐
24 tion in CTF format, if present, finally, if neither is found, it uses
25 only ELF symbols to report which of them were added or removed.
26 This tool uses the libabigail library to analyze the binary as well as
28 its associated debug information. Here is its general mode of opera‐
29 tion.
30 When instructed to do so, a binary and its associated debug information
32 is read and analyzed. To that effect, libabigail analyzes by default
33 the descriptions of the types reachable by the interfaces (functions
34 and variables) that are visible outside of their translation unit.
35 Once that analysis is done, an Application Binary Interface Corpus is
36 constructed by only considering the subset of types reachable from in‐
37 terfaces associated to ELF symbols that are defined and exported by the
38 binary. It’s that final ABI corpus which libabigail considers as rep‐
39 resenting the ABI of the analyzed binary.
40 Libabigail then has capabilities to generate textual representations of
42 ABI Corpora, compare them, analyze their changes and report about them.
43
45 abipkgdiff [option] <package1> <package2>
46 package1 and package2 are the packages that contain the binaries to be
48 compared.
49
51 abipkgdiff loads two default suppression specifications files, merges
52 their content and use it to filter out ABI change reports that might be
53 considered as false positives to users.
54 • Default system-wide suppression specification file
56 It’s located by the optional environment variable LIBABIGAIL_DE‐
58 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
59 set, then abipkgdiff tries to load the suppression file $lib‐
60 dir/libabigail/libabigail-default.abignore. If that file is not
61 present, then no default system-wide suppression specification file
62 is loaded.
63 • Default user suppression specification file.
65 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
67 PRESSION_FILE. If that environment variable is not set, then abip‐
68 kgdiff tries to load the suppression file $HOME/.abignore. If that
69 file is not present, then no default user suppression specification
70 is loaded.
71 In addition to those default suppression specification files, abip‐
73 kgdiff will also look inside the packages being compared and if it sees
74 a file that ends with the extension .abignore, then it will consider it
75 as a suppression specification and it will combine it to the default
76 suppression specification that might be already loaded.
77 The user might as well use the --suppressions option (that is docu‐
79 mented further below) to provide a suppression specification.
80
82 • --help | -h
83 Display a short help about the command and exit.
85 • –version | -v
87 Display the version of the program and exit.
89 • --debug-info-pkg1 | --d1 <path>
91 For cases where the debug information for package1 is split out
93 into a separate file, tells abipkgdiff where to find that separate
94 debug information package.
95 Note that the debug info for package1 can have been split into
97 several different debug info packages. In that case, several in‐
98 stances of this options can be provided, along with those several
99 different debug info packages.
100 • --debug-info-pkg2 | --d2 <path>
102 For cases where the debug information for package2 is split out
104 into a separate file, tells abipkgdiff where to find that separate
105 debug information package.
106 Note that the debug info for package2 can have been split into
108 several different debug info packages. In that case, several in‐
109 stances of this options can be provided, along with those several
110 different debug info packages.
111 • --devel-pkg1 | --devel1 <path>
113 Specifies where to find the Development Package associated with
115 the first package to be compared. That Development Package at
116 path should at least contain header files in which public types
117 exposed by the libraries (of the first package to be compared) are
118 defined. When this option is provided, the tool filters out re‐
119 ports about ABI changes to types that are NOT defined in these
120 header files.
121 • --devel-pkg2 | --devel2 <path>
123 Specifies where to find the Development Package associated with
125 the second package to be compared. That Development Package at
126 path should at least contains header files in which public types
127 exposed by the libraries (of the second package to be compared)
128 are defined. When this option is provided, the tool filters out
129 reports about ABI changes to types that are NOT defined in these
130 header files.
131 • --drop-private-types
133 This option is to be used with the --devel-pkg1 and --devel-pkg2
135 options. With this option, types that are NOT defined in the
136 headers are entirely dropped from the internal representation
137 build by Libabigail to represent the ABI. They thus don’t have to
138 be filtered out from the final ABI change report because they are
139 not even present in Libabigail’s representation.
140 Without this option however, those private types are kept in the
142 internal representation and later filtered out from the report.
143 This options thus potentially makes Libabigail consume less mem‐
145 ory. It’s meant to be mainly used to optimize the memory consump‐
146 tion of the tool on binaries with a lot of publicly defined and
147 exported types.
148 • --dso-only
150 Compare ELF files that are shared libraries, only. Do not compare
152 executable files, for instance.
153 • --private-dso
155 By default, abipkgdiff does not compare DSOs that are private to
157 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
158 vertised in the “provides” property of the RPM.
159 This option instructs abipkgdiff to also compare DSOs that are NOT
161 advertised in the “provides” property of the RPM.
162 Please note that the fact that (by default) abipkgdiff skips pri‐
164 vate DSO is a feature that is available only for RPMs, at the mo‐
165 ment. We would happily accept patches adding that feature for
166 other package formats.
167 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
169 pact analysis report. This option implies --redundant
170 The typical output of abipkgdiff and abidiff when comparing two
172 binaries, that we shall call full impact report, looks like this
173 $ abidiff libtest-v0.so libtest-v1.so
175 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
176 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
177 1 function with some indirect sub-type change:
179 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
181 parameter 1 of type 'C&' has sub-type changes:
182 in referenced type 'struct C' at test-v1.cc:7:1:
183 type size hasn't changed
184 1 data member change:
185 type of 'leaf* C::m0' changed:
186 in pointed to type 'struct leaf' at test-v1.cc:1:1:
187 type size changed from 32 to 64 bits
188 1 data member insertion:
189 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
190 $
192 So in that example the report emits information about how the data
194 member insertion change of “struct leaf” is reachable from func‐
195 tion “void fn(C&)”. In other words, the report not only shows the
196 data member change on “struct leaf”, but it also shows the impact
197 of that change on the function “void fn(C&)”.
198 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
200 is called a leaf change. So the --leaf-changes-only --im‐
201 pacted-interfaces options show, well, only the leaf change. And
202 it goes like this:
203 $ abidiff -l libtest-v0.so libtest-v1.so
205 'struct leaf' changed:
206 type size changed from 32 to 64 bits
207 1 data member insertion:
208 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
209 one impacted interface:
211 function void fn(C&)
212 $
213 Note how the report ends up by showing the list of interfaces im‐
215 pacted by the leaf change. That’s the effect of the additional
216 --impacted-interfaces option.
217 Now if you don’t want to see that list of impacted interfaces,
219 then you can just avoid using the --impacted-interface option.
220 You can learn about that option below, in any case.
221 Please note that when comparing two Linux Kernel packages, it’s
223 this leaf changes report that is emitted, by default. The normal
224 so-called full impact report can be emitted with the option
225 --full-impact which is documented later below.
226 • --impacted-interfaces
228 When showing leaf changes, this option instructs abipkgdiff to
230 show the list of impacted interfaces. This option is thus to be
231 used in addition to the --leaf-changes-only option, or, when com‐
232 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
233 • --full-impact|-f
235 When comparing two Linux Kernel packages, this function instructs
237 abipkgdiff to emit the so-called full impact report, which is the
238 default report kind emitted by the abidiff tool:
239 $ abidiff libtest-v0.so libtest-v1.so
241 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
242 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
243 1 function with some indirect sub-type change:
245 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
247 parameter 1 of type 'C&' has sub-type changes:
248 in referenced type 'struct C' at test-v1.cc:7:1:
249 type size hasn't changed
250 1 data member change:
251 type of 'leaf* C::m0' changed:
252 in pointed to type 'struct leaf' at test-v1.cc:1:1:
253 type size changed from 32 to 64 bits
254 1 data member insertion:
255 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
256 $
258 • --non-reachable-types|-t
260 Analyze and emit change reports for all the types of the binary,
262 including those that are not reachable from global functions and
263 variables.
264 This option might incur some serious performance degradation as
266 the number of types analyzed can be huge. However, if paired with
267 the --devel-pkg{1,2} options, the additional non-reachable types
268 analyzed are restricted to those defined in the public headers
269 files carried by the referenced development packages, thus hope‐
270 fully making the performance hit acceptable.
271 Also, using this option alongside suppression specifications (by
273 also using the --suppressions option) might help keep the number
274 of analyzed types (and the potential performance degradation) in
275 control.
276 Note that without this option, only types that are reachable from
278 global functions and variables are analyzed, so the tool detects
279 and reports changes on these reachable types only.
280 • --exported-interfaces-only
282 By default, when looking at the debug information accompanying a
284 binary, this tool analyzes the descriptions of the types reachable
285 by the interfaces (functions and variables) that are visible out‐
286 side of their translation unit. Once that analysis is done, an
287 ABI corpus is constructed by only considering the subset of types
288 reachable from interfaces associated to ELF symbols that are de‐
289 fined and exported by the binary. It’s those final ABI Corpora
290 that are compared by this tool.
291 The problem with that approach however is that analyzing all the
293 interfaces that are visible from outside their translation unit
294 can amount to a lot of data, especially when those binaries are
295 applications, as opposed to shared libraries. One example of such
296 applications is the
297 `Linux Kernel`_
298 . Analyzing massive ABI corpora like these can be extremely slow.
299 To mitigate that performance issue, this option allows libabigail
301 to only analyze types that are reachable from interfaces associ‐
302 ated with defined and exported ELF symbols.
303 Note that this option is turned on by default when analyzing the
305 `Linux Kernel`_
307 . Otherwise, it’s turned off by default.
308 • --allow-non-exported-interfaces
310 When looking at the debug information accompanying a binary, this
312 tool analyzes the descriptions of the types reachable by the in‐
313 terfaces (functions and variables) that are visible outside of
314 their translation unit. Once that analysis is done, an ABI corpus
315 is constructed by only considering the subset of types reachable
316 from interfaces associated to ELF symbols that are defined and ex‐
317 ported by the binary. It’s those final ABI Corpora that are com‐
318 pared by this tool.
319 The problem with that approach however is that analyzing all the
321 interfaces that are visible from outside their translation unit
322 can amount to a lot of data, especially when those binaries are
323 applications, as opposed to shared libraries. One example of such
324 applications is the
325 `Linux Kernel`_
326 . Analyzing massive ABI Corpora like these can be extremely slow.
327 In the presence of an “average sized” binary however one can af‐
329 ford having libabigail analyze all interfaces that are visible
330 outside of their translation unit, using this option.
331 Note that this option is turned on by default, unless we are in
333 the presence of the
334 `Linux Kernel`_
335 .
336 • --redundant
338 In the diff reports, do display redundant changes. A redundant
339 change is a change that has been displayed elsewhere in a given
340 report.
341 • --harmless
343 In the diff report, display only the harmless changes. By de‐
345 fault, the harmless changes are filtered out of the diff report
346 keep the clutter to a minimum and have a greater chance to spot
347 real ABI issues.
348 • --no-linkage-name
350 In the resulting report, do not display the linkage names of the
352 added, removed, or changed functions or variables.
353 • --no-added-syms
355 Do not show the list of functions, variables, or any symbol that
357 was added.
358 • --no-added-binaries
360 Do not show the list of binaries that got added to the second
362 package.
363 Please note that the presence of such added binaries is not con‐
365 sidered like an ABI change by this tool; as such, it doesn’t have
366 any impact on the exit code of the tool. It does only have an in‐
367 formational value. Removed binaries are, however, considered as
368 an ABI change.
369 • --no-abignore
371 Do not search the package for the presence of suppression files.
373 • --no-parallel
375 By default, abipkgdiff will use all the processors it has avail‐
377 able to execute concurrently. This option tells it not to extract
378 packages or run comparisons in parallel.
379 • --no-default-suppression
381 Do not load the default suppression specification files.
383 • --suppressions | --suppr <path-to-suppressions>
385 Use a suppression specification file located at path-to-suppres‐
387 sions. Note that this option can appear multiple times on the
388 command line. In that case, all of the suppression specification
389 files are taken into account.
390 Please note that, by default, if this option is not provided, then
392 the default suppression specification files are loaded .
393 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
395 When comparing two Linux kernel RPM packages, this option points
397 to the white list of names of ELF symbols of functions and vari‐
398 ables that must be compared for ABI changes. That white list is
399 called a “Linux kernel ABI white list”.
400 Any other function or variable which ELF symbol are not present in
402 that white list will not be considered by the ABI comparison
403 process.
404 If this option is not provided – thus if no white list is provided
406 – then the ABI of all publicly defined and exported functions and
407 global variables by the Linux Kernel binaries are compared.
408 Please note that if a white list package is given in parameter,
410 this option handles it just fine, like if the –wp option was used.
411 • --wp <path-to-whitelist-package>
413 When comparing two Linux kernel RPM packages, this option points
415 an RPM package containining several white lists of names of ELF
416 symbols of functions and variables that must be compared for ABI
417 changes. Those white lists are called “Linux kernel ABI white
418 lists”.
419 From the content of that white list package, this program then
421 chooses the appropriate Linux kernel ABI white list to consider
422 when comparing the ABI of Linux kernel binaries contained in the
423 Linux kernel packages provided on the command line.
424 That choosen Linux kernel ABI white list contains the list of
426 names of ELF symbols of functions and variables that must be com‐
427 pared for ABI changes.
428 Any other function or variable which ELF symbol are not present in
430 that white list will not be considered by the ABI comparison
431 process.
432 Note that this option can be provided twice (not mor than twice),
434 specifying one white list package for each Linux Kernel package
435 that is provided on the command line.
436 If this option is not provided – thus if no white list is provided
438 – then the ABI of all publicly defined and exported functions and
439 global variables by the Linux Kernel binaries are compared.
440 • --no-unreferenced-symbols
442 In the resulting report, do not display change information about
444 function and variable symbols that are not referenced by any debug
445 information. Note that for these symbols not referenced by any
446 debug information, the change information displayed is either
447 added or removed symbols.
448 • --no-show-locs
450 Do not show information about where in the second shared library
451 the respective type was changed.
452 • --show-bytes
454 Show sizes and offsets in bytes, not bits. By default, sizes and
456 offsets are shown in bits.
457 • --show-bits
459 Show sizes and offsets in bits, not bytes. This option is acti‐
461 vated by default.
462 • --show-hex
464 Show sizes and offsets in hexadecimal base.
466 • --show-dec
468 Show sizes and offsets in decimal base. This option is activated
470 by default.
471 • --no-show-relative-offset-changes
473 Without this option, when the offset of a data member changes, the
475 change report not only mentions the older and newer offset, but it
476 also mentions by how many bits the data member changes. With this
477 option, the latter is not shown.
478 • --show-identical-binaries
480 Show the names of the all binaries compared, including the bina‐
481 ries whose ABI compare equal. By default, when this option is
482 not provided, only binaries with ABI changes are mentionned in
483 the output.
484 • --fail-no-dbg
486 Make the program fail and return a non-zero exit code if couldn’t
488 read any of the debug information that comes from the debug info
489 packages that were given on the command line. If no debug info
490 package were provided on the command line then this option is not
491 active.
492 Note that the non-zero exit code returned by the program as a re‐
494 sult of this option is the constant ABIDIFF_ERROR. To know the
495 numerical value of that constant, please refer to the exit code
496 documentation.
497 • --keep-tmp-files
499 Do not erase the temporary directory files that are created during
501 the execution of the tool.
502 • --verbose
504 Emit verbose progress messages.
506 • --self-check
508 This is used to test the underlying Libabigail library. When in
510 used, the command expects only on input package, along with its
511 associated debug info packages. The command then compares each
512 binary inside the package against its own ABIXML representation.
513 The result of the comparison should yield the empty set if Libabi‐
514 gail behaves correctly. Otherwise, it means there is an issue
515 that ought to be fixed. This option is used by people interested
516 in Libabigail development for regression testing purposes. Here
517 is an example of the use of this option:
518 $ 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
520 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
521 $
522 • --no-assume-odr-for-cplusplus
524 When analysing a binary originating from C++ code using DWARF de‐
526 bug information, libabigail assumes the One Definition Rule to
527 speed-up the analysis. In that case, when several types have the
528 same name in the binary, they are assumed to all be equal.
529 This option disables that assumption and instructs libabigail to
531 actually actually compare the types to determine if they are
532 equal.
533 • --no-leverage-dwarf-factorization
535 When analysing a binary which DWARF debug information was pro‐
537 cessed with the DWZ tool, the type information is supposed to be
538 already factorized. That context is used by libabigail to perform
539 some speed optimizations.
540 This option disables those optimizations.
542 • --ctf
544 This is used to compare packages with CTF debug information,
545 if present.
546
548 The exit code of the abipkgdiff command is either 0 if the ABI of the
549 binaries compared are equal, or non-zero if they differ or if the tool
550 encountered an error.
551 In the later case, the value of the exit code is the same as for the
553 abidiff tool.
554
556 Dodji Seketeli
557
559 2014-2022, Red Hat, Inc.
560 Dec 02, 2022 ABIPKGDIFF(1)