RepoMirrors/libabigail
1
0
Fork 0
mirror of git://sourceware.org/git/libabigail.git synced 2025-02-18 23:07:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
783099cd25
libabigail/doc/manuals/fedabipkgdiff.rst
Chenxiong Qi 783099cd25 Bug 20380 - Compare two local RPMs 
Bug 20270 is also fixed.

This patch allows developer to compare two local RPMs in form

    fedabipkgdiff some/place/foo.rpm another/place/bar.rpm

But, network is still needed to talk with Koji.

This patch also introduces new terms for libabigail, that is the
subject, ancillary package, and comparison half. Subject represents a
package that is subject of the ABI comparison, a subject could be a RPM
and maybe it would be a DEB or some other kind of "package". A subject
may have several ancillary packages that are used to compare the
subject.  Generally, a subject may have devel, debuginfo, or both.

	* configure.ac: add dependent mimetype module.
	* doc/manuals/fedabipkgdiff.rst: Update to add document for the
	new use case of comparing two local RPMs.
	* tests/data/Makefile.am: Include new RPMs for tests.
	* tests/data/test-fedabipkgdiff/dbus-glib/dbus-glib-0.100.2-2.fc20.x86_64.rpm:
	New RPM for running test.
	* tests/data/test-fedabipkgdiff/dbus-glib/dbus-glib-0.106-1.fc23.x86_64.rpm:
	Likewise.
	* tests/data/test-fedabipkgdiff/nss-util/nss-util-3.12.6-1.fc14.x86_64.rpm:
	Likewise.
	* tests/data/test-fedabipkgdiff/nss-util/nss-util-3.24.0-2.0.fc25.x86_64.rpm:
	Likewise.
	* tests/data/test-fedabipkgdiff/nss-util/nss-util-devel-3.24.0-2.0.fc25.x86_64.rpm:
	Likewise.
	* tests/data/test-fedabipkgdiff/test4-glib-0.100.2-2.fc20.x86_64.rpm-glib-0.106-1.fc23.x86_64.rpm-report-0.txt:
	Rename filename by adding .rpm extension.
	* tests/data/test-fedabipkgdiff/test5-same-dir-dbus-glib-0.100.2-2.fc20.x86_64--dbus-glib-0.106-1.fc23.x86_64-report-0.txt:
	New reference output for testing comparing local RPMs.
	* tests/data/test-fedabipkgdiff/test6-missing-devel-debuginfo-nss-util-3.12.6-1.fc14.x86_64--nss-util-3.24.0-2.0.fc25.x86_64-report-0.txt:
	New reference output for testing comparison without non-existent
	debuginfo or development package.
	* tests/runtestfedabipkgdiff.py.in (FEDABIPKGDIFF_TEST_SPECS):
	Rename filename for test4. Add two new test cases.
	(run_fedabipkgdiff_tests): Remove semicolon and trailing
	whitespaces.
	(main): Likewise.
	(ensure_output_dir_created): Likewise.
	* tools/fedabipkgdiff: Require some new modules.
	Fix of return code.
	(PkgInfo): Renamed to ComparisonHalf.
	(match_nvr): New method to determine if a string matches format
	of N-V-R.
	(match_nvra): New method to determine if a string matches format
	of N-V-R.A.
	(is_rpm_file): New method to guess if a file is a RPM file.
	(RPM.is_peer): New method to determine if current RPM is a peer
	of another.
	(RPM.filename): Use Koji module API to construct the filename.
	(RPM.nvra): Get nvra from filename instead of constructing
	manually that is duplicated with Koji module API.
	(RPMCollection): New class to represent a set of RPMs.
	(generate_pkg_info_pair_for_abipkgdiff): New method working as a
	generator to yeild comparison halves for running abipkgdiff.
	(Brew.getRPM): Fix string format with incorrect argument.
	(Brew.select_rpms_from_a_build): Return instance of
	RPMCollection.
	(abipkgdiff): If there is no debuginfo or development package,
	just ignore it and leave a warning. If --error-on-warning is
	specified, raise an exception instead. Arguments are modified
	to represent the new name ComparisonHalf, and relative docstring
	is also updated.
	(magic_construct): Removed.
	(run_abipkgdiff): Rewrite.
	(make_rpms_usable_for_abipkgdiff): Removed.
	(diff_local_rpm_with_latest_rpm_from_koji): Rewrite by using
	RPMCollection.
	(diff_latest_rpms_based_on_distros): Likewise.
	(diff_two_nvras_from_koji): Likewise.
	(diff_from_two_rpm_files): New method to compare two local RPMs.
	(build_commandline_args_parser): Add new option
	--error-on-warning.
	(main): Add support to compare local RPMs.

Signed-off-by: Chenxiong Qi <cqi@redhat.com>
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
2016-12-12 15:21:10 +01:00

227 lines
7.8 KiB
ReStructuredText
Raw Blame History

