1ABIPKGDIFF(1) Libabigail ABIPKGDIFF(1)
2
3
4
6 abipkgdiff - compare ABIs of ELF files in software packages
7
8 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
13 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
22 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
27 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
31 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
41 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
47 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
55 • Default system-wide suppression specification file
56
57 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
64 • Default user suppression specification file.
65
66 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
72 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
78 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
84 Display a short help about the command and exit.
85
86 • –version | -v
87
88 Display the version of the program and exit.
89
90 • --debug-info-pkg1 | --d1 <path>
91
92 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
96 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
101 • --debug-info-pkg2 | --d2 <path>
102
103 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
107 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
112 • --devel-pkg1 | --devel1 <path>
113
114 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
122 • --devel-pkg2 | --devel2 <path>
123
124 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
132 • --drop-private-types
133
134 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
141 Without this option however, those private types are kept in the
142 internal representation and later filtered out from the report.
143
144 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
149 • --dso-only
150
151 Compare ELF files that are shared libraries, only. Do not compare
152 executable files, for instance.
153
154 • --private-dso
155
156 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
160 This option instructs abipkgdiff to also compare DSOs that are NOT
161 advertised in the “provides” property of the RPM.
162
163 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
168 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
169 pact analysis report. This option implies --redundant
170
171 The typical output of abipkgdiff and abidiff when comparing two
172 binaries, that we shall call full impact report, looks like this
173
174 $ 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
178 1 function with some indirect sub-type change:
179
180 [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
191 $
192
193 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
199 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
204 $ 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
210 one impacted interface:
211 function void fn(C&)
212 $
213
214 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
218 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
222 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
227 • --impacted-interfaces
228
229 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
234 • --full-impact|-f
235
236 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
240 $ 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
244 1 function with some indirect sub-type change:
245
246 [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
257 $
258
259 • --non-reachable-types|-t
260
261 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
265 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
272 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
277 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
281 • --exported-interfaces-only
282
283 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
292 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
300 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
304 Note that this option is turned on by default when analyzing the
305
306 `Linux Kernel`_
307 . Otherwise, it’s turned off by default.
308
309 • --allow-non-exported-interfaces
310
311 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
320 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
328 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
332 Note that this option is turned on by default, unless we are in
333 the presence of the
334 `Linux Kernel`_
335 .
336
337 • --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
342 • --harmless
343
344 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
349 • --no-linkage-name
350
351 In the resulting report, do not display the linkage names of the
352 added, removed, or changed functions or variables.
353
354 • --no-added-syms
355
356 Do not show the list of functions, variables, or any symbol that
357 was added.
358
359 • --no-added-binaries
360
361 Do not show the list of binaries that got added to the second
362 package.
363
364 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
370 • --no-abignore
371
372 Do not search the package for the presence of suppression files.
373
374 • --no-parallel
375
376 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
380 • --no-default-suppression
381
382 Do not load the default suppression specification files.
383
384 • --suppressions | --suppr <path-to-suppressions>
385
386 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
391 Please note that, by default, if this option is not provided, then
392 the default suppression specification files are loaded .
393
394 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
395
396 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
401 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
405 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
409 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
412 • --wp <path-to-whitelist-package>
413
414 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
420 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
425 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
429 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
433 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
437 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
441 • --no-unreferenced-symbols
442
443 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
449 • --no-show-locs
450 Do not show information about where in the second shared library
451 the respective type was changed.
452
453 • --show-bytes
454
455 Show sizes and offsets in bytes, not bits. By default, sizes and
456 offsets are shown in bits.
457
458 • --show-bits
459
460 Show sizes and offsets in bits, not bytes. This option is acti‐
461 vated by default.
462
463 • --show-hex
464
465 Show sizes and offsets in hexadecimal base.
466
467 • --show-dec
468
469 Show sizes and offsets in decimal base. This option is activated
470 by default.
471
472 • --no-show-relative-offset-changes
473
474 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
479 • --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
485 • --fail-no-dbg
486
487 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
493 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
498 • --keep-tmp-files
499
500 Do not erase the temporary directory files that are created during
501 the execution of the tool.
502
503 • --verbose
504
505 Emit verbose progress messages.
506
507 • --self-check
508
509 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
519 $ 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
523 • --no-assume-odr-for-cplusplus
524
525 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
530 This option disables that assumption and instructs libabigail to
531 actually actually compare the types to determine if they are
532 equal.
533
534 • --no-leverage-dwarf-factorization
535
536 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
541 This option disables those optimizations.
542
543 • --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
552 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
561
562
563
564 Dec 02, 2022 ABIPKGDIFF(1)