mirror of
git://sourceware.org/git/libabigail.git
synced 2025-02-18 23:07:00 +00:00
b36ca1501e
This patch adds support for loading system and user level suppression specifications for libabigail tools. At launch time, relevant libabigail tools (abidiff, abipkgdiff fedabipkgdiff for now) read the default system suppression specification file, if it's present, from a file which path is the value of the environment variable LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE, if set, or from the file $libdir/libabigail/default.abignore. Then it reads the user system suppression specification file, if it's present, from a file which path is the value of the environment variable LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE, if set, or from the file $HOME/.abignore. The content of the user system suppression file is merged with the content of default system suppression file. That content is also merged with the content of the suppression specification files that might be provided by the --suppressions command line option of the invoked tools. The resulting set of all these suppression specifications is thus used to filter the ABI change reports that are emitted. abidiff, abipkgdiff and abipkgdiff gain a --no-default-suppression option to avoid loading any of these default suppression specification files. The patch also installs a default.abignore file into $(pkglibdir). Note that on x86_64, that directory is /usr/lib64/libabigail. Now we just need to think about the content of that default.abignore file. * doc/manuals/abidiff.rst: Document the default suppression scheme, its interaction with the --supprs option and the new --no-default option. * doc/manuals/abipkgdiff.rst: Likewise. * doc/manuals/fedabipkgdiff.rst: Likewise. * configure.ac: Generate the tests/runtestdefaultsupprs.py file from the new tests/runtestdefaultsupprs.py.in template. * default.abignore: New file. * Makefile.am: Add it to source distribution. * src/Makefile.am: Define the ABIGAIL_ROOT_SYSTEM_LIBDIR preprocessor macro that is set the value of the $libdir autotools macro. * include/abg-tools-utils.h: Update copyright years. (get_system_libdir, get_default_system_suppression_file_path) (get_default_user_suppression_file_path) (load_default_system_suppressions) (load_default_user_suppressions): Declare new functions * src/abg-tools-utils.cc (get_system_libdir) (get_default_system_suppression_file_path) (get_default_user_suppression_file_path) (load_default_system_suppressions) (load_default_user_suppressions): Define new functions. (is_regular_file): Amend this so that it return true for symlinks to regular files too. (is_dir): Amend this so that it returns true for symlinks to directories too. * tools/abidiff.cc (options::no_default_supprs): New data member. (options::options): Initialize the new data member. (display_usage): Display a new help string for the new --no-default-suppression command line option. (parse_command_line): Parse this new command line option. (set_diff_context_from_opts): Load the default suppression specifications, unless --no-default-suppression or --supprs was provided. * tools/abipkgdiff.cc (options::no_default_supprs): New data member. (options::options): Initialize the new data member. (parse_command_line): Parse the new --no-default-suppression command line option. (main): Load the default suppression specifications, unless --no-default-suppression or --supprs was provided. * tools/fedabipkgdiff (abipkgdiff): Add --no-default-suppression to the invocation of abipkgdiff if it was provided on the command line. (build_commandline_args_parser): Parse the new --no-default-suppression command line option. * tests/runtestdefaultsupprs.py.in: New test harness template. * tests/Makefile.am: Add the new runtestdefaultsupprs.py to the set of tests. * tests/data/test-default-supprs/test0-type-suppr-0.suppr: New test input. * tests/data/test-default-supprs/test0-type-suppr-report-0.txt: Likewise. * tests/data/test-default-supprs/test0-type-suppr-v0.o: Likewise. * tests/data/test-default-supprs/test0-type-suppr-v1.o: Likewise. * tests/data/test-default-supprs/dirpkg-1-dir-report-0.txt: Likewise. * tests/data/test-default-supprs/dirpkg-1-dir1: Likewise. * tests/data/test-default-supprs/dirpkg-1-dir2: Likewise. * tests/data/Makefile.am: Add new the new tests input above to Makefile.am. * tests/runtestcanonicalizetypes.sh.in: Pass --no-default-suppression to abidiff invocations. * tests/runtestdefaultsupprs.py.in: Likewise. * tests/test-abidiff-exit.cc: Likewise. * tests/test-diff-dwarf-abixml.cc: Likewise. * tests/test-diff-filter.cc: Likewise. * tests/test-diff-suppr.cc: Likewise. * tools/abidiff.cc: Likewise. Signed-off-by: Dodji Seketeli <dodji@redhat.com>
191 lines
6.3 KiB
ReStructuredText
191 lines
6.3 KiB
ReStructuredText
.. _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 and their associated debug
|
|
information, download them, compare their ABI locally, and report
|
|
about the possible ABI changes.
|
|
|
|
.. _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>`.
|
|
|
|
.. _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 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
|
|
|
|
3. 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
|
|
|
|
4. 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
|