1.. _fedabipkgdiff_label:
2
3==============
4fedabipkgdiff
5==============
6
7``fedabipkgdiff`` compares the ABI of shared libraries in `Fedora`_
8packages.  It's a convenient way to do so without having to manually
9download packages from the `Fedora Build System`_.
10
11``fedabipkgdiff`` knows how to talk with the `Fedora Build System`_ to
12find the right packages versions, their associated debug information
13and development packages, download them, compare their ABI locally,
14and report about the possible ABI changes.
15
16Note that by default, this tool reports ABI changes about types that
17are defined in public header files found in the development packages
18associated with the packages being compared.  It also reports ABI
19changes about functions and global variables whose symbols are defined
20and exported in the ELF binaries found in the packages being compared.
21
22.. _fedabipkgdiff_invocation_label:
23
24Invocation
25==========
26
27::
28
29   fedabipkgdiff [option] <NVR> ...
30
31Environment
32===========
33
34.. _fedabipkgdiff_default_supprs_label:
35
36fedabipkgdiff loads two default :ref:`suppression specifications files
37<suppr_spec_label>`, merges their content and use it to filter out ABI
38change reports that might be considered as false positives to users.
39
40* Default system-wide suppression specification file
41
42  It's located by the optional environment variable
43  LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE.  If that environment
44  variable is not set, then fedabipkgdiff tries to load the
45  suppression file $libdir/libabigail/libabigail-default.abignore.  If
46  that file is not present, then no default system-wide suppression
47  specification file is loaded.
48
49* Default user suppression specification file.
50
51  It's located by the optional environment
52  LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE.  If that environment
53  variable is not set, then fedabipkgdiff tries to load the
54  suppression file $HOME/.abignore.  If that file is not present, then
55  no default user suppression specification is loaded.
56
57
58.. _fedabipkgdiff_options_label:
59
60Options
61=======
62
63  * ``--help | -h``
64
65    Display a short help about the command and exit.
66
67  * ``--dry-run``
68
69    Don't actually perform the ABI comparison.  Details about what is
70    going to be done are emitted on standard output.
71
72  * ``--debug``
73
74    Emit debugging messages about the execution of the program.
75    Details about each method invocation, including input parameters
76    and returned values, are emitted.
77
78  * ``--traceback``
79
80    Show traceback when an exception raised. This is useful for
81    developers of the tool itself to know more exceptional errors.
82
83  * ``--server`` <URL>
84
85    Specifies the URL of the `Koji`_ XMLRPC service the tool talks to.
86    The default value of this option is http://koji.fedoraproject.org/kojihub.
87
88  * ``--topurl`` <URL>
89
90    Specifies the URL of the package store the tool downloads RPMs
91    from.  The default value of this option is https://kojipkgs.fedoraproject.org.
92
93  * ``--from`` <distro>
94
95    Specifies the name of the baseline `Fedora`_ distribution in which to
96    find the first `build`_ that is used for comparison. The
97    ``distro`` value can be any valid value of the RPM macro
98    ``%{?dist}`` for `Fedora`_, for example, ``fc4``, ``fc23``, ``fc25``.
99
100  * ``--to`` <distro>
101
102    Specifies the name of the `Fedora`_ distribution in which to find
103    the `build`_ that is compared against the baseline specified by
104    option ``--from``.  The ``distro`` value could be any valid value
105    of the RPM macro ``%{?dist}`` for `Fedora`_, for example, ``fc4``,
106    ``fc23``.
107
108  * ``--all-subpackages``
109
110    Instructs the tool to also compare the ABI of the binaries in the
111    sub-packages of the packages specified.
112
113  * ``--dso-only``
114
115    Compares the ABI of shared libraries only.  If this option is not
116    provided, the tool compares the ABI of all ELF binaries found in
117    the packages.
118
119  * ``--suppressions`` <*path-to-suppresions*>
120
121    Use a :ref:`suppression specification <suppr_spec_label>` file
122    located at *path-to-suppressions*.
123
124
125  * ``--no-default-suppression``
126
127    Do not load the :ref:`default suppression specification files
128    <fedabipkgdiff_default_supprs_label>`.
129
130  * ``--no-devel-pkg``
131
132    Do not take associated development packages into account when
133    performing the ABI comparison.  This makes the tool report ABI
134    changes about all types that are reachable from functions and
135    global variables which symbols are defined and publicly exported
136    in the binaries being compared, even if those types are not
137    defined in public header files available from the packages being
138    compared.
139
140  * ``--show-identical-binaries``
141
142   Show the names of the all binaries compared, including the
143   binaries whose ABI compare equal.  By default, when this option is
144   not provided, only binaries with ABI changes are mentionned in the
145   output.
146
147  * ``--abipkgdiff`` <path/to/abipkgdiff>
148
149    Specify an alternative abipkgdiff instead of the one installed in system.
150
151  * ``--clean-cache-before``
152
153    Clean cache before ABI comparison.
154
155  * ``--clean-cache-after``
156
157    Clean cache after ABI comparison.
158
159  * ``--clean-cache``
160
161    If you want to clean cache both before and after ABI comparison,
162    ``--clean-cache`` is the convenient way for you to save typing of two
163    options at same time.
164
165.. _build:
166
167Note that a build is a specific version and release of an RPM package.
168It's specified by its the package name, version and release. These are specified
169by the `Fedora Naming Guidelines <https://fedoraproject.org/wiki/Packaging:NamingGuidelines>`_
170
171
172.. _fedabipkgdiff_return_value_label:
173
174Return value
175============
176
177The exit code of the ``abipkgdiff`` command is either 0 if the ABI of
178the binaries compared are equivalent, or non-zero if they differ or if
179the tool encountered an error.
180
181In the later case, the value of the exit code is the same as for the
182:ref:`abidiff tool <abidiff_return_value_label>`.
183
184.. _fedabipkgdiff_usage_example_label:
185
186
187Use cases
188=========
189
190Below are some usage examples currently supported by
191``fedabipkgdiff``.
192
193  1. Compare the ABI of binaries in a local package against the ABI of
194     the latest stable package in `Fedora`_ 23.
195
196     Suppose you have built just built the ``httpd`` package and you
197     want to compare the ABI of the binaries in this locally built
198     package against the ABI of the binaries in the latest ``http``
199     build from `Fedora`_ 23.  The command line invocation would be: ::
200
201       $ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
202
203  2. Compare the ABI of binaries in two local packages.
204
205     Suppose you have built two versions of package httpd, and you want to see
206     what ABI differences between these two versions of RPM files. The
207     command line invocation would be::
208
209       $ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
210
211     All what fedabipkgdiff does happens on local machine without the need of
212     querying or downloading RPMs from Koji.
213
214  3. Compare the ABI of binaries in the latest build of the ``httpd``
215     package in ``Fedora 23`` against the ABI of the binaries in the
216     latest build of the same package in 24.
217
218     In this case, note that neither of the two packages are available
219     locally.  The tool is going to talk with the `Fedora Build
220     System`_, determine what the versions and releases of the latest
221     packages are, download them and perform the comparison locally.
222     The command line invocation would be: ::
223
224       $ fedabipkgdiff --from fc23 --to fc24 httpd
225
226  4. Compare the ABI of binaries of two builds of the ``httpd``
227     package, designated their versions and releases.
228
229     If we want to do perform the ABI comparison for all the processor
230     architectures supported by `Fedora`_ the command line invocation
231     would be: ::
232
233       $ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
234
235     But if we want to perform the ABI comparison for a specific
236     architecture, say, x86_64, then the command line invocation would
237     be: ::
238
239       $ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
240
241  5. If the use wants to also compare the sub-packages of a given
242     package, she can use the --all-subpackages option.  The first
243     command of the previous example would thus look like: ::
244
245       $ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
246
247.. _Fedora: https://getfedora.org
248.. _Fedora Build System: http://koji.fedoraproject.org/koji
249.. _Koji: https://fedoraproject.org/wiki/Koji
250