You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
490 lines
18 KiB
490 lines
18 KiB
.. _abipkgdiff_label:
|
|
|
|
===========
|
|
abipkgdiff
|
|
===========
|
|
|
|
``abipkgdiff`` compares the Application Binary Interfaces (ABI) of the
|
|
`ELF`_ binaries contained in two software packages. The software
|
|
package formats currently supported are `Deb`_, `RPM`_, `tar`_
|
|
archives (either compressed or not) and plain directories that contain
|
|
binaries.
|
|
|
|
For a comprehensive ABI change report that includes changes about
|
|
function and variable sub-types, the two input packages must be
|
|
accompanied with their debug information packages that contain debug
|
|
information in `DWARF`_ format.
|
|
|
|
|
|
.. _abipkgdiff_invocation_label:
|
|
|
|
Invocation
|
|
==========
|
|
|
|
::
|
|
|
|
abipkgdiff [option] <package1> <package2>
|
|
|
|
``package1`` and ``package2`` are the packages that contain the
|
|
binaries to be compared.
|
|
|
|
|
|
Environment
|
|
===========
|
|
|
|
.. _abipkgdiff_default_supprs_label:
|
|
|
|
abipkgdiff loads two default :ref:`suppression specifications files
|
|
<suppr_spec_label>`, merges their content and use it to filter out ABI
|
|
change reports that might be considered as false positives to users.
|
|
|
|
* Default system-wide suppression specification file
|
|
|
|
It's located by the optional environment variable
|
|
LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment
|
|
variable is not set, then abipkgdiff tries to load the suppression file
|
|
$libdir/libabigail/libabigail-default.abignore. If that file is not
|
|
present, then no default system-wide suppression specification file
|
|
is loaded.
|
|
|
|
* Default user suppression specification file.
|
|
|
|
It's located by the optional environment
|
|
LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. If that environment
|
|
variable is not set, then abipkgdiff tries to load the suppression file
|
|
$HOME/.abignore. If that file is not present, then no default user
|
|
suppression specification is loaded.
|
|
|
|
In addition to those default suppression specification files,
|
|
abipkgdiff will also look inside the packages being compared and if it
|
|
sees a file that ends with the extension ``.abignore``, then it will
|
|
consider it as a suppression specification and it will combine it to the
|
|
default suppression specification that might be already loaded.
|
|
|
|
The user might as well use the ``--suppressions`` option (that is
|
|
documented further below) to provide a suppression specification.
|
|
|
|
.. _abipkgdiff_options_label:
|
|
|
|
Options
|
|
=======
|
|
|
|
* ``--help | -h``
|
|
|
|
Display a short help about the command and exit.
|
|
|
|
* `--version | -v`
|
|
|
|
Display the version of the program and exit.
|
|
|
|
* ``--debug-info-pkg1 | --d1`` <path>
|
|
|
|
For cases where the debug information for *package1* is split out
|
|
into a separate file, tells ``abipkgdiff`` where to find that
|
|
separate debug information package.
|
|
|
|
Note that the debug info for *package1* can have been split into
|
|
several different debug info packages. In that case, several
|
|
instances of this options can be provided, along with those
|
|
several different debug info packages.
|
|
|
|
* ``--debug-info-pkg2 | --d2`` <path>
|
|
|
|
For cases where the debug information for *package2* is split out
|
|
into a separate file, tells ``abipkgdiff`` where to find that
|
|
separate debug information package.
|
|
|
|
Note that the debug info for *package2* can have been split into
|
|
several different debug info packages. In that case, several
|
|
instances of this options can be provided, along with those
|
|
several different debug info packages.
|
|
|
|
* ``--devel-pkg1 | --devel1`` <path>
|
|
|
|
Specifies where to find the `Development Package`_ associated with
|
|
the first package to be compared. That `Development Package`_ at
|
|
``path`` should at least contain header files in which public
|
|
types exposed by the libraries (of the first package to be
|
|
compared) are defined. When this option is provided, the tool
|
|
filters out reports about ABI changes to types that are *NOT*
|
|
defined in these header files.
|
|
|
|
* ``--devel-pkg2 | --devel2`` <path>
|
|
|
|
Specifies where to find the `Development Package`_ associated with
|
|
the second package to be compared. That `Development Package`_ at
|
|
``path`` should at least contains header files in which public
|
|
types exposed by the libraries (of the second package to be
|
|
compared) are defined. When this option is provided, the tool
|
|
filters out reports about ABI changes to types that are *NOT*
|
|
defined in these header files.
|
|
|
|
* ``--drop-private-types``
|
|
|
|
This option is to be used with the ``--devel-pkg1`` and
|
|
``--devel-pkg2`` options. With this option, types that are *NOT*
|
|
defined in the headers are entirely dropped from the internal
|
|
representation build by Libabigail to represent the ABI. They
|
|
thus don't have to be filtered out from the final ABI change
|
|
report because they are not even present in Libabigail's
|
|
representation.
|
|
|
|
Without this option however, those private types are kept in the
|
|
internal representation and later filtered out from the report.
|
|
|
|
This options thus potentially makes Libabigail consume less
|
|
memory. It's meant to be mainly used to optimize the memory
|
|
consumption of the tool on binaries with a lot of publicly defined
|
|
and exported types.
|
|
|
|
* ``--dso-only``
|
|
|
|
Compare ELF files that are shared libraries, only. Do not compare
|
|
executable files, for instance.
|
|
|
|
* ``--private-dso``
|
|
|
|
By default, ``abipkgdiff`` does not compare DSOs that are private
|
|
to the RPM package. A private DSO is a DSO which SONAME is *NOT*
|
|
advertised in the "provides" property of the RPM.
|
|
|
|
This option instructs ``abipkgdiff`` to *also* compare DSOs that
|
|
are *NOT* advertised in the "provides" property of the RPM.
|
|
|
|
Please note that the fact that (by default) ``abipkgdiff`` skips
|
|
private DSO is a feature that is available only for RPMs, at the
|
|
moment. We would happily accept patches adding that feature for
|
|
other package formats.
|
|
|
|
* ``--leaf-changes-only|-l`` only show leaf changes, so don't show
|
|
impact analysis report. This option implies ``--redundant``
|
|
|
|
The typical output of ``abipkgdiff`` and ``abidiff`` when
|
|
comparing two binaries, that we shall call ``full impact report``,
|
|
looks like this ::
|
|
|
|
$ abidiff libtest-v0.so libtest-v1.so
|
|
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
|
|
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
|
|
|
|
1 function with some indirect sub-type change:
|
|
|
|
[C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
|
|
parameter 1 of type 'C&' has sub-type changes:
|
|
in referenced type 'struct C' at test-v1.cc:7:1:
|
|
type size hasn't changed
|
|
1 data member change:
|
|
type of 'leaf* C::m0' changed:
|
|
in pointed to type 'struct leaf' at test-v1.cc:1:1:
|
|
type size changed from 32 to 64 bits
|
|
1 data member insertion:
|
|
'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
|
|
|
|
$
|
|
|
|
So in that example the report emits information about how the data
|
|
member insertion change of "struct leaf" is reachable from
|
|
function "void fn(C&)". In other words, the report not only shows
|
|
the data member change on "struct leaf", but it also shows the
|
|
impact of that change on the function "void fn(C&)".
|
|
|
|
In abidiff (and abipkgdiff) parlance, the change on "struct leaf"
|
|
is called a leaf change. So the ``--leaf-changes-only
|
|
--impacted-interfaces`` options show, well, only the leaf change.
|
|
And it goes like this: ::
|
|
|
|
$ abidiff -l libtest-v0.so libtest-v1.so
|
|
'struct leaf' changed:
|
|
type size changed from 32 to 64 bits
|
|
1 data member insertion:
|
|
'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
|
|
|
|
one impacted interface:
|
|
function void fn(C&)
|
|
$
|
|
|
|
Note how the report ends up by showing the list of interfaces
|
|
impacted by the leaf change. That's the effect of the additional
|
|
``--impacted-interfaces`` option.
|
|
|
|
Now if you don't want to see that list of impacted interfaces,
|
|
then you can just avoid using the ``--impacted-interface`` option.
|
|
You can learn about that option below, in any case.
|
|
|
|
Please note that when comparing two Linux Kernel packages, it's
|
|
this ``leaf changes report`` that is emitted, by default. The
|
|
normal so-called ``full impact report`` can be emitted with the
|
|
option ``--full-impact`` which is documented later below.
|
|
|
|
|
|
* ``--impacted-interfaces``
|
|
|
|
When showing leaf changes, this option instructs abipkgdiff to
|
|
show the list of impacted interfaces. This option is thus to be
|
|
used in addition to the ``--leaf-changes-only`` option, or, when
|
|
comparing two Linux Kernel packages. Otherwise, it's simply
|
|
ignored.
|
|
|
|
* ``--full-impact|-f``
|
|
|
|
When comparing two Linux Kernel packages, this function instructs
|
|
``abipkgdiff`` to emit the so-called ``full impact report``, which
|
|
is the default report kind emitted by the ``abidiff`` tool: ::
|
|
|
|
$ abidiff libtest-v0.so libtest-v1.so
|
|
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
|
|
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
|
|
|
|
1 function with some indirect sub-type change:
|
|
|
|
[C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
|
|
parameter 1 of type 'C&' has sub-type changes:
|
|
in referenced type 'struct C' at test-v1.cc:7:1:
|
|
type size hasn't changed
|
|
1 data member change:
|
|
type of 'leaf* C::m0' changed:
|
|
in pointed to type 'struct leaf' at test-v1.cc:1:1:
|
|
type size changed from 32 to 64 bits
|
|
1 data member insertion:
|
|
'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
|
|
|
|
$
|
|
|
|
|
|
* ``--non-reachable-types|-t``
|
|
|
|
Analyze and emit change reports for all the types of the binary,
|
|
including those that are not reachable from global functions and
|
|
variables.
|
|
|
|
This option might incur some serious performance degradation as
|
|
the number of types analyzed can be huge. However, if paired with
|
|
the ``--devel-pkg{1,2}`` options, the additional non-reachable
|
|
types analyzed are restricted to those defined in the public
|
|
headers files carried by the referenced development packages, thus
|
|
hopefully making the performance hit acceptable.
|
|
|
|
Also, using this option alongside suppression specifications (by
|
|
also using the ``--suppressions`` option) might help keep the number of
|
|
analyzed types (and the potential performance degradation) in
|
|
control.
|
|
|
|
Note that without this option, only types that are reachable from
|
|
global functions and variables are analyzed, so the tool detects
|
|
and reports changes on these reachable types only.
|
|
|
|
* ``--redundant``
|
|
|
|
In the diff reports, do display redundant changes. A redundant
|
|
change is a change that has been displayed elsewhere in a given
|
|
report.
|
|
|
|
* ``--harmless``
|
|
|
|
In the diff report, display only the :ref:`harmless
|
|
<harmlesschangeconcept_label>` changes. By default, the harmless
|
|
changes are filtered out of the diff report keep the clutter to a
|
|
minimum and have a greater chance to spot real ABI issues.
|
|
|
|
* ``--no-linkage-name``
|
|
|
|
In the resulting report, do not display the linkage names of
|
|
the added, removed, or changed functions or variables.
|
|
|
|
* ``--no-added-syms``
|
|
|
|
Do not show the list of functions, variables, or any symbol that
|
|
was added.
|
|
|
|
* ``--no-added-binaries``
|
|
|
|
Do not show the list of binaries that got added to the second
|
|
package.
|
|
|
|
Please note that the presence of such added binaries is not
|
|
considered like an ABI change by this tool; as such, it doesn't
|
|
have any impact on the exit code of the tool. It does only have
|
|
an informational value. Removed binaries are, however, considered
|
|
as an ABI change.
|
|
|
|
* ``--no-abignore``
|
|
|
|
Do not search the package for the presence of suppression files.
|
|
|
|
* ``--no-parallel``
|
|
|
|
By default, ``abipkgdiff`` will use all the processors it has available to
|
|
execute concurrently. This option tells it not to extract packages or run
|
|
comparisons in parallel.
|
|
|
|
* ``--no-default-suppression``
|
|
|
|
Do not load the :ref:`default suppression specification files
|
|
<abipkgdiff_default_supprs_label>`.
|
|
|
|
* ``--suppressions | --suppr`` <*path-to-suppressions*>
|
|
|
|
Use a :ref:`suppression specification <suppr_spec_label>` file
|
|
located at *path-to-suppressions*. Note that this option can
|
|
appear multiple times on the command line. In that case, all of
|
|
the suppression specification files are taken into account.
|
|
|
|
Please note that, by default, if this option is not provided, then
|
|
the :ref:`default suppression specification files
|
|
<abipkgdiff_default_supprs_label>` are loaded .
|
|
|
|
* ``--linux-kernel-abi-whitelist | -w`` <*path-to-whitelist*>
|
|
|
|
When comparing two Linux kernel RPM packages, this option points
|
|
to the white list of names of ELF symbols of functions and
|
|
variables that must be compared for ABI changes. That white list
|
|
is called a "Linux kernel ABI white list".
|
|
|
|
Any other function or variable which ELF symbol are not present in
|
|
that white list will not be considered by the ABI comparison
|
|
process.
|
|
|
|
If this option is not provided -- thus if no white list is
|
|
provided -- then the ABI of all publicly defined and exported
|
|
functions and global variables by the Linux Kernel binaries are
|
|
compared.
|
|
|
|
Please note that if a white list package is given in parameter,
|
|
this option handles it just fine, like if the --wp option was
|
|
used.
|
|
|
|
* ``--wp`` <*path-to-whitelist-package*>
|
|
|
|
When comparing two Linux kernel RPM packages, this option points
|
|
an RPM package containining several white lists of names of ELF
|
|
symbols of functions and variables that must be compared for ABI
|
|
changes. Those white lists are called "Linux kernel ABI white
|
|
lists".
|
|
|
|
From the content of that white list package, this program then
|
|
chooses the appropriate Linux kernel ABI white list to consider
|
|
when comparing the ABI of Linux kernel binaries contained in the
|
|
Linux kernel packages provided on the command line.
|
|
|
|
That choosen Linux kernel ABI white list contains the list of
|
|
names of ELF symbols of functions and variables that must be
|
|
compared for ABI changes.
|
|
|
|
Any other function or variable which ELF symbol are not present in
|
|
that white list will not be considered by the ABI comparison
|
|
process.
|
|
|
|
Note that this option can be provided twice (not mor than twice),
|
|
specifying one white list package for each Linux Kernel package
|
|
that is provided on the command line.
|
|
|
|
If this option is not provided -- thus if no white list is
|
|
provided -- then the ABI of all publicly defined and exported
|
|
functions and global variables by the Linux Kernel binaries are
|
|
compared.
|
|
|
|
* ``--no-unreferenced-symbols``
|
|
|
|
In the resulting report, do not display change information about
|
|
function and variable symbols that are not referenced by any debug
|
|
information. Note that for these symbols not referenced by any
|
|
debug information, the change information displayed is either
|
|
added or removed symbols.
|
|
|
|
* ``--no-show-locs``
|
|
|
|
Do not show information about where in the *second shared library*
|
|
the respective type was changed.
|
|
|
|
* ``--show-bytes``
|
|
|
|
Show sizes and offsets in bytes, not bits. By default, sizes and
|
|
offsets are shown in bits.
|
|
|
|
* ``--show-bits``
|
|
|
|
Show sizes and offsets in bits, not bytes. This option is
|
|
activated by default.
|
|
|
|
* ``--show-hex``
|
|
|
|
Show sizes and offsets in hexadecimal base.
|
|
|
|
* ``--show-dec``
|
|
|
|
Show sizes and offsets in decimal base. This option is activated
|
|
by default.
|
|
|
|
* ``--no-show-relative-offset-changes``
|
|
|
|
Without this option, when the offset of a data member changes,
|
|
the change report not only mentions the older and newer offset,
|
|
but it also mentions by how many bits the data member changes.
|
|
With this option, the latter is not shown.
|
|
|
|
* ``--show-identical-binaries``
|
|
|
|
Show the names of the all binaries compared, including the
|
|
binaries whose ABI compare equal. By default, when this option is
|
|
not provided, only binaries with ABI changes are mentionned in the
|
|
output.
|
|
|
|
* ``--fail-no-dbg``
|
|
|
|
Make the program fail and return a non-zero exit code if couldn't
|
|
read any of the debug information that comes from the debug info
|
|
packages that were given on the command line. If no debug info
|
|
package were provided on the command line then this option is not
|
|
active.
|
|
|
|
Note that the non-zero exit code returned by the program as a
|
|
result of this option is the constant ``ABIDIFF_ERROR``. To know
|
|
the numerical value of that constant, please refer to the
|
|
:ref:`exit code documentation <abidiff_return_value_label>`.
|
|
|
|
* ``--keep-tmp-files``
|
|
|
|
Do not erase the temporary directory files that are created during
|
|
the execution of the tool.
|
|
|
|
* ``--verbose``
|
|
|
|
Emit verbose progress messages.
|
|
|
|
|
|
* ``self-check``
|
|
|
|
This is used to test the underlying Libabigail library. When in
|
|
used, the command expects only on input package, along with its
|
|
associated debug info packages. The command then compares each
|
|
binary inside the package against its own ABIXML
|
|
representation. The result of the comparison should yield the
|
|
empty set if Libabigail behaves correctly. Otherwise, it means
|
|
there is an issue that ought to be fixed. This option is used by
|
|
people interested in Libabigail development for regression testing
|
|
purposes. Here is an example of the use of this option: ::
|
|
|
|
$ 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
|
|
==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
|
|
$
|
|
|
|
.. _abipkgdiff_return_value_label:
|
|
|
|
Return value
|
|
============
|
|
|
|
The exit code of the ``abipkgdiff`` command is either 0 if the ABI of
|
|
the binaries compared are equal, or non-zero if they differ or if the
|
|
tool encountered an error.
|
|
|
|
In the later case, the value of the exit code is the same as for the
|
|
:ref:`abidiff tool <abidiff_return_value_label>`.
|
|
|
|
|
|
.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
|
|
.. _RPM: https://en.wikipedia.org/wiki/RPM_Package_Manager
|
|
.. _Deb: https://en.wikipedia.org/wiki/Deb_%28file_format%29
|
|
.. _tar: https://en.wikipedia.org/wiki/Tar_%28computing%29
|
|
.. _DWARF: http://www.dwarfstd.org
|
|
.. _Development Package: https://fedoraproject.org/wiki/Packaging:Guidelines?rd=Packaging/Guidelines#Devel_Packages
|