From patchwork Mon Jun 30 17:58:59 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dodji Seketeli X-Patchwork-Id: 115333 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 7E06E385140C for ; Mon, 30 Jun 2025 17:59:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7E06E385140C 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=G2frDM8p 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 219CC3858294 for ; Mon, 30 Jun 2025 17:59:05 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 219CC3858294 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 219CC3858294 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=1751306345; cv=none; b=RamhfFQun30o2orJlhb3WrMKyl0VkxsA3f7gVtFuI/ptnuC7gxIbarZajzh/3NEkJx/CgvIQj4eudfaFW8Zzh2D9biOZvU8tMTT0R0HnjeTn5ItXYm98fT3NWLpw7J5XBDRpbD0gPB0UjNZe+iQQdB4IG/DTJuk3R4o9mqOjRvo= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1751306345; c=relaxed/simple; bh=U4ArB/5/Y5hXhJajZJr3p8OQr39WsE9eBZSbFlS6fzw=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=drGPmUMamD5B30v+GNWJz/1hOfCyjt9yifCRh8uXqRaf9Ar9GaTDPnNg7Wgq/GehvSZQ33ZI59fzMdilYCc+nQiTQbnHjhaPe8btQSacJiN8M8PBXvGH/ZmA+9sQ4T98zQ2vP2pfvCDPAyrHQhiSJe3Zgi7AK6PCzuOPTVUf9Hg= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 219CC3858294 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1751306344; 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=csHiQGa7ZXi+KdogIOIxEVf8hhVu1lfXL1Bnar+i+BQ=; b=G2frDM8pwiGlOQCE2opMqNL0pKtP1z8ViurCb37bSxC124gnSv8ua540N7iqTPtDeRKArm BWiM4fRj5mW8swAYh/plxC0Yzqwd/Cc9IBkjE2KFI4gemie9AEOvlAfDPPAN70e78IU3q7 fQSMLb0X0ewZtsTcaqOdNZVKOEbHjjA= 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-447-GeXp5_WwPrOIVIdWPgDbOg-1; Mon, 30 Jun 2025 13:59:03 -0400 X-MC-Unique: GeXp5_WwPrOIVIdWPgDbOg-1 X-Mimecast-MFC-AGG-ID: GeXp5_WwPrOIVIdWPgDbOg_1751306342 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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 9D418193F057 for ; Mon, 30 Jun 2025 17:59:02 +0000 (UTC) Received: from localhost (unknown [10.44.22.5]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0D05A19560AB for ; Mon, 30 Jun 2025 17:59:02 +0000 (UTC) Received: by localhost (Postfix, from userid 1000) id 62FD7504EC40; Mon, 30 Jun 2025 19:58:59 +0200 (CEST) From: Dodji Seketeli To: libabigail@sourceware.org Subject: [PATCH, applied] abidw: Sort options documentation alphabetically Organization: Red Hat / France X-Operating-System: AlmaLinux 9.6 X-URL: http://www.redhat.com Date: Mon, 30 Jun 2025 19:58:59 +0200 Message-ID: <87ecv1rtzw.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.0 on 10.30.177.40 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: 0mjseABe7BS2FQZEQDx-P8bPRpMHcERyijcj0NoQdfk_1751306342 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.7 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_H5, RCVD_IN_MSPIKE_WL, RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED, 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/abidw.rst: Sort items of options documentation alphabetically. * tools/abidw.cc (display_usage): Likewise. Signed-off-by: Dodji Seketeli Applied to the mainline. --- doc/manuals/abidw.rst | 460 +++++++++++++++++++++++------------------- tools/abidw.cc | 105 +++++----- 2 files changed, 307 insertions(+), 258 deletions(-) diff --git a/doc/manuals/abidw.rst b/doc/manuals/abidw.rst index cd3e6253..0293a3c0 100644 --- a/doc/manuals/abidw.rst +++ b/doc/manuals/abidw.rst @@ -40,18 +40,23 @@ Invocation Options ======= - * ``--help | -h`` + * ``--abidiff`` - Display a short help about the command and exit. + Load the ABI of the ELF binary given in argument, save it in + libabigail's XML format in a temporary file; read the ABI from the + temporary XML file and compare the ABI that has been read back + against the ABI of the ELF binary given in argument. The ABIs + should compare equal. If they don't, the program emits a + diagnostic and exits with a non-zero code. - * ``--version | -v`` + This is a debugging and sanity check option. - Display the version of the program and exit. * ``--abixml-version`` Display the version of the ABIXML format emitted by this program and exit. + * ``--add-binaries`` <*bin1,bin2,...*> For each of the comma-separated binaries given in argument to this @@ -61,20 +66,6 @@ Options Group) made of the binary denoted by the Argument of ``abidw``. That corpus group is then serialized out. - * ``--follow-dependencies`` - - For each dependency of the input binary of ``abidw``, if it is - found in the directory specified by the ``--added-binaries-dir`` - option, then construct an ABI corpus out of the dependency and add - it to a set of ABI corpora (called an ABI Corpus Group) along with - the ABI corpus of the input binary of the program. The ABI Corpus - Group is then serialized out. - - * ``--list-dependencies`` - - For each dependency of the input binary of``abidw``, if it's found - in the directory specified by the ``--added-binaries-dir`` option, - then the name of the dependency is printed out. * ``--added-binaries-dir | --abd`` <*dir-path*> @@ -87,6 +78,80 @@ Options corpus and added to the set of ABI corpora (called an ABI corpus group) built and serialized. + + * ``--allow-non-exported-interfaces`` + + 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 that final ABI corpus which textual + representation is saved as ``ABIXML``. + + 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`_. + + + * ``--annotate`` + + Annotate the ABIXML output with comments above most elements. The + comments are made of the pretty-printed form types, declaration or + even ELF symbols. The purpose is to make the ABIXML output more + human-readable for debugging or documenting purposes. + + + * ``--btf`` + + Extract ABI information from `BTF`_ debug information, if present in + the given object. + + + * ``--check-alternate-debug-info`` <*elf-path*> + + If the debug info for the file *elf-path* contains a reference to + an `alternate debug info `_ file, ``abidw`` checks + that it can find that alternate debug info file. In that case, it + emits a meaningful success message mentioning the full path to the + alternate debug info file found. Otherwise, it emits an error + code. + + + * ``--check-alternate-debug-info-base-name`` <*elf-path*> + + + Like ``--check-alternate-debug-info``, but in the success message, + only mention the base name of the debug info file; not its full path. + + + * ``--debug-abidiff`` + + Same as ``--abidiff`` but in debug mode. In this mode, error + messages are emitted for types which fail type canonicalization. + + 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 option. + + + * ``--ctf`` + + Extract ABI information from `CTF`_ debug information, if present in + the given object. + + * ``--debug-info-dir | -d`` <*dir-path*> In cases where the debug info for *path-to-elf-file* is in a @@ -107,32 +172,105 @@ Options installed by your system's package manager because then ``abidw`` knows where to find it. - * ``--out-file | -o`` <*file-path*> - This option instructs ``abidw`` to emit the XML representation of - *path-to-elf-file* into the file *file-path*, rather than emitting - it to its standard output. + * ``--debug-type-canonicalization | --debug-tc`` - * ``--noout`` + Debug the type canonicalization process. This is done by using + structural and canonical equality when canonicalizing every single + type. Structural and canonical equality should yield the same + result. If they don't yield the same result for a given type, + then it means that the canonicalization of that type went wrong. + In that case, an error message is emitted and the execution of the + program is aborted. - This option instructs ``abidw`` to not emit the XML representation - of the ABI. So it only reads the ELF and debug information, - builds the internal representation of the ABI and exits. This - option is usually useful for debugging purposes. + This option is available only if the package was configured with + the --enable-debug-type-canonicalization option. - * ``--no-corpus-path`` - Do not emit the path attribute for the ABI corpus. + * ``--drop-private-types`` - * ``--suppressions | suppr`` <*path-to-suppression-specifications-file*> + This option is to be used with the ``--headers-dir`` and/or + ``header-file`` 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 and will + not end up in the abi XML file. - Use a :ref:`suppression specification ` file - located at *path-to-suppression-specifications-file*. 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. ABI artifacts matched by the suppression - specifications are suppressed from the output of this tool. + * ``--drop-undefined-syms`` + + With this option functions or variables for which the (exported) + ELF symbol is undefined are dropped from the internal + representation build by Libabigail to represent the ABI and will + not end up in the abi XML file. + + + * ``--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 that final ABI corpus + which textual representation is saved as ``ABIXML``. + + 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. + + + * ``--follow-dependencies`` + + For each dependency of the input binary of ``abidw``, if it is + found in the directory specified by the ``--added-binaries-dir`` + option, then construct an ABI corpus out of the dependency and add + it to a set of ABI corpora (called an ABI Corpus Group) along with + the ABI corpus of the input binary of the program. The ABI Corpus + Group is then serialized out. + + + + + + * ``--headers-dir | --hd`` + + Specifies where to find the public headers of the binary that the + tool has to consider. The tool will thus filter out types that + are not defined in public headers. + + Note that several public header directories can be specified for + the binary to consider. In that case the ``--header-dir`` option + should be present several times on the command line, like in the + following example: :: + + $ abidw --header-dir /some/path \ + --header-dir /some/other/path \ + binary > binary.abi + + + + .. _abidw_header_file_option_label: + * ``--header-file | --hf`` + + Specifies where to find one of the public headers of the abi file + that the tool has to consider. The tool will thus filter out + types that are not defined in public headers. + + + * ``--help | -h`` + + Display a short help about the command and exit. * ``--kmi-whitelist | --kmi-stablelist |-w`` <*path-to-stablelist*> @@ -153,7 +291,25 @@ Options provided -- then the entire KMI, that is, all publicly defined and exported functions and global variables by the `Linux Kernel`_ binaries is emitted. - + + + * ``--list-dependencies`` + + For each dependency of the input binary of``abidw``, if it's found + in the directory specified by the ``--added-binaries-dir`` option, + then the name of the dependency is printed out. + + + * ``--load-all-types`` + + By default, ``libabigail`` (and thus ``abidw``) only loads types + that are reachable from functions and variables declarations that + are publicly defined and exported by the binary. So only those + types are present in the output of ``abidw``. This option however + makes ``abidw`` load *all* the types defined in the binaries, even + those that are not reachable from public declarations. + + * ``--linux-tree | --lt`` Make ``abidw`` to consider the input path as a path to a directory @@ -177,96 +333,51 @@ Options $ cp vmlinux build-output/modules/4.5.0 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi - * ``--headers-dir | --hd`` - Specifies where to find the public headers of the binary that the - tool has to consider. The tool will thus filter out types that - are not defined in public headers. - Note that several public header directories can be specified for - the binary to consider. In that case the ``--header-dir`` option - should be present several times on the command line, like in the - following example: :: + * ``--no-assume-odr-for-cplusplus`` - $ abidw --header-dir /some/path \ - --header-dir /some/other/path \ - binary > binary.abi + 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. - * ``--header-file | --hf`` + This option disables that assumption and instructs libabigail to + actually actually compare the types to determine if they are + equal. - Specifies where to find one of the public headers of the abi file - that the tool has to consider. The tool will thus filter out - types that are not defined in public headers. - * ``--drop-private-types`` + * ``--no-corpus-path`` + + Do not emit the path attribute for the ABI corpus. - This option is to be used with the ``--headers-dir`` and/or - ``header-file`` 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 and will - not end up in the abi XML file. * ``--no-elf-needed`` Do not include the list of DT_NEEDED dependency names in the corpus. - * ``--drop-undefined-syms`` - - With this option functions or variables for which the (exported) - ELF symbol is undefined are dropped from the internal - representation build by Libabigail to represent the ABI and will - not end up in the abi XML file. - - * ``--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 that final ABI corpus - which textual representation is saved as ``ABIXML``. - - 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-leverage-dwarf-factorization`` - 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 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. - * ``--allow-non-exported-interfaces`` + This option disables those optimizations. - 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 that final ABI corpus which textual - representation is saved as ``ABIXML``. - 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-load-undefined-interfaces`` - 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. + By default, ``libabigail`` (and thus ``abidw``) loads information + about undefined function and variable symbols as well as functions + and variables that are associated with those undefined symbols. + Those are called undefined interfaces. This option however makes + makes ``abidw`` avoid loading information about undefined + interfaces. The resulting XML file thus doesn't contain + information about those undefined interfaces. - Note that this option is turned on by default, unless we are in - the presence of the `Linux Kernel`_. * ``--no-linux-kernel-mode`` @@ -279,25 +390,27 @@ Options ELF binary. It thus considers functions and variables which are defined and exported in the ELF sense. - * ``--check-alternate-debug-info`` <*elf-path*> - If the debug info for the file *elf-path* contains a reference to - an `alternate debug info `_ file, ``abidw`` checks - that it can find that alternate debug info file. In that case, it - emits a meaningful success message mentioning the full path to the - alternate debug info file found. Otherwise, it emits an error - code. + * ``--noout`` - * ``--no-show-locs`` + This option instructs ``abidw`` to not emit the XML representation + of the ABI. So it only reads the ELF and debug information, + builds the internal representation of the ABI and exits. This + option is usually useful for debugging purposes. - In the emitted ABI representation, do not show file, line or column - where ABI artifacts are defined. * ``--no-parameter-names`` In the emitted ABI representation, do not show names of function parameters, just the types. + + * ``--no-show-locs`` + + In the emitted ABI representation, do not show file, line or column + where ABI artifacts are defined. + + * ``--no-write-default-sizes`` In the XML ABI representation, do not write the size-in-bits for @@ -307,113 +420,50 @@ Options 1.8 will not set the default size and will interpret types without a size-in-bits attribute as zero sized. - * ``--type-id-style`` <``sequence``|``hash``> - - This option controls how types are idenfied in the generated XML - files. The default ``sequence`` style just numbers (with - ``type-id-`` as prefix) the types in the order they are - encountered. The ``hash`` style uses a (stable, portable) hash of - libabigail's internal type names and is intended to make the XML - files easier to diff. - - * ``--check-alternate-debug-info-base-name`` <*elf-path*> - - - Like ``--check-alternate-debug-info``, but in the success message, - only mention the base name of the debug info file; not its full path. - - * ``--load-all-types`` - - By default, ``libabigail`` (and thus ``abidw``) only loads types - that are reachable from functions and variables declarations that - are publicly defined and exported by the binary. So only those - types are present in the output of ``abidw``. This option however - makes ``abidw`` load *all* the types defined in the binaries, even - those that are not reachable from public declarations. - - * ``--no-load-undefined-interfaces`` - - By default, ``libabigail`` (and thus ``abidw``) loads information - about undefined function and variable symbols as well as functions - and variables that are associated with those undefined symbols. - Those are called undefined interfaces. This option however makes - makes ``abidw`` avoid loading information about undefined - interfaces. The resulting XML file thus doesn't contain - information about those undefined interfaces. - - * ``--abidiff`` - - Load the ABI of the ELF binary given in argument, save it in - libabigail's XML format in a temporary file; read the ABI from the - temporary XML file and compare the ABI that has been read back - against the ABI of the ELF binary given in argument. The ABIs - should compare equal. If they don't, the program emits a - diagnostic and exits with a non-zero code. - - This is a debugging and sanity check option. - - * ``--debug-abidiff`` - Same as ``--abidiff`` but in debug mode. In this mode, error - messages are emitted for types which fail type canonicalization. + * ``--out-file | -o`` <*file-path*> - 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 option. + This option instructs ``abidw`` to emit the XML representation of + *path-to-elf-file* into the file *file-path*, rather than emitting + it to its standard output. - * ``--debug-type-canonicalization | --debug-tc`` - Debug the type canonicalization process. This is done by using - structural and canonical equality when canonicalizing every single - type. Structural and canonical equality should yield the same - result. If they don't yield the same result for a given type, - then it means that the canonicalization of that type went wrong. - In that case, an error message is emitted and the execution of the - program is aborted. + * ``--stats`` - This option is available only if the package was configured with - the --enable-debug-type-canonicalization option. + Emit statistics about various internal things. - * ``--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. + * ``--suppressions | suppr`` <*path-to-suppression-specifications-file*> - This option disables that assumption and instructs libabigail to - actually actually compare the types to determine if they are - equal. + Use a :ref:`suppression specification ` file + located at *path-to-suppression-specifications-file*. 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. ABI artifacts matched by the suppression + specifications are suppressed from the output of this tool. - * ``--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. + * ``--type-id-style`` <``sequence``|``hash``> - This option disables those optimizations. + This option controls how types are idenfied in the generated XML + files. The default ``sequence`` style just numbers (with + ``type-id-`` as prefix) the types in the order they are + encountered. The ``hash`` style uses a (stable, portable) hash of + libabigail's internal type names and is intended to make the XML + files easier to diff. - * ``--ctf`` - Extract ABI information from `CTF`_ debug information, if present in - the given object. + * ``--verbose`` - * ``--annotate`` + Emit verbose logs about the progress of miscellaneous internal + things. - Annotate the ABIXML output with comments above most elements. The - comments are made of the pretty-printed form types, declaration or - even ELF symbols. The purpose is to make the ABIXML output more - human-readable for debugging or documenting purposes. - * ``--stats`` + * ``--version | -v`` - Emit statistics about various internal things. + Display the version of the program and exit. - * ``--verbose`` - Emit verbose logs about the progress of miscellaneous internal - things. Usage examples ============== diff --git a/tools/abidw.cc b/tools/abidw.cc index 61d4f5ee..9f3f1e03 100644 --- a/tools/abidw.cc +++ b/tools/abidw.cc @@ -197,75 +197,74 @@ display_usage(const string& prog_name, ostream& out) emit_prefix(prog_name, out) << "usage: " << prog_name << " [options] []\n" << " where options can be: \n" - << " --help|-h display this message\n" - << " --version|-v display program version information and exit\n" + << " --abidiff compare the loaded ABI against itself\n" << " --abixml-version display the version of the ABIXML ABI format\n" - << " --debug-info-dir|-d look for debug info under 'dir-path'\n" - << " --headers-dir|--hd the path to headers of the elf file\n" - << " --header-file|--hf the path one header of the elf file\n" - << " --out-file|-o write the output to 'file-path'\n" - << " --noout do not emit anything after reading the binary\n" - << " --suppressions|--suppr specify a suppression file\n" - << " --no-architecture do not emit architecture info in the output\n" - << " --no-corpus-path do not take the path to the corpora into account\n" - << " --no-show-locs do not show location information\n" - << " --short-locs only print filenames rather than paths\n" - << " --drop-private-types drop private types from representation\n" - << " --drop-undefined-syms drop undefined symbols from representation\n" - << " --exported-interfaces-only analyze exported interfaces only\n" - << " --allow-non-exported-interfaces analyze interfaces that " + << " --add-binaries build a corpus group with " + "the added inaries\n" + << " --allow-non-exported-interfaces analyze interfaces that" "might not be exported\n" - << " --no-comp-dir-path do not show compilation path information\n" - << " --no-elf-needed do not show the DT_NEEDED information\n" - << " --no-write-default-sizes do not emit pointer size when it equals" - " the default address size of the translation unit\n" - << " --no-parameter-names do not show names of function parameters\n" - << " --type-id-style type id style (sequence(default): " - "\"type-id-\" + number; hash: hex-digits)\n" + << " --annotate annotate the ABI artifacts emitted in the output\n" +#ifdef WITH_BTF + << " --btf use BTF instead of DWARF in ELF files\n" +#endif << " --check-alternate-debug-info check alternate debug info " "of \n" << " --check-alternate-debug-info-base-name check alternate " "debug info of , and show its base name\n" - << " --load-all-types read all types including those not reachable from " - "exported declarations\n" - << " --no-load-undefined-interfaces do not consider undefined " - "interfaces from the binary" - << " --no-linux-kernel-mode don't consider the input binary as " - "a Linux Kernel binary\n" - << " --kmi-whitelist|--kmi-stablelist|-w path to a linux kernel " - "abi whitelist\n" - << " --linux-tree|--lt emit the ABI for the union of a " - "vmlinux and its modules\n" - << " --vmlinux the path to the vmlinux binary to consider to emit " - "the ABI of the union of vmlinux and its modules\n" - << " --abidiff compare the loaded ABI against itself\n" - << " --add-binaries build a corpus group with " - "the added inaries\n" - << " --follow-dependencies build a corpus group with the dependencies\n" - << " --list-dependencies list the dependencies of a given binary\n" - << " --added-binaries-dir|--abd where to look for dependencies " - "or added binaries\n" +#ifdef WITH_CTF + << " --ctf use CTF instead of DWARF in ELF files\n" +#endif #ifdef WITH_DEBUG_SELF_COMPARISON << " --debug-abidiff debug the process of comparing the loaded ABI against itself\n" #endif + << " --debug-info-dir|-d look for debug info under 'dir-path'\n" #ifdef WITH_DEBUG_TYPE_CANONICALIZATION << " --debug-tc debug the type canonicalization process\n" << " --debug-dc debug the DIE canonicalization process\n" #endif -#ifdef WITH_CTF - << " --ctf use CTF instead of DWARF in ELF files\n" -#endif - << " --no-leverage-dwarf-factorization do not use DWZ optimisations to " - "speed-up the analysis of the binary\n" + << " --drop-private-types drop private types from representation\n" + << " --drop-undefined-syms drop undefined symbols from representation\n" + << " --exported-interfaces-only analyze exported interfaces only\n" + << " --follow-dependencies build a corpus group with the dependencies\n" + << " --headers-dir|--hd the path to headers of the elf file\n" + << " --header-file|--hf the path one header of the elf file\n" + << " --help|-h display this message\n" + << " --kmi-whitelist|--kmi-stablelist|-w path to a linux kernel " + "abi whitelist\n" + << " --list-dependencies list the dependencies of a given binary\n" + << " --added-binaries-dir|--abd where to look for dependencies " + "or added binaries\n" + << " --linux-tree|--lt emit the ABI for the union of a " + "vmlinux and its modules\n" + << " --load-all-types read all types including those not reachable from " + "exported declarations\n" + << " --no-architecture do not emit architecture info in the output\n" << " --no-assume-odr-for-cplusplus do not assume the ODR to speed-up the " "analysis of the binary\n" -#ifdef WITH_BTF - << " --btf use BTF instead of DWARF in ELF files\n" -#endif - << " --annotate annotate the ABI artifacts emitted in the output\n" + << " --no-comp-dir-path do not show compilation path information\n" + << " --no-corpus-path do not take the path to the corpora into account\n" + << " --no-elf-needed do not show the DT_NEEDED information\n" + << " --no-leverage-dwarf-factorization do not use DWZ optimisations to " + "speed-up the analysis of the binary\n" + << " --no-linux-kernel-mode don't consider the input binary as " + "a Linux Kernel binary\n" + << " --no-load-undefined-interfaces do not consider undefined " + "interfaces from the binary" + << " --no-parameter-names do not show names of function parameters\n" + << " --no-show-locs do not show location information\n" + << " --no-write-default-sizes do not emit pointer size when it equals" + " the default address size of the translation unit\n" + << " --noout do not emit anything after reading the binary\n" + << " --out-file|-o write the output to 'file-path'\n" + << " --short-locs only print filenames rather than paths\n" + << " --suppressions|--suppr specify a suppression file\n" + << " --type-id-style type id style (sequence(default): " + "\"type-id-\" + number; hash: hex-digits)\n" << " --stats show statistics about various internal stuff\n" - << " --verbose show verbose messages about internal stuff\n"; - ; + << " --verbose show verbose messages about internal stuff\n" + << " --version|-v display program version information and exit\n" + << " --vmlinux the path to the vmlinux binary to consider to emit " + "the ABI of the union of vmlinux and its modules\n" ; } static bool