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.
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

RETURN VALUE

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

AUTHOR

412       Dodji Seketeli
413
415       2014-2016, Red Hat, Inc.
416
417
418
419
420                                 Mar 29, 2019                    ABIPKGDIFF(1)
Impressum