@@ -80,13 +80,43 @@ documented further below) to provide a suppression specification.
Options
=======
- * ``--help | -h``
+ * ``--allow-non-exported-interfaces``
- Display a short help about the command and exit.
+ When looking at the debug information accompanying a binary, this
+ tool analyzes the descriptions of the types reachable by the
+ interfaces (functions and variables) that are visible outside of
+ their translation unit. Once that analysis is done, an ABI corpus
+ is constructed by only considering the subset of types reachable
+ from interfaces associated to `ELF`_ symbols that are defined and
+ exported by the binary. It's those final ABI Corpora that are
+ compared by this tool.
- * `--version | -v`
+ The problem with that approach however is that analyzing all the
+ interfaces that are visible from outside their translation unit
+ can amount to a lot of data, especially when those binaries are
+ applications, as opposed to shared libraries. One example of such
+ applications is the `Linux Kernel`_. Analyzing massive ABI
+ Corpora like these can be extremely slow.
+
+ In the presence of an "average sized" binary however one can
+ afford having libabigail analyze all interfaces that are visible
+ outside of their translation unit, using this option.
+
+ Note that this option is turned on by default, unless we are in
+ the presence of the `Linux Kernel`_.
+
+
+ * ``--btf``
+
+ This is used to compare packages with `BTF`_ debug information,
+ if present.
+
+
+ * ``--ctf``
+
+ This is used to compare packages with `CTF`_ debug information,
+ if present.
- Display the version of the program and exit.
* ``--debug-info-pkg1 | --d1`` <path>
@@ -99,6 +129,7 @@ Options
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
@@ -110,6 +141,7 @@ Options
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
@@ -120,6 +152,7 @@ Options
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
@@ -130,6 +163,7 @@ Options
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
@@ -148,24 +182,106 @@ Options
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.
+ * ``--exported-interfaces-only``
- This option instructs ``abipkgdiff`` to *also* compare DSOs that
- are *NOT* advertised in the "provides" property of the RPM.
+ By default, when looking at the debug information accompanying a
+ binary, this tool analyzes the descriptions of the types reachable
+ by the interfaces (functions and variables) that are visible
+ outside of their translation unit. Once that analysis is done, an
+ ABI corpus is constructed by only considering the subset of types
+ reachable from interfaces associated to `ELF`_ symbols that are
+ defined and exported by the binary. It's those final ABI Corpora
+ that are compared by this tool.
+
+ The problem with that approach however is that analyzing all the
+ interfaces that are visible from outside their translation unit
+ can amount to a lot of data, especially when those binaries are
+ applications, as opposed to shared libraries. One example of such
+ applications is the `Linux Kernel`_. Analyzing massive ABI
+ corpora like these can be extremely slow.
+
+ To mitigate that performance issue, this option allows libabigail
+ to only analyze types that are reachable from interfaces
+ associated with defined and exported `ELF`_ symbols.
+
+ Note that this option is turned on by default when analyzing the
+ `Linux Kernel`_. Otherwise, it's turned off by default.
+
+
+ * ``--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>`.
+
+
+ * ``--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
+
+ $
+
+
+ * ``--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.
+
+
+ * ``--help | -h``
+
+ Display a short help about the command and exit.
+
+
+ * ``--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.
+
+
+ * ``--keep-tmp-files``
+
+ Do not erase the temporary directory files that are created during
+ the execution of the tool.
- 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``
@@ -228,149 +344,83 @@ Options
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.
+ * ``--linux-kernel-abi-whitelist | -w`` <*path-to-whitelist*>
- * ``--full-impact|-f``
+ 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".
- 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: ::
+ Any other function or variable which ELF symbol are not present in
+ that white list will not be considered by the ABI comparison
+ process.
- $ 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
+ 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.
- 1 function with some indirect sub-type change:
+ 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.
- [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
- $
+ * ``--no-abignore``
+ Do not search the package for the presence of suppression files.
- * ``--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.
+ * ``--no-added-binaries``
- 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.
+ Do not show the list of binaries that got added to the second
+ package.
- 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.
+ 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.
- 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.
- * ``--exported-interfaces-only``
+ * ``--no-added-syms``
- By default, when looking at the debug information accompanying a
- binary, this tool analyzes the descriptions of the types reachable
- by the interfaces (functions and variables) that are visible
- outside of their translation unit. Once that analysis is done, an
- ABI corpus is constructed by only considering the subset of types
- reachable from interfaces associated to `ELF`_ symbols that are
- defined and exported by the binary. It's those final ABI Corpora
- that are compared by this tool.
+ Do not show the list of functions, variables, or any symbol that
+ was added.
- The problem with that approach however is that analyzing all the
- interfaces that are visible from outside their translation unit
- can amount to a lot of data, especially when those binaries are
- applications, as opposed to shared libraries. One example of such
- applications is the `Linux Kernel`_. Analyzing massive ABI
- corpora like these can be extremely slow.
- To mitigate that performance issue, this option allows libabigail
- to only analyze types that are reachable from interfaces
- associated with defined and exported `ELF`_ symbols.
+ * ``--no-assume-odr-for-cplusplus``
- Note that this option is turned on by default when analyzing the
- `Linux Kernel`_. Otherwise, it's turned off by default.
+ When analysing a binary originating from C++ code using `DWARF`_
+ debug information, libabigail assumes the `One Definition Rule`_
+ to speed-up the analysis. In that case, when several types have
+ the same name in the binary, they are assumed to all be equal.
- * ``--allow-non-exported-interfaces``
+ This option disables that assumption and instructs libabigail to
+ actually actually compare the types to determine if they are
+ equal.
- When looking at the debug information accompanying a binary, this
- tool analyzes the descriptions of the types reachable by the
- interfaces (functions and variables) that are visible outside of
- their translation unit. Once that analysis is done, an ABI corpus
- is constructed by only considering the subset of types reachable
- from interfaces associated to `ELF`_ symbols that are defined and
- exported by the binary. It's those final ABI Corpora that are
- compared by this tool.
- The problem with that approach however is that analyzing all the
- interfaces that are visible from outside their translation unit
- can amount to a lot of data, especially when those binaries are
- applications, as opposed to shared libraries. One example of such
- applications is the `Linux Kernel`_. Analyzing massive ABI
- Corpora like these can be extremely slow.
+ * ``--no-default-suppression``
- In the presence of an "average sized" binary however one can
- afford having libabigail analyze all interfaces that are visible
- outside of their translation unit, using this option.
+ Do not load the :ref:`default suppression specification files
+ <abipkgdiff_default_supprs_label>`.
- Note that this option is turned on by default, unless we are in
- the presence of the `Linux Kernel`_.
- * ``--redundant``
+ * ``--no-leverage-dwarf-factorization``
- In the diff reports, do display redundant changes. A redundant
- change is a change that has been displayed elsewhere in a given
- report.
+ When analysing a binary which `DWARF`_ debug information was
+ processed with the `DWZ`_ tool, the type information is supposed
+ to be already factorized. That context is used by libabigail to
+ perform some speed optimizations.
- * ``--harmless``
+ This option disables those optimizations.
- 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``
@@ -378,71 +428,43 @@ Options
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*>
+ * ``--non-reachable-types|-t``
- 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".
+ Analyze and emit change reports for all the types of the binary,
+ including those that are not reachable from global functions and
+ variables.
- Any other function or variable which ELF symbol are not present in
- that white list will not be considered by the ABI comparison
- process.
+ 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.
- 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.
+ 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.
- 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.
+ 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.
- * ``--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".
+ * ``--no-show-locs``
- 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.
+ Do not show information about where in the *second shared library*
+ the respective type was changed.
- 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.
+ * ``--no-show-relative-offset-changes``
- 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.
+ 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.
- 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``
@@ -451,37 +473,30 @@ Options
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-bytes``
+
+ Show sizes and offsets in bytes, not bits. By default, sizes and
+ offsets are shown in bits.
+
* ``--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-hex``
+
+ Show sizes and offsets in hexadecimal base.
+
* ``--show-identical-binaries``
@@ -490,33 +505,27 @@ Options
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``
+ * ``--private-dso``
- Do not erase the temporary directory files that are created during
- the execution of the tool.
+ 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.
- * ``--verbose``
+ This option instructs ``abipkgdiff`` to *also* compare DSOs that
+ are *NOT* advertised in the "provides" property of the RPM.
- Emit verbose progress messages.
+ 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.
- * ``--verbose-diff``
+ * ``--redundant``
- Emit timed verbose progress messages about the diffing process.
- This option implies the --verbose one.
+ In the diff reports, do display redundant changes. A redundant
+ change is a change that has been displayed elsewhere in a given
+ report.
* ``--self-check``
@@ -534,36 +543,66 @@ Options
$ 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' ====
$
- * ``--no-assume-odr-for-cplusplus``
- When analysing a binary originating from C++ code using `DWARF`_
- debug information, libabigail assumes the `One Definition Rule`_
- to speed-up the analysis. In that case, when several types have
- the same name in the binary, they are assumed to all be equal.
- This option disables that assumption and instructs libabigail to
- actually actually compare the types to determine if they are
- equal.
+ * ``--suppressions | --suppr`` <*path-to-suppressions*>
- * ``--no-leverage-dwarf-factorization``
+ 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.
- When analysing a binary which `DWARF`_ debug information was
- processed with the `DWZ`_ tool, the type information is supposed
- to be already factorized. That context is used by libabigail to
- perform some speed optimizations.
+ Please note that, by default, if this option is not provided, then
+ the :ref:`default suppression specification files
+ <abipkgdiff_default_supprs_label>` are loaded .
- This option disables those optimizations.
+ * `--version | -v`
+
+ Display the version of the program and exit.
- * ``--ctf``
- This is used to compare packages with `CTF`_ debug information,
- if present.
+ * ``--wp`` <*path-to-whitelist-package*>
- * ``--btf``
+ 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.
+
+
+ * ``--verbose``
+
+ Emit verbose progress messages.
+
+
+ * ``--verbose-diff``
+
+ Emit timed verbose progress messages about the diffing process.
+ This option implies the --verbose one.
- This is used to compare packages with `BTF`_ debug information,
- if present.
.. _abipkgdiff_return_value_label: