@@ -63,120 +63,6 @@ change reports that might be considered as false positives to users.
Options
=======
- * ``--help | -h``
-
- Display a short help about the command and exit.
-
- * ``--debug-self-comparison``
-
- In this mode, error messages are emitted for types which fail type
- canonicalization, in some circumstances, when comparing a binary
- against itself.
-
- When comparing a binary against itself, canonical types of the
- second binary should be equal (as much as possible) to canonical
- types of the first binary. When some discrepancies are detected
- in this mode, an abort signal is emitted and execution is halted.
- This option should be used while executing the tool in a debugger,
- for troubleshooting purposes.
-
- This is an optional debugging and sanity check option. To enable
- it the libabigail package needs to be configured with
- the --enable-debug-self-comparison configure option.
-
- * ``--debug-tc``
-
- In this mode, the process of type canonicalization is put under
- heavy scrutiny. Basically, during type canonicalization, each
- type comparison is performed twice: once in a structural mode
- (comparing every sub-type member-wise), and once using canonical
- comparison. The two comparisons should yield the same result.
- Otherwise, an abort signal is emitted and the process can be
- debugged to understand why the two kinds of comparison yield
- different results.
-
- This is an optional debugging and sanity check option. To enable
- it the libabigail package needs to be configured with
- the --enable-debug-type-canonicalization configure option.
-
- * ``--version | -v``
-
- Display the version of the program and exit.
-
- * ``--debug-info-dir1 | --d1`` <*di-path1*>
-
- For cases where the debug information for *first-shared-library*
- is split out into a separate file, tells ``abidiff`` where to find
- that separate debug information file.
-
- Note that *di-path* must point to the root directory under which
- the debug information is arranged in a tree-like manner. Under
- Red Hat based systems, that directory is usually
- ``<root>/usr/lib/debug``.
-
- This option can be provided several times with different root
- directories. In that case, ``abidiff`` will potentially look into
- all those root directories to find the split debug info for
- *first-shared-library*.
-
- Note also that this option is not mandatory for split debug
- information installed by your system's package manager because
- then ``abidiff`` knows where to find it.
-
- * ``--debug-info-dir2 | --d2`` <*di-path2*>
-
- Like ``--debug-info-dir1``, this options tells ``abidiff`` where
- to find the split debug information for the
- *second-shared-library* file.
-
- This option can be provided several times with different root
- directories. In that case, ``abidiff`` will potentially look into
- all those root directories to find the split debug info for
- *second-shared-library*.
-
- * ``--headers-dir1 | --hd1`` <headers-directory-path-1>
-
- Specifies where to find the public headers of the first shared
- library (or binary in general) that the tool has to consider. The
- tool will thus filter out ABI changes on types that are not
- defined in public headers.
-
- Note that several public header directories can be specified for
- the first shared library. In that case the ``--headers-dir1``
- option should be present several times on the command line, like
- in the following example: ::
-
- $ abidiff --headers-dir1 /some/path \
- --headers-dir1 /some/other/path \
- binary-version-1 binary-version-2
-
- * ``--header-file1 | --hf1`` <header-file-path-1>
-
- Specifies where to find one public header of the first shared
- library that the tool has to consider. The tool will thus filter
- out ABI changes on types that are not defined in public headers.
-
- * ``--headers-dir2 | --hd2`` <headers-directory-path-2>
-
- Specifies where to find the public headers of the second shared
- library that the tool has to consider. The tool will thus filter
- out ABI changes on types that are not defined in public headers.
-
- Note that several public header directories can be specified for
- the second shared library. In that case the ``--headers-dir2``
- option should be present several times like in the following
- example: ::
-
- $ abidiff --headers-dir2 /some/path \
- --headers-dir2 /some/other/path \
- binary-version-1 binary-version-2
-
- * ``--header-file2 | --hf2`` <header-file-path-2>
-
- Specifies where to find one public header of the second shared
- library that the tool has to consider. The tool will thus filter
- out ABI changes on types that are not defined in public headers.
-
* ``--add-binaries1`` <*bin1,bin2,bin3,..*>
For each of the comma-separated binaries given in argument to this
@@ -188,6 +74,7 @@ Options
That ABI corpus group is then compared against the second corpus
group given in argument to ``abidiff``.
+
* ``--add-binaries2`` <*bin1,bin2,bin3,..*>
For each of the comma-separated binaries given in argument to this
@@ -199,31 +86,6 @@ Options
That ABI corpus group is then compared against the first corpus
group given in argument to ``abidiff``.
- * ``--follow-dependencies | --fdeps``
-
- For each dependency of the first argument of ``abidiff``, if it's
- found in the directory specified by the ``--added-binaries-dir1``
- option, then construct an ABI corpus out of the dependency, add it
- to a set of corpora (called an ABI Corpus Group) that includes the
- first argument of ``abidiff``.
-
- Similarly, for each dependency of the second argument of
- ``abidiff``, if it's found in the directory specified by the
- ``--added-binaries-dir2`` option, then construct an ABI corpus out
- of the dependency, add it to an ABI corpus group that includes the
- second argument of ``abidiff``.
-
- These two ABI corpus groups are then compared against each other.
-
- Said otherwise, this makes ``abidiff`` compare the set of its
- first input and its dependencies against the set of its second
- input and its dependencies.
-
- * ``list-dependencies | --ldeps``
-
- This option lists all the dependencies of the input arguments of
- ``abidiff`` that are found in the directories specified by the
- options ``--added-binaries-dir1`` and ``--added-binaries-dir2``
* ``--added-binaries-dir1 | --abd1`` <added-binaries-directory-1>
@@ -234,6 +96,7 @@ Options
are loaded as ABI corpus and are added to the first ABI corpus group
that is to be used in the comparison.
+
* ``--added-binaries-dir2 | --abd2`` <added-binaries-directory-2>
This option is to be used in conjunction with the
@@ -243,77 +106,22 @@ Options
are loaded as ABI corpus and are added to the second ABI corpus
group to be used in the comparison.
- * ``--no-linux-kernel-mode``
-
- Without this option, if abidiff detects that the binaries it is
- looking at are Linux Kernel binaries (either vmlinux or modules)
- then it only considers functions and variables which ELF symbols
- are listed in the __ksymtab and __ksymtab_gpl sections.
-
- With this option, abidiff considers the binary as a non-special
- ELF binary. It thus considers functions and variables which are
- defined and exported in the ELF sense.
-
- * ``--kmi-whitelist | -w`` <*path-to-whitelist*>
-
- When analyzing a Linux kernel binary, this option points to the
- white list of names of ELF symbols of functions and variables
- which ABI must be considered. That white list is called a "Kernel
- Module Interface white list". This is because for the Kernel, we
- don't talk about ``ABI``; we rather talk about the interface
- between the Kernel and its module. Hence the term ``KMI`` rather
- than ``ABI``.
-
- Any other function or variable which ELF symbol are not present in
- that white list will not be considered by this tool.
-
- If this option is not provided -- thus if no white list is
- provided -- then the entire KMI, that is, the set of all publicly
- defined and exported functions and global variables by the Linux
- Kernel binaries, is considered.
-
- * ``--drop-private-types``
-
- This option is to be used with the ``--headers-dir1``,
- ``header-file1``, ``header-file2`` and ``--headers-dir2`` 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.
+ * ``--added-fns``
- * ``--exported-interfaces-only``
+ In the resulting report about the differences between
+ *first-shared-library* and *second-shared-library*, only display
+ the globally defined functions that were added to
+ *second-shared-library*.
- 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.
+ * ``--added-vars``
- 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.
+ In the resulting report about the differences between
+ *first-shared-library* and *second-shared-library*, only display
+ the global variables that were added (defined) to
+ *second-shared-library*.
- Note that this option is turned on by default when analyzing the
- `Linux Kernel`_. Otherwise, it's turned off by default.
* ``--allow-non-exported-interfaces``
@@ -340,23 +148,12 @@ Options
Note that this option is turned on by default, unless we are in
the presence of the `Linux Kernel`_.
- * ``--stat``
-
- Rather than displaying the detailed ABI differences between
- *first-shared-library* and *second-shared-library*, just display
- some summary statistics about these differences.
-
- * ``--symtabs``
- Only display the symbol tables of the *first-shared-library* and
- *second-shared-library*.
+ * ``--btf``
- * ``--deleted-fns``
+ When comparing binaries, extract ABI information from `BTF`_ debug
+ information, if present.
- In the resulting report about the differences between
- *first-shared-library* and *second-shared-library*, only display
- the globally defined functions that got deleted from
- *first-shared-library*.
* ``--changed-fns``
@@ -365,19 +162,6 @@ Options
the changes in sub-types of the global functions defined in
*first-shared-library*.
- * ``--added-fns``
-
- In the resulting report about the differences between
- *first-shared-library* and *second-shared-library*, only display
- the globally defined functions that were added to
- *second-shared-library*.
-
- * ``--deleted-vars``
-
- In the resulting report about the differences between
- *first-shared-library* and *second-shared-library*, only display
- the globally defined variables that were deleted from
- *first-shared-library*.
* ``--changed-vars``
@@ -386,108 +170,94 @@ Options
the changes in the sub-types of the global variables defined in
*first-shared-library*
- * ``--added-vars``
- In the resulting report about the differences between
- *first-shared-library* and *second-shared-library*, only display
- the global variables that were added (defined) to
- *second-shared-library*.
+ * ``--ctf``
- * ``--non-reachable-types|-t``
+ When comparing binaries, extract ABI information from `CTF`_ debug
+ information, if present.
- 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 ``--headers-dir{1,2}`` and/or ``header-file{1,2}`` options,
- the additional non-reachable types analyzed are restricted to
- those defined in public headers files, 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.
-
- * ``--no-added-syms``
- In the resulting report about the differences between
- *first-shared-library* and *second-shared-library*, do not display
- added functions or variables. Do not display added functions or
- variables ELF symbols either. All other kinds of changes are
- displayed unless they are explicitely forbidden by other options
- on the command line.
+ * ``--debug-info-dir1 | --d1`` <*di-path1*>
- * ``--no-linkage-name``
+ For cases where the debug information for *first-shared-library*
+ is split out into a separate file, tells ``abidiff`` where to find
+ that separate debug information file.
- In the resulting report, do not display the linkage names of
- the added, removed, or changed functions or variables.
+ Note that *di-path* must point to the root directory under which
+ the debug information is arranged in a tree-like manner. Under
+ Red Hat based systems, that directory is usually
+ ``<root>/usr/lib/debug``.
- * ``--no-show-locs``
+ This option can be provided several times with different root
+ directories. In that case, ``abidiff`` will potentially look into
+ all those root directories to find the split debug info for
+ *first-shared-library*.
- Do not show information about where in the *second shared library*
- the respective type was changed.
+ Note also that this option is not mandatory for split debug
+ information installed by your system's package manager because
+ then ``abidiff`` knows where to find it.
- * ``--show-bytes``
- Show sizes and offsets in bytes, not bits. By default, sizes and
- offsets are shown in bits.
+ * ``--debug-info-dir2 | --d2`` <*di-path2*>
- * ``--show-bits``
+ Like ``--debug-info-dir1``, this options tells ``abidiff`` where
+ to find the split debug information for the
+ *second-shared-library* file.
- Show sizes and offsets in bits, not bytes. This option is
- activated by default.
+ This option can be provided several times with different root
+ directories. In that case, ``abidiff`` will potentially look into
+ all those root directories to find the split debug info for
+ *second-shared-library*.
- * ``--show-hex``
- Show sizes and offsets in hexadecimal base.
+ * ``--debug-self-comparison``
- * ``--show-dec``
+ In this mode, error messages are emitted for types which fail type
+ canonicalization, in some circumstances, when comparing a binary
+ against itself.
- Show sizes and offsets in decimal base. This option is activated
- by default.
+ When comparing a binary against itself, canonical types of the
+ second binary should be equal (as much as possible) to canonical
+ types of the first binary. When some discrepancies are detected
+ in this mode, an abort signal is emitted and execution is halted.
+ This option should be used while executing the tool in a debugger,
+ for troubleshooting purposes.
- * ``--ignore-soname``
+ This is an optional debugging and sanity check option. To enable
+ it the libabigail package needs to be configured with
+ the --enable-debug-self-comparison configure option.
- Ignore differences in the SONAME when doing a comparison
+ * ``--debug-tc``
- * ``--no-show-relative-offset-changes``
+ In this mode, the process of type canonicalization is put under
+ heavy scrutiny. Basically, during type canonicalization, each
+ type comparison is performed twice: once in a structural mode
+ (comparing every sub-type member-wise), and once using canonical
+ comparison. The two comparisons should yield the same result.
+ Otherwise, an abort signal is emitted and the process can be
+ debugged to understand why the two kinds of comparison yield
+ different results.
- 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.
+ This is an optional debugging and sanity check option. To enable
+ it the libabigail package needs to be configured with
+ the --enable-debug-type-canonicalization configure option.
- * ``--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.
+ * ``--deleted-fns``
- * ``--no-default-suppression``
+ In the resulting report about the differences between
+ *first-shared-library* and *second-shared-library*, only display
+ the globally defined functions that got deleted from
+ *first-shared-library*.
- Do not load the :ref:`default suppression specification files
- <abidiff_default_supprs_label>`.
- * ``--suppressions | --suppr`` <*path-to-suppressions*>
+ * ``--deleted-vars``
- 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 provided suppression specification files are taken into
- account.
+ In the resulting report about the differences between
+ *first-shared-library* and *second-shared-library*, only display
+ the globally defined variables that were deleted from
+ *first-shared-library*.
- Please note that, by default, if this option is not provided, then
- the :ref:`default suppression specification files
- <abidiff_default_supprs_label>` are loaded .
* ``--drop`` <*regex*>
@@ -497,6 +267,7 @@ Options
*regex*. As a result, no change involving these functions or
variables will be emitted in the diff report.
+
* ``--drop-fn`` <*regex*>
When reading the *first-shared-library* and
@@ -505,11 +276,173 @@ Options
result, no change involving these functions will be emitted in the
diff report.
- * ``--drop-var`` <*regex*>
- When reading the *first-shared-library* and
- *second-shared-library* ELF input files, drop the globally defined
- variables matching a the regular expression *regex*.
+ * ``--drop-var`` <*regex*>
+
+ When reading the *first-shared-library* and
+ *second-shared-library* ELF input files, drop the globally defined
+ variables matching a the regular expression *regex*.
+
+
+ * ``--drop-private-types``
+
+ This option is to be used with the ``--headers-dir1``,
+ ``header-file1``, ``header-file2`` and ``--headers-dir2`` 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.
+
+
+ * ``--dump-diff-tree``
+
+ After the diff report, emit a textual representation of the diff
+ nodes tree used by the comparison engine to represent the changed
+ functions and variables. That representation is emitted to the
+ error output for debugging purposes. Note that this diff tree is
+ relevant only to functions and variables that have some sub-type
+ changes. Added or removed functions and variables do not have any
+ diff nodes tree associated to them.
+
+
+ * ``--exported-interfaces-only``
+
+ 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-debug-info``
+
+ If no debug info was found, then this option makes the program to
+ fail. Otherwise, without this option, the program will attempt to
+ compare properties of the binaries that are not related to debug
+ info, like pure ELF properties.
+
+
+ * ``--follow-dependencies | --fdeps``
+
+ For each dependency of the first argument of ``abidiff``, if it's
+ found in the directory specified by the ``--added-binaries-dir1``
+ option, then construct an ABI corpus out of the dependency, add it
+ to a set of corpora (called an ABI Corpus Group) that includes the
+ first argument of ``abidiff``.
+
+ Similarly, for each dependency of the second argument of
+ ``abidiff``, if it's found in the directory specified by the
+ ``--added-binaries-dir2`` option, then construct an ABI corpus out
+ of the dependency, add it to an ABI corpus group that includes the
+ second argument of ``abidiff``.
+
+ These two ABI corpus groups are then compared against each other.
+
+ Said otherwise, this makes ``abidiff`` compare the set of its
+ first input and its dependencies against the set of its second
+ input and its dependencies.
+
+
+ * ``--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.
+
+
+ * ``--headers-dir1 | --hd1`` <headers-directory-path-1>
+
+ Specifies where to find the public headers of the first shared
+ library (or binary in general) that the tool has to consider. The
+ tool will thus filter out ABI changes on types that are not
+ defined in public headers.
+
+ Note that several public header directories can be specified for
+ the first shared library. In that case the ``--headers-dir1``
+ option should be present several times on the command line, like
+ in the following example: ::
+
+ $ abidiff --headers-dir1 /some/path \
+ --headers-dir1 /some/other/path \
+ binary-version-1 binary-version-2
+
+
+
+ * ``--headers-dir2 | --hd2`` <headers-directory-path-2>
+
+ Specifies where to find the public headers of the second shared
+ library that the tool has to consider. The tool will thus filter
+ out ABI changes on types that are not defined in public headers.
+
+ Note that several public header directories can be specified for
+ the second shared library. In that case the ``--headers-dir2``
+ option should be present several times like in the following
+ example: ::
+
+ $ abidiff --headers-dir2 /some/path \
+ --headers-dir2 /some/other/path \
+ binary-version-1 binary-version-2
+
+
+
+ * ``--header-file1 | --hf1`` <header-file-path-1>
+
+ Specifies where to find one public header of the first shared
+ library that the tool has to consider. The tool will thus filter
+ out ABI changes on types that are not defined in public headers.
+
+
+ * ``--header-file2 | --hf2`` <header-file-path-2>
+
+ Specifies where to find one public header of the second shared
+ library that the tool has to consider. The tool will thus filter
+ out ABI changes on types that are not defined in public headers.
+
+
+ * ``--help | -h``
+
+ Display a short help about the command and exit.
+
+
+ * ``--ignore-soname``
+
+ Ignore differences in the SONAME when doing a comparison
+
+
+ * ``--impacted-interfaces``
+
+ When showing leaf changes, this option instructs abidiff to show
+ the list of impacted interfaces. This option is thus to be used
+ in addition the ``--leaf-changes-only`` option, otherwise, it's
+ ignored.
+
* ``--keep`` <*regex*>
@@ -519,6 +452,7 @@ Options
*regex*. All other functions and variables are dropped on the
floor and will thus not appear in the resulting diff report.
+
* ``--keep-fn`` <*regex*>
When reading the *first-shared-library* and
@@ -527,6 +461,7 @@ Options
other functions are dropped on the floor and will thus not appear
in the resulting diff report.
+
* ``--keep-var`` <*regex*>
When reading the *first-shared-library* and
@@ -535,45 +470,25 @@ Options
variables are dropped on the floor and will thus not appear in the
resulting diff 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-harmful``
-
- In the diff report, do not display the :ref:`harmful
- <harmfulchangeconcept_label>` changes. By default, only the
- harmful changes are displayed in diff report.
-
- * ``--redundant``
-
- In the diff report, do display redundant changes. A redundant
- change is a change that has been displayed elsewhere in the
- report.
-
- * ``--no-redundant``
-
- In the diff report, do *NOT* display redundant changes. A
- redundant change is a change that has been displayed elsewhere in
- the report. This option is switched on by default.
-
- * ``--no-architecture``
- Do not take architecture in account when comparing ABIs.
+ * ``--kmi-whitelist | -w`` <*path-to-whitelist*>
- * ``--no-corpus-path``
+ When analyzing a Linux kernel binary, this option points to the
+ white list of names of ELF symbols of functions and variables
+ which ABI must be considered. That white list is called a "Kernel
+ Module Interface white list". This is because for the Kernel, we
+ don't talk about ``ABI``; we rather talk about the interface
+ between the Kernel and its module. Hence the term ``KMI`` rather
+ than ``ABI``.
- Do not emit the path attribute for the ABI corpus.
+ Any other function or variable which ELF symbol are not present in
+ that white list will not be considered by this tool.
- * ``--fail-no-debug-info``
+ If this option is not provided -- thus if no white list is
+ provided -- then the entire KMI, that is, the set of all publicly
+ defined and exported functions and global variables by the Linux
+ Kernel binaries, is considered.
- If no debug info was found, then this option makes the program to
- fail. Otherwise, without this option, the program will attempt to
- compare properties of the binaries that are not related to debug
- info, like pure ELF properties.
* ``--leaf-changes-only|-l`` only show leaf changes, so don't show
impact analysis report. This option implies ``--redundant``.
@@ -629,27 +544,26 @@ Options
You can learn about that option below, in any case.
- * ``--impacted-interfaces``
+ * ``--list-dependencies | --ldeps``
- When showing leaf changes, this option instructs abidiff to show
- the list of impacted interfaces. This option is thus to be used
- in addition the ``--leaf-changes-only`` option, otherwise, it's
- ignored.
+ This option lists all the dependencies of the input arguments of
+ ``abidiff`` that are found in the directories specified by the
+ options ``--added-binaries-dir1`` and ``--added-binaries-dir2``
- * ``--dump-diff-tree``
+ * ``--no-added-syms``
+
+ In the resulting report about the differences between
+ *first-shared-library* and *second-shared-library*, do not display
+ added functions or variables. Do not display added functions or
+ variables ELF symbols either. All other kinds of changes are
+ displayed unless they are explicitely forbidden by other options
+ on the command line.
- After the diff report, emit a textual representation of the diff
- nodes tree used by the comparison engine to represent the changed
- functions and variables. That representation is emitted to the
- error output for debugging purposes. Note that this diff tree is
- relevant only to functions and variables that have some sub-type
- changes. Added or removed functions and variables do not have any
- diff nodes tree associated to them.
* ``--no-assume-odr-for-cplusplus``
- When analysing a binary originating from C++ code using `DWARF`_
+ When analyzing 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.
@@ -658,14 +572,11 @@ Options
actually actually compare the types to determine if they are
equal.
- * ``--no-leverage-dwarf-factorization``
- 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.
+ * ``--no-architecture``
+
+ Do not take architecture in account when comparing ABIs.
- This option disables those optimizations.
* ``--no-change-categorization | -x``
@@ -679,25 +590,178 @@ Options
impact on interfaces. In that case, this option would be used
along with the ``--leaf-changes-only`` one.
- * ``--ctf``
- When comparing binaries, extract ABI information from `CTF`_ debug
- information, if present.
+ * ``--no-corpus-path``
- * ``--btf``
+ Do not emit the path attribute for the ABI corpus.
+
+
+ * ``--no-default-suppression``
+
+ Do not load the :ref:`default suppression specification files
+ <abidiff_default_supprs_label>`.
+
+
+ * ``--no-harmful``
+
+ In the diff report, do not display the :ref:`harmful
+ <harmfulchangeconcept_label>` changes. By default, only the
+ harmful changes are displayed in diff report.
+
+
+ * ``--no-leverage-dwarf-factorization``
+
+ When analyzing 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.
+
+ This option disables those optimizations.
+
+
+ * ``--no-linkage-name``
+
+ In the resulting report, do not display the linkage names of
+ the added, removed, or changed functions or variables.
+
+
+ * ``--no-linux-kernel-mode``
+
+ Without this option, if abidiff detects that the binaries it is
+ looking at are Linux Kernel binaries (either vmlinux or modules)
+ then it only considers functions and variables which ELF symbols
+ are listed in the __ksymtab and __ksymtab_gpl sections.
+
+ With this option, abidiff considers the binary as a non-special
+ ELF binary. It thus considers functions and variables which are
+ defined and exported in the ELF sense.
+
+
+ * ``--no-redundant``
+
+ In the diff report, do *NOT* display redundant changes. A
+ redundant change is a change that has been displayed elsewhere in
+ the report. This option is switched on by default.
+
+
+ * ``--no-show-locs``
+
+ Do not show information about where in the *second shared library*
+ the respective type was changed.
+
+
+ * ``--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.
+
+
+ * ``--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.
+
+
+ * ``--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 ``--headers-dir{1,2}`` and/or ``header-file{1,2}`` options,
+ the additional non-reachable types analyzed are restricted to
+ those defined in public headers files, 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 report, do display redundant changes. A redundant
+ change is a change that has been displayed elsewhere in the
+ report.
+
+
+ * ``--show-bits``
+
+ Show sizes and offsets in bits, not bytes. This option is
+ activated by default.
+
+
+ * ``--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.
+
+
+ * ``--show-hex``
+
+ Show sizes and offsets in hexadecimal base.
+
+
+ * ``--stat``
+
+ Rather than displaying the detailed ABI differences between
+ *first-shared-library* and *second-shared-library*, just display
+ some summary statistics about these differences.
- When comparing binaries, extract ABI information from `BTF`_ debug
- information, if present.
* ``--stats``
Emit statistics about various internal things.
+
+ * ``--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 provided 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
+ <abidiff_default_supprs_label>` are loaded .
+
+
+ * ``--symtabs``
+
+ Only display the symbol tables of the *first-shared-library* and
+ *second-shared-library*.
+
+
* ``--verbose``
Emit verbose logs about the progress of miscellaneous internal
things.
+
+ * ``--version | -v``
+
+ Display the version of the program and exit.
+
+
.. _abidiff_return_value_label:
Return values