1ABIPKGDIFF(1)                     Libabigail                     ABIPKGDIFF(1)
2
3
4

NAME

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

INVOCATION

19          abipkgdiff [option] <package1> <package2>
20
21       package1  and package2 are the packages that contain the binaries to be
22       compared.
23

ENVIRONMENT

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

OPTIONS

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.  This option implies --redundant
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          · --non-reachable-types|-t
234
235            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
239            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
246            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
251            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
255          · --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
260          · --harmless
261
262            In  the  diff  report,  display  only  the  harmless  changes.  By
263            default, 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
267          · --no-linkage-name
268
269            In the resulting report, do not display the linkage names  of  the
270            added, removed, or changed functions or variables.
271
272          · --no-added-syms
273
274            Do  not  show the list of functions, variables, or any symbol that
275            was added.
276
277          · --no-added-binaries
278
279            Do not show the list of binaries that  got  added  to  the  second
280            package.
281
282            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
285            informational value.  Removed binaries are, however, considered as
286            an ABI change.
287
288          · --no-abignore
289
290            Do not search the package for the presence of suppression files.
291
292          · --no-parallel
293
294            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
298          · --no-default-suppression
299
300            Do not load the default suppression specification files.
301
302          · --suppressions | --suppr <path-to-suppressions>
303
304            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
309            Please note that, by default, if this option is not provided, then
310            the default suppression specification files are loaded .
311
312          · --linux-kernel-abi-whitelist | -w <path-to-whitelist>
313
314            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
319            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
323            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
327            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
330          · --wp <path-to-whitelist-package>
331
332            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
338            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
343            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
347            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
351            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
355            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
359          · --no-unreferenced-symbols
360
361            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
367          · --no-show-locs
368              Do not show information about where in the second shared library
369              the respective type was changed.
370
371          · --show-bytes
372
373            Show  sizes and offsets in bytes, not bits.  By default, sizes and
374            offsets are shown in bits.
375
376          · --show-bits
377
378            Show sizes and offsets in bits, not bytes.  This option  is  acti‐
379            vated by default.
380
381          · --show-hex
382
383            Show sizes and offsets in hexadecimal base.
384
385          · --show-dec
386
387            Show  sizes and offsets in decimal base.  This option is activated
388            by default.
389
390          · --no-show-relative-offset-changes
391
392            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
397          · --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
403          · --fail-no-dbg
404
405            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
411            Note that the non-zero exit code returned  by  the  program  as  a
412            result  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
416          · --keep-tmp-files
417
418            Do not erase the temporary directory files that are created during
419            the execution of the tool.
420
421          · --verbose
422
423            Emit verbose progress messages.
424
425          · self-check
426
427            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
437                $ 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

RETURN VALUE

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
446       In the later case, the value of the exit code is the same  as  for  the
447       abidiff tool.
448

AUTHOR

450       Dodji Seketeli
451
453       2014-2021, Red Hat, Inc.
454
455
456
457
458                                 Feb 25, 2021                    ABIPKGDIFF(1)
Impressum