.. _fedabipkgdiff_label:
==============
fedabipkgdiff
==============
``fedabipkgdiff`` compares the ABI of shared libraries in `Fedora`_
packages. It's a convenient way to do so without having to manually
download packages from the `Fedora Build System`_.
``fedabipkgdiff`` knows how to talk with the `Fedora Build System`_ to
find the right packages versions, their associated debug information
and development packages, download them, compare their ABI locally,
and report about the possible ABI changes.
Note that by default, this tool reports ABI changes about types that
are defined in public header files found in the development packages
associated with the packages being compared. It also reports ABI
changes about functions and global variables whose symbols are defined
and exported in the ELF binaries found in the packages being compared.
.. _fedabipkgdiff_invocation_label:
Invocation
==========
::
fedabipkgdiff [option] <NVR> ...
Environment
===========
.. _fedabipkgdiff_default_supprs_label:
fedabipkgdiff 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 fedabipkgdiff 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 fedabipkgdiff tries to load the
suppression file $HOME/.abignore. If that file is not present, then
no default user suppression specification is loaded.
.. _fedabipkgdiff_options_label:
Options
=======
* ``--help | -h``
Display a short help about the command and exit.
* ``--dry-run``
Don't actually perform the ABI comparison. Details about what is
going to be done are emitted on standard output.
* ``--debug``
Emit debugging messages about the execution of the program.
Details about each method invocation, including input parameters
and returned values, are emitted.
* ``--traceback``
Show traceback when an exception raised. This is useful for
developers of the tool itself to know more exceptional errors.
* ``--server`` <URL>
Specifies the URL of the `Koji`_ XMLRPC service the tool talks to.
The default value of this option is http://koji.fedoraproject.org/kojihub.
* ``--topdir`` <URL>
Specifies the URL of the package store the tool downloads RPMs
from. The default value of this option is https://kojipkgs.fedoraproject.org.
* ``--from`` <distro>
Specifies the name of the baseline `Fedora`_ distribution in which to
find the first `build`_ that is used for comparison. The
``distro`` value can be any valid value of the RPM macro
``%{?dist}`` for `Fedora`_, for example, ``fc4``, ``fc23``, ``fc25``.
* ``--to`` <distro>
Specifies the name of the `Fedora`_ distribution in which to find
the `build`_ that is compared against the baseline specified by
option ``--from``. The ``distro`` value could be any valid value
of the RPM macro ``%{?dist}`` for `Fedora`_, for example, ``fc4``,
``fc23``.
* ``--all-subpackages``
Instructs the tool to also compare the ABI of the binaries in the
sub-packages of the packages specified.
* ``--dso-only``
Compares the ABI of shared libraries only. If this option is not
provided, the tool compares the ABI of all ELF binaries found in
the packages.
* ``--no-default-suppression``
Do not load the :ref:`default suppression specification files
<fedabipkgdiff_default_supprs_label>`.
* ``--no-devel-pkg``
Do not take associated development packages into account when
performing the ABI comparison. This makes the tool report ABI
changes about all types that are reachable from functions and
global variables which symbols are defined and publicly exported
in the binaries being compared, even if those types are not
defined in public header files available from the packages being
compared.
* ``--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.
* ``--abipkgdiff`` <path/to/abipkgdiff>
Specify an alternative abipkgdiff instead of the one installed in system.
.. _build:
Note that a build is a specific version and release of an RPM package.
It's specified by its the package name, version and release. These are specified
by the `Fedora Naming Guidelines <https://fedoraproject.org/wiki/Packaging:NamingGuidelines>`_
.. _fedabipkgdiff_return_value_label:
Return value
============
The exit code of the ``abipkgdiff`` command is either 0 if the ABI of
the binaries compared are equivalent, 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>`.
.. _fedabipkgdiff_usage_example_label:
Use cases
=========
Below are some usage examples currently supported by
``fedabipkgdiff``.
1. Compare the ABI of binaries in a local package against the ABI of
the latest stable package in `Fedora`_ 23.
Suppose you have built just built the ``httpd`` package and you
want to compare the ABI of the binaries in this locally built
package against the ABI of the binaries in the latest ``http``
build from `Fedora`_ 23. The command line invocation would be: ::
$ fedabipkgdiff --from fc23 ./httpd-2.4.18-2.fc24.x86_64.rpm
2. Compare the ABI of binaries in two local packages.
Suppose you have built two versions of package httpd, and you want to see
what ABI differences between these two versions of RPM files. The
commandline invocation would be::
$ fedabipkgdiff path/to/httpd-2.4.23-3.fc23.x86_64.rpm another/path/to/httpd-2.4.23-4.fc24.x86_64.rpm
3. Compare the ABI of binaries in the latest build of the ``httpd``
package in ``Fedora 23`` against the ABI of the binaries in the
latest build of the same package in 24.
In this case, note that neither of the two packages are available
locally. The tool is going to talk with the `Fedora Build
System`_, determine what the versions and releases of the latest
packages are, download them and perform the comparison locally.
The command line invocation would be: ::
$ fedabipkgdiff --from fc23 --to fc24 httpd
4. Compare the ABI of binaries of two builds of the ``httpd``
package, designated their versions and releases.
If we want to do perform the ABI comparison for all the processor
architectures supported by `Fedora`_ the command line invocation
would be: ::
$ fedabipkgdiff httpd-2.8.14.fc23 httpd-2.8.14.fc24
But if we want to perform the ABI comparison for a specific
architecture, say, x86_64, then the command line invocation would
be: ::
$ fedabipkgdiff httpd-2.8.14.fc23.x86_64 httpd-2.8.14.fc24.x86_64
5. If the use wants to also compare the sub-packages of a given
package, she can use the --all-subpackages option. The first
command of the previous example would thus look like: ::
$ fedabipkgdiff --all-subpackages httpd-2.8.14.fc23 httpd-2.8.14.fc24
.. _Fedora: https://getfedora.org
.. _Fedora Build System: http://koji.fedoraproject.org/koji
.. _Koji: https://fedoraproject.org/wiki/Koji
Reference in New Issue View Git Blame Copy Permalink