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, CTF or in BTF formats. Please note however that some
17 packages contain binaries that embed the debug information directly in
18 a section of said binaries. In those cases, obviously, no separate de‐
19 bug information package is needed as the tool will find the debug in‐
20 formation 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 or in BTF formats, if present. Finally, if no debug info in
25 these formats is found, it only considers ELF symbols and report about
26 their addition or removal.
27 This tool uses the libabigail library to analyze the binary as well as
29 its associated debug information. Here is its general mode of opera‐
30 tion.
31 When instructed to do so, a binary and its associated debug information
33 is read and analyzed. To that effect, libabigail analyzes by default
34 the descriptions of the types reachable by the interfaces (functions
35 and variables) that are visible outside of their translation unit.
36 Once that analysis is done, an Application Binary Interface Corpus is
37 constructed by only considering the subset of types reachable from in‐
38 terfaces associated to ELF symbols that are defined and exported by the
39 binary. It’s that final ABI corpus which libabigail considers as rep‐
40 resenting the ABI of the analyzed binary.
41 Libabigail then has capabilities to generate textual representations of
43 ABI Corpora, compare them, analyze their changes and report about them.
44
46 abipkgdiff [option] <package1> <package2>
47 package1 and package2 are the packages that contain the binaries to be
49 compared.
50
52 abipkgdiff loads two default suppression specifications files, merges
53 their content and use it to filter out ABI change reports that might be
54 considered as false positives to users.
55 • Default system-wide suppression specification file
57 It’s located by the optional environment variable LIBABIGAIL_DE‐
59 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
60 set, then abipkgdiff tries to load the suppression file $lib‐
61 dir/libabigail/libabigail-default.abignore. If that file is not
62 present, then no default system-wide suppression specification file
63 is loaded.
64 • Default user suppression specification file.
66 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
68 PRESSION_FILE. If that environment variable is not set, then abip‐
69 kgdiff tries to load the suppression file $HOME/.abignore. If that
70 file is not present, then no default user suppression specification
71 is loaded.
72 In addition to those default suppression specification files, abip‐
74 kgdiff will also look inside the packages being compared and if it sees
75 a file that ends with the extension .abignore, then it will consider it
76 as a suppression specification and it will combine it to the default
77 suppression specification that might be already loaded.
78 The user might as well use the --suppressions option (that is docu‐
80 mented further below) to provide a suppression specification.
81
83 • --help | -h
84 Display a short help about the command and exit.
86 • –version | -v
88 Display the version of the program and exit.
90 • --debug-info-pkg1 | --d1 <path>
92 For cases where the debug information for package1 is split out
94 into a separate file, tells abipkgdiff where to find that separate
95 debug information package.
96 Note that the debug info for package1 can have been split into
98 several different debug info packages. In that case, several in‐
99 stances of this options can be provided, along with those several
100 different debug info packages.
101 • --debug-info-pkg2 | --d2 <path>
103 For cases where the debug information for package2 is split out
105 into a separate file, tells abipkgdiff where to find that separate
106 debug information package.
107 Note that the debug info for package2 can have been split into
109 several different debug info packages. In that case, several in‐
110 stances of this options can be provided, along with those several
111 different debug info packages.
112 • --devel-pkg1 | --devel1 <path>
114 Specifies where to find the Development Package associated with
116 the first package to be compared. That Development Package at
117 path should at least contain header files in which public types
118 exposed by the libraries (of the first package to be compared) are
119 defined. When this option is provided, the tool filters out re‐
120 ports about ABI changes to types that are NOT defined in these
121 header files.
122 • --devel-pkg2 | --devel2 <path>
124 Specifies where to find the Development Package associated with
126 the second package to be compared. That Development Package at
127 path should at least contains header files in which public types
128 exposed by the libraries (of the second package to be compared)
129 are defined. When this option is provided, the tool filters out
130 reports about ABI changes to types that are NOT defined in these
131 header files.
132 • --drop-private-types
134 This option is to be used with the --devel-pkg1 and --devel-pkg2
136 options. With this option, types that are NOT defined in the
137 headers are entirely dropped from the internal representation
138 build by Libabigail to represent the ABI. They thus don’t have to
139 be filtered out from the final ABI change report because they are
140 not even present in Libabigail’s representation.
141 Without this option however, those private types are kept in the
143 internal representation and later filtered out from the report.
144 This options thus potentially makes Libabigail consume less mem‐
146 ory. It’s meant to be mainly used to optimize the memory consump‐
147 tion of the tool on binaries with a lot of publicly defined and
148 exported types.
149 • --dso-only
151 Compare ELF files that are shared libraries, only. Do not compare
153 executable files, for instance.
154 • --private-dso
156 By default, abipkgdiff does not compare DSOs that are private to
158 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
159 vertised in the “provides” property of the RPM.
160 This option instructs abipkgdiff to also compare DSOs that are NOT
162 advertised in the “provides” property of the RPM.
163 Please note that the fact that (by default) abipkgdiff skips pri‐
165 vate DSO is a feature that is available only for RPMs, at the mo‐
166 ment. We would happily accept patches adding that feature for
167 other package formats.
168 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
170 pact analysis report. This option implies --redundant
171 The typical output of abipkgdiff and abidiff when comparing two
173 binaries, that we shall call full impact report, looks like this
174 $ abidiff libtest-v0.so libtest-v1.so
176 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
177 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
178 1 function with some indirect sub-type change:
180 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
182 parameter 1 of type 'C&' has sub-type changes:
183 in referenced type 'struct C' at test-v1.cc:7:1:
184 type size hasn't changed
185 1 data member change:
186 type of 'leaf* C::m0' changed:
187 in pointed to type 'struct leaf' at test-v1.cc:1:1:
188 type size changed from 32 to 64 bits
189 1 data member insertion:
190 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
191 $
193 So in that example the report emits information about how the data
195 member insertion change of “struct leaf” is reachable from func‐
196 tion “void fn(C&)”. In other words, the report not only shows the
197 data member change on “struct leaf”, but it also shows the impact
198 of that change on the function “void fn(C&)”.
199 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
201 is called a leaf change. So the --leaf-changes-only --im‐
202 pacted-interfaces options show, well, only the leaf change. And
203 it goes like this:
204 $ abidiff -l libtest-v0.so libtest-v1.so
206 'struct leaf' changed:
207 type size changed from 32 to 64 bits
208 1 data member insertion:
209 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
210 one impacted interface:
212 function void fn(C&)
213 $
214 Note how the report ends up by showing the list of interfaces im‐
216 pacted by the leaf change. That’s the effect of the additional
217 --impacted-interfaces option.
218 Now if you don’t want to see that list of impacted interfaces,
220 then you can just avoid using the --impacted-interface option.
221 You can learn about that option below, in any case.
222 Please note that when comparing two Linux Kernel packages, it’s
224 this leaf changes report that is emitted, by default. The normal
225 so-called full impact report can be emitted with the option
226 --full-impact which is documented later below.
227 • --impacted-interfaces
229 When showing leaf changes, this option instructs abipkgdiff to
231 show the list of impacted interfaces. This option is thus to be
232 used in addition to the --leaf-changes-only option, or, when com‐
233 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
234 • --full-impact|-f
236 When comparing two Linux Kernel packages, this function instructs
238 abipkgdiff to emit the so-called full impact report, which is the
239 default report kind emitted by the abidiff tool:
240 $ abidiff libtest-v0.so libtest-v1.so
242 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
243 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
244 1 function with some indirect sub-type change:
246 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
248 parameter 1 of type 'C&' has sub-type changes:
249 in referenced type 'struct C' at test-v1.cc:7:1:
250 type size hasn't changed
251 1 data member change:
252 type of 'leaf* C::m0' changed:
253 in pointed to type 'struct leaf' at test-v1.cc:1:1:
254 type size changed from 32 to 64 bits
255 1 data member insertion:
256 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
257 $
259 • --non-reachable-types|-t
261 Analyze and emit change reports for all the types of the binary,
263 including those that are not reachable from global functions and
264 variables.
265 This option might incur some serious performance degradation as
267 the number of types analyzed can be huge. However, if paired with
268 the --devel-pkg{1,2} options, the additional non-reachable types
269 analyzed are restricted to those defined in the public headers
270 files carried by the referenced development packages, thus hope‐
271 fully making the performance hit acceptable.
272 Also, using this option alongside suppression specifications (by
274 also using the --suppressions option) might help keep the number
275 of analyzed types (and the potential performance degradation) in
276 control.
277 Note that without this option, only types that are reachable from
279 global functions and variables are analyzed, so the tool detects
280 and reports changes on these reachable types only.
281 • --exported-interfaces-only
283 By default, when looking at the debug information accompanying a
285 binary, this tool analyzes the descriptions of the types reachable
286 by the interfaces (functions and variables) that are visible out‐
287 side of their translation unit. Once that analysis is done, an
288 ABI corpus is constructed by only considering the subset of types
289 reachable from interfaces associated to ELF symbols that are de‐
290 fined and exported by the binary. It’s those final ABI Corpora
291 that are compared by this tool.
292 The problem with that approach however is that analyzing all the
294 interfaces that are visible from outside their translation unit
295 can amount to a lot of data, especially when those binaries are
296 applications, as opposed to shared libraries. One example of such
297 applications is the Linux Kernel. Analyzing massive ABI corpora
298 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. Otherwise, it’s turned off by default.
306 • --allow-non-exported-interfaces
308 When looking at the debug information accompanying a binary, this
310 tool analyzes the descriptions of the types reachable by the in‐
311 terfaces (functions and variables) that are visible outside of
312 their translation unit. Once that analysis is done, an ABI corpus
313 is constructed by only considering the subset of types reachable
314 from interfaces associated to ELF symbols that are defined and ex‐
315 ported by the binary. It’s those final ABI Corpora that are com‐
316 pared by this tool.
317 The problem with that approach however is that analyzing all the
319 interfaces that are visible from outside their translation unit
320 can amount to a lot of data, especially when those binaries are
321 applications, as opposed to shared libraries. One example of such
322 applications is the Linux Kernel. Analyzing massive ABI Corpora
323 like these can be extremely slow.
324 In the presence of an “average sized” binary however one can af‐
326 ford having libabigail analyze all interfaces that are visible
327 outside of their translation unit, using this option.
328 Note that this option is turned on by default, unless we are in
330 the presence of the Linux Kernel.
331 • --redundant
333 In the diff reports, do display redundant changes. A redundant
334 change is a change that has been displayed elsewhere in a given
335 report.
336 • --harmless
338 In the diff report, display only the harmless changes. By de‐
340 fault, the harmless changes are filtered out of the diff report
341 keep the clutter to a minimum and have a greater chance to spot
342 real ABI issues.
343 • --no-linkage-name
345 In the resulting report, do not display the linkage names of the
347 added, removed, or changed functions or variables.
348 • --no-added-syms
350 Do not show the list of functions, variables, or any symbol that
352 was added.
353 • --no-added-binaries
355 Do not show the list of binaries that got added to the second
357 package.
358 Please note that the presence of such added binaries is not con‐
360 sidered like an ABI change by this tool; as such, it doesn’t have
361 any impact on the exit code of the tool. It does only have an in‐
362 formational value. Removed binaries are, however, considered as
363 an ABI change.
364 • --no-abignore
366 Do not search the package for the presence of suppression files.
368 • --no-parallel
370 By default, abipkgdiff will use all the processors it has avail‐
372 able to execute concurrently. This option tells it not to extract
373 packages or run comparisons in parallel.
374 • --no-default-suppression
376 Do not load the default suppression specification files.
378 • --suppressions | --suppr <path-to-suppressions>
380 Use a suppression specification file located at path-to-suppres‐
382 sions. Note that this option can appear multiple times on the
383 command line. In that case, all of the suppression specification
384 files are taken into account.
385 Please note that, by default, if this option is not provided, then
387 the default suppression specification files are loaded .
388 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
390 When comparing two Linux kernel RPM packages, this option points
392 to the white list of names of ELF symbols of functions and vari‐
393 ables that must be compared for ABI changes. That white list is
394 called a “Linux kernel ABI white list”.
395 Any other function or variable which ELF symbol are not present in
397 that white list will not be considered by the ABI comparison
398 process.
399 If this option is not provided – thus if no white list is provided
401 – then the ABI of all publicly defined and exported functions and
402 global variables by the Linux Kernel binaries are compared.
403 Please note that if a white list package is given in parameter,
405 this option handles it just fine, like if the –wp option was used.
406 • --wp <path-to-whitelist-package>
408 When comparing two Linux kernel RPM packages, this option points
410 an RPM package containining several white lists of names of ELF
411 symbols of functions and variables that must be compared for ABI
412 changes. Those white lists are called “Linux kernel ABI white
413 lists”.
414 From the content of that white list package, this program then
416 chooses the appropriate Linux kernel ABI white list to consider
417 when comparing the ABI of Linux kernel binaries contained in the
418 Linux kernel packages provided on the command line.
419 That choosen Linux kernel ABI white list contains the list of
421 names of ELF symbols of functions and variables that must be com‐
422 pared for ABI changes.
423 Any other function or variable which ELF symbol are not present in
425 that white list will not be considered by the ABI comparison
426 process.
427 Note that this option can be provided twice (not mor than twice),
429 specifying one white list package for each Linux Kernel package
430 that is provided on the command line.
431 If this option is not provided – thus if no white list is provided
433 – then the ABI of all publicly defined and exported functions and
434 global variables by the Linux Kernel binaries are compared.
435 • --no-unreferenced-symbols
437 In the resulting report, do not display change information about
439 function and variable symbols that are not referenced by any debug
440 information. Note that for these symbols not referenced by any
441 debug information, the change information displayed is either
442 added or removed symbols.
443 • --no-show-locs
445 Do not show information about where in the second shared library
446 the respective type was changed.
447 • --show-bytes
449 Show sizes and offsets in bytes, not bits. By default, sizes and
451 offsets are shown in bits.
452 • --show-bits
454 Show sizes and offsets in bits, not bytes. This option is acti‐
456 vated by default.
457 • --show-hex
459 Show sizes and offsets in hexadecimal base.
461 • --show-dec
463 Show sizes and offsets in decimal base. This option is activated
465 by default.
466 • --no-show-relative-offset-changes
468 Without this option, when the offset of a data member changes, the
470 change report not only mentions the older and newer offset, but it
471 also mentions by how many bits the data member changes. With this
472 option, the latter is not shown.
473 • --show-identical-binaries
475 Show the names of the all binaries compared, including the bina‐
476 ries whose ABI compare equal. By default, when this option is
477 not provided, only binaries with ABI changes are mentionned in
478 the output.
479 • --fail-no-dbg
481 Make the program fail and return a non-zero exit code if couldn’t
483 read any of the debug information that comes from the debug info
484 packages that were given on the command line. If no debug info
485 package were provided on the command line then this option is not
486 active.
487 Note that the non-zero exit code returned by the program as a re‐
489 sult of this option is the constant ABIDIFF_ERROR. To know the
490 numerical value of that constant, please refer to the exit code
491 documentation.
492 • --keep-tmp-files
494 Do not erase the temporary directory files that are created during
496 the execution of the tool.
497 • --verbose
499 Emit verbose progress messages.
501 • --self-check
503 This is used to test the underlying Libabigail library. When in
505 used, the command expects only on input package, along with its
506 associated debug info packages. The command then compares each
507 binary inside the package against its own ABIXML representation.
508 The result of the comparison should yield the empty set if Libabi‐
509 gail behaves correctly. Otherwise, it means there is an issue
510 that ought to be fixed. This option is used by people interested
511 in Libabigail development for regression testing purposes. Here
512 is an example of the use of this option:
513 $ 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
515 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
516 $
517 • --no-assume-odr-for-cplusplus
519 When analysing a binary originating from C++ code using DWARF de‐
521 bug information, libabigail assumes the One Definition Rule to
522 speed-up the analysis. In that case, when several types have the
523 same name in the binary, they are assumed to all be equal.
524 This option disables that assumption and instructs libabigail to
526 actually actually compare the types to determine if they are
527 equal.
528 • --no-leverage-dwarf-factorization
530 When analysing a binary which DWARF debug information was pro‐
532 cessed with the DWZ tool, the type information is supposed to be
533 already factorized. That context is used by libabigail to perform
534 some speed optimizations.
535 This option disables those optimizations.
537 • --ctf
539 This is used to compare packages with CTF debug information,
540 if present.
541 • --btf
543 This is used to compare packages with BTF debug information,
544 if present.
545
547 The exit code of the abipkgdiff command is either 0 if the ABI of the
548 binaries compared are equal, or non-zero if they differ or if the tool
549 encountered an error.
550 In the later case, the value of the exit code is the same as for the
552 abidiff tool.
553
555 Dodji Seketeli
556
558 2014-2023, Red Hat, Inc.
559 Nov 20, 2023 ABIPKGDIFF(1)