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 in
16 DWARF format.
17
19 abipkgdiff [option] <package1> <package2>
20
21 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
29 · Default system-wide suppression specification file
30
31 It’s located by the optional environment variable LIBABI‐
32 GAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable
33 is not 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
38 · Default user suppression specification file.
39
40 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
46 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
52 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
58 Display a short help about the command and exit.
59
60 · –version | -v
61
62 Display the version of the program and exit.
63
64 · --debug-info-pkg1 | --d1 <path>
65
66 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
70 Note that the debug info for package1 can have been split into
71 several different debug info packages. In that case, several
72 instances of this options can be provided, along with those sev‐
73 eral different debug info packages.
74
75 · --debug-info-pkg2 | --d2 <path>
76
77 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
81 Note that the debug info for package2 can have been split into
82 several different debug info packages. In that case, several
83 instances of this options can be provided, along with those sev‐
84 eral different debug info packages.
85
86 · --devel-pkg1 | --devel1 <path>
87
88 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
93 reports about ABI changes to types that are NOT defined in these
94 header files.
95
96 · --devel-pkg2 | --devel2 <path>
97
98 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
106 · --drop-private-types
107
108 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
115 Without this option however, those private types are kept in the
116 internal representation and later filtered out from the report.
117
118 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
123 · --dso-only
124
125 Compare ELF files that are shared libraries, only. Do not compare
126 executable files, for instance.
127
128 · --private-dso
129
130 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
132 advertised in the “provides” property of the RPM.
133
134 This option instructs abipkgdiff to also compare DSOs that are NOT
135 advertised in the “provides” property of the RPM.
136
137 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
139 moment. We would happily accept patches adding that feature for
140 other package formats.
141
142 · --leaf-changes-only|-l only show leaf changes, so don’t show
143 impact analysis report.
144
145 The typical output of abipkgdiff and abidiff when comparing two
146 binaries, that we shall call full impact report, looks like this
147
148 $ 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
152 1 function with some indirect sub-type change:
153
154 [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
165 $
166
167 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
173 In abidiff (and abipkgdiff) parlance, the change on “struct leaf”
174 is called a leaf change. So the --leaf-changes-only
175 --impacted-interfaces options show, well, only the leaf change.
176 And it goes like this:
177
178 $ 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
184 one impacted interface:
185 function void fn(C&)
186 $
187
188 Note how the report ends up by showing the list of interfaces
189 impacted by the leaf change. That’s the effect of the additional
190 --impacted-interfaces option.
191
192 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
196 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
201 · --impacted-interfaces
202
203 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
208 · --full-impact|-f
209
210 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
214 $ 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
218 1 function with some indirect sub-type change:
219
220 [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
231 $
232
233 · --redundant
234 In the diff reports, do display redundant changes. A redundant
235 change is a change that has been displayed elsewhere in a given
236 report.
237
238 · --harmless
239
240 In the diff report, display only the harmless changes. By
241 default, the harmless changes are filtered out of the diff report
242 keep the clutter to a minimum and have a greater chance to spot
243 real ABI issues.
244
245 · --no-linkage-name
246
247 In the resulting report, do not display the linkage names of the
248 added, removed, or changed functions or variables.
249
250 · --no-added-syms
251
252 Do not show the list of functions, variables, or any symbol that
253 was added.
254
255 · --no-added-binaries
256
257 Do not show the list of binaries that got added to the second
258 package.
259
260 Please note that the presence of such added binaries is not con‐
261 sidered like an ABI change by this tool; as such, it doesn’t have
262 any impact on the exit code of the tool. It does only have an
263 informational value. Removed binaries are, however, considered as
264 an ABI change.
265
266 · --no-abignore
267
268 Do not search the package for the presence of suppression files.
269
270 · --no-parallel
271
272 By default, abipkgdiff will use all the processors it has avail‐
273 able to execute concurrently. This option tells it not to extract
274 packages or run comparisons in parallel.
275
276 · --no-default-suppression
277
278 Do not load the default suppression specification files.
279
280 · --suppressions | --suppr <path-to-suppressions>
281
282 Use a suppression specification file located at path-to-suppres‐
283 sions. Note that this option can appear multiple times on the
284 command line. In that case, all of the suppression specification
285 files are taken into account.
286
287 Please note that, by default, if this option is not provided, then
288 the default suppression specification files are loaded .
289
290 · --linux-kernel-abi-whitelist | -w <path-to-whitelist>
291
292 When comparing two Linux kernel RPM packages, this option points
293 to the white list of names of ELF symbols of functions and vari‐
294 ables that must be compared for ABI changes. That white list is
295 called a “Linux kernel ABI white list”.
296
297 Any other function or variable which ELF symbol are not present in
298 that white list will not be considered by the ABI comparison
299 process.
300
301 If this option is not provided – thus if no white list is provided
302 – then the ABI of all publicly defined and exported functions and
303 global variables by the Linux Kernel binaries are compared.
304
305 Please note that if a white list package is given in parameter,
306 this option handles it just fine, like if the –wp option was used.
307
308 · --wp <path-to-whitelist-package>
309
310 When comparing two Linux kernel RPM packages, this option points
311 an RPM package containining several white lists of names of ELF
312 symbols of functions and variables that must be compared for ABI
313 changes. Those white lists are called “Linux kernel ABI white
314 lists”.
315
316 From the content of that white list package, this program then
317 chooses the appropriate Linux kernel ABI white list to consider
318 when comparing the ABI of Linux kernel binaries contained in the
319 Linux kernel packages provided on the command line.
320
321 That choosen Linux kernel ABI white list contains the list of
322 names of ELF symbols of functions and variables that must be com‐
323 pared for ABI changes.
324
325 Any other function or variable which ELF symbol are not present in
326 that white list will not be considered by the ABI comparison
327 process.
328
329 Note that this option can be provided twice (not mor than twice),
330 specifying one white list package for each Linux Kernel package
331 that is provided on the command line.
332
333 If this option is not provided – thus if no white list is provided
334 – then the ABI of all publicly defined and exported functions and
335 global variables by the Linux Kernel binaries are compared.
336
337 · --no-unreferenced-symbols
338
339 In the resulting report, do not display change information about
340 function and variable symbols that are not referenced by any debug
341 information. Note that for these symbols not referenced by any
342 debug information, the change information displayed is either
343 added or removed symbols.
344
345 · --no-show-locs
346 Do not show information about where in the second shared library
347 the respective type was changed.
348
349 · --show-bytes
350
351 Show sizes and offsets in bytes, not bits. By default, sizes and
352 offsets are shown in bits.
353
354 · --show-bits
355
356 Show sizes and offsets in bits, not bytes. This option is acti‐
357 vated by default.
358
359 · --show-hex
360
361 Show sizes and offsets in hexadecimal base.
362
363 · --show-dec
364
365 Show sizes and offsets in decimal base. This option is activated
366 by default.
367
368 · --no-show-relative-offset-changes
369
370 Without this option, when the offset of a data member changes, the
371 change report not only mentions the older and newer offset, but it
372 also mentions by how many bits the data member changes. With this
373 option, the latter is not shown.
374
375 · --show-identical-binaries
376 Show the names of the all binaries compared, including the bina‐
377 ries whose ABI compare equal. By default, when this option is
378 not provided, only binaries with ABI changes are mentionned in
379 the output.
380
381 · --fail-no-dbg
382
383 Make the program fail and return a non-zero exit code if couldn’t
384 read any of the debug information that comes from the debug info
385 packages that were given on the command line. If no debug info
386 package were provided on the command line then this option is not
387 active.
388
389 Note that the non-zero exit code returned by the program as a
390 result of this option is the constant ABIDIFF_ERROR. To know the
391 numerical value of that constant, please refer to the exit code
392 documentation.
393
394 · --keep-tmp-files
395
396 Do not erase the temporary directory files that are created during
397 the execution of the tool.
398
399 · --verbose
400
401 Emit verbose progress messages.
402
404 The exit code of the abipkgdiff command is either 0 if the ABI of the
405 binaries compared are equal, or non-zero if they differ or if the tool
406 encountered an error.
407
408 In the later case, the value of the exit code is the same as for the
409 abidiff tool.
410
412 Dodji Seketeli
413
415 2014-2016, Red Hat, Inc.
416
417
418
419
420 Mar 29, 2019 ABIPKGDIFF(1)