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 in
16 DWARF format.
17
19 abipkgdiff [option] <package1> <package2>
20 package1 and package2 are the packages that contain the binaries to be
22 compared.
23
25 abipkgdiff loads two default suppression specifications files, merges
26 their content and use it to filter out ABI change reports that might be
27 considered as false positives to users.
28 • Default system-wide suppression specification file
30 It’s located by the optional environment variable LIBABIGAIL_DE‐
32 FAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not
33 set, then abipkgdiff tries to load the suppression file $lib‐
34 dir/libabigail/libabigail-default.abignore. If that file is not
35 present, then no default system-wide suppression specification file
36 is loaded.
37 • Default user suppression specification file.
39 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
41 PRESSION_FILE. If that environment variable is not set, then abip‐
42 kgdiff tries to load the suppression file $HOME/.abignore. If that
43 file is not present, then no default user suppression specification
44 is loaded.
45 In addition to those default suppression specification files, abip‐
47 kgdiff will also look inside the packages being compared and if it sees
48 a file that ends with the extension .abignore, then it will consider it
49 as a suppression specification and it will combine it to the default
50 suppression specification that might be already loaded.
51 The user might as well use the --suppressions option (that is docu‐
53 mented further below) to provide a suppression specification.
54
56 • --help | -h
57 Display a short help about the command and exit.
59 • –version | -v
61 Display the version of the program and exit.
63 • --debug-info-pkg1 | --d1 <path>
65 For cases where the debug information for package1 is split out
67 into a separate file, tells abipkgdiff where to find that separate
68 debug information package.
69 Note that the debug info for package1 can have been split into
71 several different debug info packages. In that case, several in‐
72 stances of this options can be provided, along with those several
73 different debug info packages.
74 • --debug-info-pkg2 | --d2 <path>
76 For cases where the debug information for package2 is split out
78 into a separate file, tells abipkgdiff where to find that separate
79 debug information package.
80 Note that the debug info for package2 can have been split into
82 several different debug info packages. In that case, several in‐
83 stances of this options can be provided, along with those several
84 different debug info packages.
85 • --devel-pkg1 | --devel1 <path>
87 Specifies where to find the Development Package associated with
89 the first package to be compared. That Development Package at
90 path should at least contain header files in which public types
91 exposed by the libraries (of the first package to be compared) are
92 defined. When this option is provided, the tool filters out re‐
93 ports about ABI changes to types that are NOT defined in these
94 header files.
95 • --devel-pkg2 | --devel2 <path>
97 Specifies where to find the Development Package associated with
99 the second package to be compared. That Development Package at
100 path should at least contains header files in which public types
101 exposed by the libraries (of the second package to be compared)
102 are defined. When this option is provided, the tool filters out
103 reports about ABI changes to types that are NOT defined in these
104 header files.
105 • --drop-private-types
107 This option is to be used with the --devel-pkg1 and --devel-pkg2
109 options. With this option, types that are NOT defined in the
110 headers are entirely dropped from the internal representation
111 build by Libabigail to represent the ABI. They thus don’t have to
112 be filtered out from the final ABI change report because they are
113 not even present in Libabigail’s representation.
114 Without this option however, those private types are kept in the
116 internal representation and later filtered out from the report.
117 This options thus potentially makes Libabigail consume less mem‐
119 ory. It’s meant to be mainly used to optimize the memory consump‐
120 tion of the tool on binaries with a lot of publicly defined and
121 exported types.
122 • --dso-only
124 Compare ELF files that are shared libraries, only. Do not compare
126 executable files, for instance.
127 • --private-dso
129 By default, abipkgdiff does not compare DSOs that are private to
131 the RPM package. A private DSO is a DSO which SONAME is NOT ad‐
132 vertised in the “provides” property of the RPM.
133 This option instructs abipkgdiff to also compare DSOs that are NOT
135 advertised in the “provides” property of the RPM.
136 Please note that the fact that (by default) abipkgdiff skips pri‐
138 vate DSO is a feature that is available only for RPMs, at the mo‐
139 ment. We would happily accept patches adding that feature for
140 other package formats.
141 • --leaf-changes-only|-l only show leaf changes, so don’t show im‐
143 pact analysis report. This option implies --redundant
144 The typical output of abipkgdiff and abidiff when comparing two
146 binaries, that we shall call full impact report, looks like this
147 $ abidiff libtest-v0.so libtest-v1.so
149 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
150 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
151 1 function with some indirect sub-type change:
153 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
155 parameter 1 of type 'C&' has sub-type changes:
156 in referenced type 'struct C' at test-v1.cc:7:1:
157 type size hasn't changed
158 1 data member change:
159 type of 'leaf* C::m0' changed:
160 in pointed to type 'struct leaf' at test-v1.cc:1:1:
161 type size changed from 32 to 64 bits
162 1 data member insertion:
163 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
164 $
166 So in that example the report emits information about how the data
168 member insertion change of “struct leaf” is reachable from func‐
169 tion “void fn(C&)”. In other words, the report not only shows the
170 data member change on “struct leaf”, but it also shows the impact
171 of that change on the function “void fn(C&)”.
172 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
174 is called a leaf change. So the --leaf-changes-only --im‐
175 pacted-interfaces options show, well, only the leaf change. And
176 it goes like this:
177 $ abidiff -l libtest-v0.so libtest-v1.so
179 'struct leaf' changed:
180 type size changed from 32 to 64 bits
181 1 data member insertion:
182 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
183 one impacted interface:
185 function void fn(C&)
186 $
187 Note how the report ends up by showing the list of interfaces im‐
189 pacted by the leaf change. That’s the effect of the additional
190 --impacted-interfaces option.
191 Now if you don’t want to see that list of impacted interfaces,
193 then you can just avoid using the --impacted-interface option.
194 You can learn about that option below, in any case.
195 Please note that when comparing two Linux Kernel packages, it’s
197 this leaf changes report that is emitted, by default. The normal
198 so-called full impact report can be emitted with the option
199 --full-impact which is documented later below.
200 • --impacted-interfaces
202 When showing leaf changes, this option instructs abipkgdiff to
204 show the list of impacted interfaces. This option is thus to be
205 used in addition to the --leaf-changes-only option, or, when com‐
206 paring two Linux Kernel packages. Otherwise, it’s simply ignored.
207 • --full-impact|-f
209 When comparing two Linux Kernel packages, this function instructs
211 abipkgdiff to emit the so-called full impact report, which is the
212 default report kind emitted by the abidiff tool:
213 $ abidiff libtest-v0.so libtest-v1.so
215 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
216 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
217 1 function with some indirect sub-type change:
219 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
221 parameter 1 of type 'C&' has sub-type changes:
222 in referenced type 'struct C' at test-v1.cc:7:1:
223 type size hasn't changed
224 1 data member change:
225 type of 'leaf* C::m0' changed:
226 in pointed to type 'struct leaf' at test-v1.cc:1:1:
227 type size changed from 32 to 64 bits
228 1 data member insertion:
229 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
230 $
232 • --non-reachable-types|-t
234 Analyze and emit change reports for all the types of the binary,
236 including those that are not reachable from global functions and
237 variables.
238 This option might incur some serious performance degradation as
240 the number of types analyzed can be huge. However, if paired with
241 the --devel-pkg{1,2} options, the additional non-reachable types
242 analyzed are restricted to those defined in the public headers
243 files carried by the referenced development packages, thus hope‐
244 fully making the performance hit acceptable.
245 Also, using this option alongside suppression specifications (by
247 also using the --suppressions option) might help keep the number
248 of analyzed types (and the potential performance degradation) in
249 control.
250 Note that without this option, only types that are reachable from
252 global functions and variables are analyzed, so the tool detects
253 and reports changes on these reachable types only.
254 • --redundant
256 In the diff reports, do display redundant changes. A redundant
257 change is a change that has been displayed elsewhere in a given
258 report.
259 • --harmless
261 In the diff report, display only the harmless changes. By de‐
263 fault, the harmless changes are filtered out of the diff report
264 keep the clutter to a minimum and have a greater chance to spot
265 real ABI issues.
266 • --no-linkage-name
268 In the resulting report, do not display the linkage names of the
270 added, removed, or changed functions or variables.
271 • --no-added-syms
273 Do not show the list of functions, variables, or any symbol that
275 was added.
276 • --no-added-binaries
278 Do not show the list of binaries that got added to the second
280 package.
281 Please note that the presence of such added binaries is not con‐
283 sidered like an ABI change by this tool; as such, it doesn’t have
284 any impact on the exit code of the tool. It does only have an in‐
285 formational value. Removed binaries are, however, considered as
286 an ABI change.
287 • --no-abignore
289 Do not search the package for the presence of suppression files.
291 • --no-parallel
293 By default, abipkgdiff will use all the processors it has avail‐
295 able to execute concurrently. This option tells it not to extract
296 packages or run comparisons in parallel.
297 • --no-default-suppression
299 Do not load the default suppression specification files.
301 • --suppressions | --suppr <path-to-suppressions>
303 Use a suppression specification file located at path-to-suppres‐
305 sions. Note that this option can appear multiple times on the
306 command line. In that case, all of the suppression specification
307 files are taken into account.
308 Please note that, by default, if this option is not provided, then
310 the default suppression specification files are loaded .
311 • --linux-kernel-abi-whitelist | -w <path-to-whitelist>
313 When comparing two Linux kernel RPM packages, this option points
315 to the white list of names of ELF symbols of functions and vari‐
316 ables that must be compared for ABI changes. That white list is
317 called a “Linux kernel ABI white list”.
318 Any other function or variable which ELF symbol are not present in
320 that white list will not be considered by the ABI comparison
321 process.
322 If this option is not provided – thus if no white list is provided
324 – then the ABI of all publicly defined and exported functions and
325 global variables by the Linux Kernel binaries are compared.
326 Please note that if a white list package is given in parameter,
328 this option handles it just fine, like if the –wp option was used.
329 • --wp <path-to-whitelist-package>
331 When comparing two Linux kernel RPM packages, this option points
333 an RPM package containining several white lists of names of ELF
334 symbols of functions and variables that must be compared for ABI
335 changes. Those white lists are called “Linux kernel ABI white
336 lists”.
337 From the content of that white list package, this program then
339 chooses the appropriate Linux kernel ABI white list to consider
340 when comparing the ABI of Linux kernel binaries contained in the
341 Linux kernel packages provided on the command line.
342 That choosen Linux kernel ABI white list contains the list of
344 names of ELF symbols of functions and variables that must be com‐
345 pared for ABI changes.
346 Any other function or variable which ELF symbol are not present in
348 that white list will not be considered by the ABI comparison
349 process.
350 Note that this option can be provided twice (not mor than twice),
352 specifying one white list package for each Linux Kernel package
353 that is provided on the command line.
354 If this option is not provided – thus if no white list is provided
356 – then the ABI of all publicly defined and exported functions and
357 global variables by the Linux Kernel binaries are compared.
358 • --no-unreferenced-symbols
360 In the resulting report, do not display change information about
362 function and variable symbols that are not referenced by any debug
363 information. Note that for these symbols not referenced by any
364 debug information, the change information displayed is either
365 added or removed symbols.
366 • --no-show-locs
368 Do not show information about where in the second shared library
369 the respective type was changed.
370 • --show-bytes
372 Show sizes and offsets in bytes, not bits. By default, sizes and
374 offsets are shown in bits.
375 • --show-bits
377 Show sizes and offsets in bits, not bytes. This option is acti‐
379 vated by default.
380 • --show-hex
382 Show sizes and offsets in hexadecimal base.
384 • --show-dec
386 Show sizes and offsets in decimal base. This option is activated
388 by default.
389 • --no-show-relative-offset-changes
391 Without this option, when the offset of a data member changes, the
393 change report not only mentions the older and newer offset, but it
394 also mentions by how many bits the data member changes. With this
395 option, the latter is not shown.
396 • --show-identical-binaries
398 Show the names of the all binaries compared, including the bina‐
399 ries whose ABI compare equal. By default, when this option is
400 not provided, only binaries with ABI changes are mentionned in
401 the output.
402 • --fail-no-dbg
404 Make the program fail and return a non-zero exit code if couldn’t
406 read any of the debug information that comes from the debug info
407 packages that were given on the command line. If no debug info
408 package were provided on the command line then this option is not
409 active.
410 Note that the non-zero exit code returned by the program as a re‐
412 sult of this option is the constant ABIDIFF_ERROR. To know the
413 numerical value of that constant, please refer to the exit code
414 documentation.
415 • --keep-tmp-files
417 Do not erase the temporary directory files that are created during
419 the execution of the tool.
420 • --verbose
422 Emit verbose progress messages.
424 • self-check
426 This is used to test the underlying Libabigail library. When in
428 used, the command expects only on input package, along with its
429 associated debug info packages. The command then compares each
430 binary inside the package against its own ABIXML representation.
431 The result of the comparison should yield the empty set if Libabi‐
432 gail behaves correctly. Otherwise, it means there is an issue
433 that ought to be fixed. This option is used by people interested
434 in Libabigail development for regression testing purposes. Here
435 is an example of the use of this option:
436 $ 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
438 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
439 $
440
442 The exit code of the abipkgdiff command is either 0 if the ABI of the
443 binaries compared are equal, or non-zero if they differ or if the tool
444 encountered an error.
445 In the later case, the value of the exit code is the same as for the
447 abidiff tool.
448
450 Dodji Seketeli
451
453 2014-2022, Red Hat, Inc.
454 Jan 20, 2022 ABIPKGDIFF(1)