2015-07-15 14:30:46 +00:00
|
|
|
.. _abipkgdiff_label:
|
|
|
|
|
|
|
|
|
|
===========
|
|
|
|
|
abipkgdiff
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
``abipkgdiff`` compares the Application Binary Interfaces (ABI) of the
|
2015-09-08 08:11:34 +00:00
|
|
|
`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.
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
|
|
|
|
|
.. _RPM: https://en.wikipedia.org/wiki/RPM_Package_Manager
|
2015-08-14 13:24:59 +00:00
|
|
|
.. _Deb: https://en.wikipedia.org/wiki/Deb_%28file_format%29
|
2015-09-08 08:11:34 +00:00
|
|
|
.. _tar: https://en.wikipedia.org/wiki/Tar_%28computing%29
|
2015-07-15 14:30:46 +00:00
|
|
|
.. _DWARF: http://www.dwarfstd.org
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _abipkgdiff_invocation_label:
|
|
|
|
|
|
|
|
|
|
Invocation
|
2015-10-05 06:40:20 +00:00
|
|
|
==========
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
abipkgdiff [option] <package1> <package2>
|
|
|
|
|
|
|
|
|
|
.. _abipkgdiff_options_label:
|
|
|
|
|
|
|
|
|
|
Options
|
|
|
|
|
=======
|
|
|
|
|
|
2015-08-13 15:19:59 +00:00
|
|
|
* ``--help | -h``
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
Display a short help about the command and exit.
|
|
|
|
|
|
Add --version option to several libabigail tools
This patch changed the revision number of the libabigail library to
make it reflect the fact that we are not in "release candidate" mode,
before the first 1.0 release. So the revision number is now "rc0".
The configuration manager has been updated to support version numbers
that are strings, so that it can supports things like "rc0".
Then, several libabigail tools have been modified to support the
--version option to display their version number.
* configure.ac: Set the version revision to "rc0".
* doc/manuals/abicompat.rst: Adjust manual for new --version
option.
* doc/manuals/abidiff.rst: Likewise.
* doc/manuals/abidw.rst: Likewise.
* doc/manuals/abilint.rst: Likewise.
* doc/manuals/abipkgdiff.rst: Likewise.
* include/abg-config.h (config::{m_format_minor, m_format_major}):
Make these be strings.
(config::{get,set}_format_minor_version_number): Make these return
strings.
(config::{get,set}_format_major_version_number): Make these return
or take strings.
(abigail_get_library_version): Make this take strings.
* src/abg-config.cc (config::config): Adjust.
(config::{get,set}_format_major_version_number): Make these return
or take strings.
(config::{get,set}_format_minor_version_number): Make these return
strings.
(abigail_get_library_version): Make this take strings.
* include/abg-version.h.in: Make the version variables be strings.
* src/abg-writer.cc (write_translation_unit): The version numbers
are now strings so adjust.
* tools/{abicompat,abidiff,abidw,abilint,abipkgdiff,abisym}.cc
(options::display_version): New data member.
(options::options): Initialize it.
(display_usage): Add documentation for new --version option.
(parse_command_line): Parse new --version option.
(main): Support --version.
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
2015-11-16 10:39:15 +00:00
|
|
|
* `--version | -v`
|
|
|
|
|
|
|
|
|
|
Display the version of the program and exit.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--debug-info-pkg1 | --d1`` <path>
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--debug-info-pkg2 | --d2`` <path>
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--dso-only``
|
2015-07-16 09:40:43 +00:00
|
|
|
|
|
|
|
|
Compare ELF files that are shared libraries, only. Do not compare
|
|
|
|
|
executable files, for instance.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--redundant``
|
2015-07-16 10:01:11 +00:00
|
|
|
|
|
|
|
|
In the diff reports, do display redundant changes. A redundant
|
|
|
|
|
change is a change that has been displayed elsewhere in a given
|
|
|
|
|
report.
|
|
|
|
|
|
2015-07-21 13:49:25 +00:00
|
|
|
* ``--no-linkage-name``
|
|
|
|
|
|
|
|
|
|
In the resulting report, do not display the linkage names of
|
|
|
|
|
the added, removed, or changed functions or variables.
|
|
|
|
|
|
2015-08-06 11:56:48 +00:00
|
|
|
* ``--no-added-syms``
|
|
|
|
|
|
|
|
|
|
Do not show the list of functions, variables, or any symbol that
|
|
|
|
|
was added.
|
|
|
|
|
|
2015-07-21 12:15:33 +00:00
|
|
|
* ``--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.
|
|
|
|
|
|
2015-10-14 15:34:11 +00:00
|
|
|
* ``--no-abignore``
|
|
|
|
|
|
|
|
|
|
Do not search the *package2* for the presence of suppression
|
|
|
|
|
files.
|
|
|
|
|
|
Bug 19081 - abipkgdiff parallelization
Abipkgdiff now attempts to extract packages and compare the resulting
ELF pairs in parallel. First off, a thread is spawned to extract each
package and each debuginfo package. After the ELF files are extracted,
mapped and the threads are successfully collected, the resulting
ELF vectors are traversed to identify existing pairs and a list of
arguments for future comparison is made. This list is then sorted
by size from largest to smallest. Unless --no-parallel is
specified on the command line, MIN(pairs,active_processors) threads
are spawned, sharing a single list of arguments. This list is
processed and a map of (ELF_PATH,DIFF_CORPUS) is created. Meanwhile,
the main thread checks this same map for results in the original order
of the ELF pairs, ensuring sequential output. After all the diffing
and reporting is done, the threads are collected again.
* doc/manuals/abipkgdiff.rst: Mention the new --no-parallel option.
* tools/Makefile.am: Add -pthread to abipkgdiffs link options.
* tools/abipkgdiff.cc (elf_file_paths_tls_key): New key for the
thread-local vector of ELF filepaths.
(reports_map): A map of the path of the first ELF of a compared pair
and a corpus representing the difference.
(env_map): A map of the corpus difference and a corresponding
environment needed to be kept alive until the diff is reported.
({arg,map}_lock): mutexes to control access to the comparison argument
list and the {reports,env}_map respectively.
(options): Add a new member "parallel" and set it to true in the ctor.
(elf_file): Add a new "size" member and set it in the ctor.
(package descriptor): Arguments passed to extract_package_set.
(compare_args): Arguments passed to the ELF comparison function.
(display_usage): Mention the new "--no-parallel" option.
(pthread_routine_extract_package): A wrapper function around
extract_package to be used in a multi-threaded environment.
({first_second}_package_tree_walker_callback_fn): Add the new ELF file
paths to a thread-specific vector.
(compare): In an overload of compare, verbose output is updated to
always mention the ELF files being compared for each reported stage.
Reporting is no longer done in this function, the resulting difference
is instead passed back to the calling function for reporting in the
main thread, along with a corresponding environment.
(pthread_routine_compare): Accept a pointer to a vector of comparison
arguments. This function is to be called NTHREAD times and share the
vector passed to it with its other invocations. Create the environment
for compare() and store its output in a map if there is a difference.
(create_maps_of_package_content): Allocate memory for a thread local
vector of ELF paths and dispose of it before returning.
(pthread_routine_extract_pkg_and_map_its_content): Renamed from
extract_package_and_map_its_content. Extract the debuginfo as well as
the regular package in this function. Spawn a separate thread for the
extraction of the debug package.
(pthread_join): A function handling thread joining throughout package
extractions.
(prepare_packages): Spawn a thread to extract each set of packages.
(elf_size_is_greater): New comparison function used to order ELF pairs
by size.
(compare): In the overload of compare, pass through the ELF path
vectors and identify pairs to be diffed. Put them in a vector and sort
it by the summed ELF pair size. Spawn comparison threads and safely
check for results in the proper order of the ELF pairs. Report any
differences ASAP and collect the threads after all the reporting is
done, checking their return status.
(parse_command_line): Check for the "--no-parallel" option.
Signed-off-by: Ondrej Oprala <ooprala@redhat.com>
2015-11-09 10:02:45 +00:00
|
|
|
* ``--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.
|
|
|
|
|
|
2015-07-19 12:46:09 +00:00
|
|
|
* ``--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; all the suppression
|
|
|
|
|
specification files are then taken into account.
|
|
|
|
|
|
Add the option of printing the file, line and column information about a type being reported.
* bash-completion/abicompat: Complete the new "--no-show-locs" option.
* bash-completion/abidiff: Likewise.
* bash-completion/abidw: Likewise.
* bash-completion/abipkgdiff: Likewise.
* doc/manuals/abicompat.rst: Mention the new "--no-show-locs" option.
* doc/manuals/abidiff.rst: Likewise.
* doc/manuals/abidw.rst: Likewise.
* doc/manuals/abipkgdiff.rst: Likewise.
* include/abg-comparison.h (show_locs): Add declarations.
* src/abg-comparison.cc: (diff_context::priv): Add a new switch
called "show_locs_" and set its default value to false.
(report_loc_info): New function. Outputting the extra information
is conditionalized based on the associated diff contexts settings.
(show_locs): define a getter/setter for
diff_context::priv::show_locs_.
({distinct,pointer,reference,qualified_type,enum,class,scope,fn_parm,
typedef,corpus}_diff::report): Call report_loc_info when
appropriate.
(maybe_report_diff_for_member): Likewise.
(represent): Accept a const reference to a diff_context_sptr as a first
argument and call report_loc_info on its second argument.
* src/abg-dwarf-reader.cc:
* tests/data/Makefile.am: Add the new test reference files.
* tests/data/test-abicompat/test0-fn-changed-report-2.txt: New test
reference output.
* tests/data/test-abicompat/test5-fn-changed-report-1.txt: Likewise.
* tests/data/test-abicompat/test6-var-changed-report-1.txt: Likewise.
* tests/data/test-abicompat/test7-fn-changed-report-2.txt: Likewise.
* tests/data/test-diff-filter/test30-pr18904-rvalueref-report1.txt:
Likewise.
* tests/data/test-diff-filter/test31-pr18535-libstdc++-report-1.txt:
Likewise.
* tests/data/test-diff-pkg/dirpkg-3-report-2.txt: Likewise.
* tests/data/test-diff-suppr/test6-fn-suppr-report-0-1.txt: Likewise.
* tests/test-abidiff.cc: Explicitly create a diff context and turn off
location emitting.
* tests/test-diff-dwarf.cc: Likewise.
* tests/test-abicompat.cc: Add --no-show-locs to all existing test
arguments. Run a few of the existing tests again, but without this
option.
* tests/test-diff-filter.cc: Likewise.
* tests/test-diff-pkg.cc: Likewise.
* tests/test-diff-suppr.cc: Likewise.
* tools/abicompat.cc: Handle the new "--no-show-locs" option.
* tools/abidiff.cc: Likewise.
* tools/abidw.cc: Likewise.
* tools/abipkgdiff.cc: Likewise.
Signed-off-by: Ondrej Oprala <ooprala@redhat.com>
2015-11-16 09:55:28 +00:00
|
|
|
* ``--no-show-locs``
|
|
|
|
|
|
|
|
|
|
Do not show information about where in the *second shared library*
|
|
|
|
|
the respective type was changed.
|
|
|
|
|
|
2015-08-13 15:21:13 +00:00
|
|
|
* ``--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>`.
|
|
|
|
|
|
2015-07-22 07:44:57 +00:00
|
|
|
* ``--keep-tmp-files``
|
|
|
|
|
|
|
|
|
|
Do not erase the temporary directory files that are created during
|
|
|
|
|
the execution of the tool.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--verbose``
|
2015-07-15 14:30:46 +00:00
|
|
|
|
|
|
|
|
Emit verbose progress messages.
|
|
|
|
|
|
|
|
|
|
.. _abipkgdiff_return_value_label:
|
|
|
|
|
|
|
|
|
|
Return value
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
The exit code of the ``abipkgdiff`` command is either 0 if the ABI of
|
2015-07-21 10:59:43 +00:00
|
|
|
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>`.
|
|
|
|
|
|