From patchwork Mon Apr 7 12:25:06 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dodji Seketeli X-Patchwork-Id: 109968 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D540F384A466 for ; Mon, 7 Apr 2025 12:25:26 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D540F384A466 Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=Ntfq/tDM X-Original-To: libabigail@sourceware.org Delivered-To: libabigail@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id E681A384A465 for ; Mon, 7 Apr 2025 12:25:11 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E681A384A465 Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org E681A384A465 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1744028712; cv=none; b=lVHFzU8M42/5GVbIUvp6lTUHkQmGRhnUMdcnxEXDF3+ayw3XdJDXxqR//93moPu7DK2PCQRxE6FdqnI9rpRE7NbWle6rEFqeIvFUz/01KlfsdQzJBJGwMunRTc71tSdGanItZV72Y/h+PNu/H/AV7zSPcDWnEvT12fqYl3ZvGt8= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1744028712; c=relaxed/simple; bh=tnfG6jL2GzOtMn0QcMP5ltUkhwpE5aD/a/aZt9SyC8I=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=YLiQkTnNHRae34D/0jUFLnPoGjqxjk7Hl6uMGK1xMAnXYT7j/qZhiqWOI+RvGwGmpZEXZst2u709OvRfyXsmIjjPaJliO3amib8wai9g8yceg+4L5l2heLx5EnNRRN2XLuS8rqj1vUbyhRHkOuuFS6QtBzd3ljVHujDTmrggV7I= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E681A384A465 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1744028711; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=g10qMRSWlZ1j/qeI1iwzP3BL1TUE4AwXWPZ7zn7V2h8=; b=Ntfq/tDMY3mbJiT1vF+can/cypAGGbwxaRl8MdPYsZ9aehcUBAMTd9i6FUHa2FwpjAxZBX iELURdhocZAjPAhYgTfSwk07KhOO+V2bE9lO2t/Uw8EW+nchOKkxXGcV1wBxS443rO5pp0 rTQ0EAm9/zYA//PaYf98NJAIYf090cE= Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-421-ZRvarPM-PMa4RzpzClqLbg-1; Mon, 07 Apr 2025 08:25:10 -0400 X-MC-Unique: ZRvarPM-PMa4RzpzClqLbg-1 X-Mimecast-MFC-AGG-ID: ZRvarPM-PMa4RzpzClqLbg_1744028709 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8BFE9195608B for ; Mon, 7 Apr 2025 12:25:09 +0000 (UTC) Received: from localhost (unknown [10.44.22.27]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B9D711828AA4 for ; Mon, 7 Apr 2025 12:25:08 +0000 (UTC) Received: by localhost (Postfix, from userid 1000) id 352A55094D63; Mon, 7 Apr 2025 14:25:06 +0200 (CEST) From: Dodji Seketeli To: libabigail@sourceware.org Subject: [PATCH, applied] abidiff.rst: Sort option documentation bullets in lexicographic order Organization: Red Hat / France X-Operating-System: AlmaLinux 9.5 X-URL: http://www.redhat.com Date: Mon, 07 Apr 2025 14:25:06 +0200 Message-ID: <8734ekxiot.fsf@redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: wZTWOmb-xmHBAVgJGR6iKgvGI45SoiUuLr_r8TC-cxo_1744028709 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.8 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libabigail@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Mailing list of the Libabigail project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libabigail-bounces~patchwork=sourceware.org@sourceware.org Hello, * doc/manuals/abidiff.rst: Sort option documentation bullets in lexicographic order. Signed-off-by: Dodji Seketeli Applied to mainline. --- doc/manuals/abidiff.rst | 804 ++++++++++++++++++++++------------------ 1 file changed, 434 insertions(+), 370 deletions(-) diff --git a/doc/manuals/abidiff.rst b/doc/manuals/abidiff.rst index 40eb256d..6a6cceeb 100644 --- a/doc/manuals/abidiff.rst +++ b/doc/manuals/abidiff.rst @@ -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 - ``/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`` - - 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`` - - 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`` - - 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`` - - 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`` @@ -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`` 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 + ``/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 - `. - * ``--suppressions | --suppr`` <*path-to-suppressions*> + * ``--deleted-vars`` - Use a :ref:`suppression specification ` 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 - ` 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 + ` 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`` + + 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`` + + 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`` + + 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`` + + 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 - ` 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 - ` 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 + `. + + + * ``--no-harmful`` + + In the diff report, do not display the :ref:`harmful + ` 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 ` 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 + ` 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