From patchwork Mon Oct 2 10:21:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dodji Seketeli X-Patchwork-Id: 76938 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 62B48385C414 for ; Mon, 2 Oct 2023 10:21:22 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 62B48385C414 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1696242082; bh=ikBQ15d7TpB3t7UASOL/bpwjoeo99BX7Rcbb3ipYbJE=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Help:List-Subscribe:From:Reply-To:From; b=mj59WVOQ9hmfdegi6FoLDN2da0gKNEZcpLxL5q+NwyLUCXJRH0lLDcnO0cv/KiEI0 Fkc3/IEzfDrgaYTlGJI015W9GjU7S9z2eBQE198hZIKCGtr5HwZgVneDw9f40g6ig9 6BHg/yGoXbt9pgnv3OGSoHg5f62z7M7xjXJ0E+5w= 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.133.124]) by sourceware.org (Postfix) with ESMTPS id 89C35385B530 for ; Mon, 2 Oct 2023 10:21:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 89C35385B530 Received: from mail-qk1-f197.google.com (mail-qk1-f197.google.com [209.85.222.197]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-388-E9l0s4YLNUm_euzmWhgHeQ-1; Mon, 02 Oct 2023 06:21:05 -0400 X-MC-Unique: E9l0s4YLNUm_euzmWhgHeQ-1 Received: by mail-qk1-f197.google.com with SMTP id af79cd13be357-774382db0a5so1773121585a.2 for ; Mon, 02 Oct 2023 03:21:05 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696242065; x=1696846865; h=mime-version:user-agent:message-id:date:organization:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=ikBQ15d7TpB3t7UASOL/bpwjoeo99BX7Rcbb3ipYbJE=; b=vU0nwBMnfV1Doh7hASkHRcGsv/qOytt8Vl3PD8GzVYn/UAbCYWqeC8cY3n1g8cA7Du bAypFFRcC21QfYVOKtrKiMWgG0oMR3J1Qof1MBUZpvk7CND5cjeuasY4O5TjTrToeUoe szIfv0RP+YsQeKQRpJnt3j34uuYvgjPtX5UheNspEjfREA4M3g37xsdiaUxJ/WW5eB9s sBMbmQOf4PeWSuNYPUlgwAGsYtK+gcAUU0HVbVrU1KqRzVpnmbab41YODFZCYqOX+93e TFXcCZ2bIq9ekmqdn7s+gmoLzOrPky5anvKT/FlVPrEAZCjltYY/RYQJVytbw07DruAx 8l/Q== X-Gm-Message-State: AOJu0YyhPlv/LyLVcvdiDpgxlsAyXAjMUtm6CD+xGu/kCXYtp4kaMzLS y+Lyl5CNC/3NE9f+WTa4nrmzs1isQW0IM5UYeyRTyccCGRQe4Dsz7xsNJdKYE7C7++lo4ph0hsp 5fL4/+9mYrLsLUiPf+ce5JmURdJqu X-Received: by 2002:a0c:aa8e:0:b0:647:21d2:21d2 with SMTP id f14-20020a0caa8e000000b0064721d221d2mr9219400qvb.14.1696242064847; Mon, 02 Oct 2023 03:21:04 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEaUgHZFHNugVTR0CQVKzrzKMrUFdWcIP672Cfv3tf94emI4bxUWEWFbdNp8KCZil1sKPh4ww== X-Received: by 2002:a0c:aa8e:0:b0:647:21d2:21d2 with SMTP id f14-20020a0caa8e000000b0064721d221d2mr9219388qvb.14.1696242064235; Mon, 02 Oct 2023 03:21:04 -0700 (PDT) Received: from localhost ([88.120.130.27]) by smtp.gmail.com with ESMTPSA id m23-20020ae9e017000000b007757f6558b3sm3166043qkk.95.2023.10.02.03.21.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 02 Oct 2023 03:21:03 -0700 (PDT) Received: by localhost (Postfix, from userid 1000) id 25BB5B4FD2; Mon, 2 Oct 2023 12:21:01 +0200 (CEST) To: libabigail@sourceware.org Cc: dodji@redhat.com Subject: [PATCH, applied] libabigail-concepts.rst: Sort the properties of the directives Organization: Red Hat / France X-Operating-System: CentOS Stream release 9 X-URL: http://www.redhat.com Date: Mon, 02 Oct 2023 12:21:01 +0200 Message-ID: <87h6n9mik2.fsf@redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.9 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_H3, RCVD_IN_MSPIKE_WL, 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-Help: List-Subscribe: , X-Patchwork-Original-From: Dodji Seketeli via Libabigail From: Dodji Seketeli Reply-To: Dodji Seketeli Errors-To: libabigail-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libabigail" Hello, In the documentation for the suppression directives, the properties of the directives were not sorted, making it hard to look for a particular one. This patch sorts the properties in the lexicographic order. * doc/manuals/libabigail-concepts.rst: Sort the properties in the lexicographic order. Signed-off-by: Dodji Seketeli Applied to master --- doc/manuals/libabigail-concepts.rst | 561 +++++++++++++++------------- 1 file changed, 295 insertions(+), 266 deletions(-) diff --git a/doc/manuals/libabigail-concepts.rst b/doc/manuals/libabigail-concepts.rst index 4f26932c..a447abb8 100644 --- a/doc/manuals/libabigail-concepts.rst +++ b/doc/manuals/libabigail-concepts.rst @@ -213,6 +213,17 @@ If none of the above properties are provided, then the The potential properties of this sections are listed below: +* ``file_name_not_regexp`` + + Usage: + + ``file_name_not_regexp`` ``=`` <:ref:`regular-expression `> + + Prevents the system from loading the file which name does not match + the regular expression specified as value of this property. + + + * ``file_name_regexp`` Usage: @@ -222,14 +233,16 @@ The potential properties of this sections are listed below: Prevents the system from loading the file which name matches the regular expression specified as value of this property. -* ``file_name_not_regexp`` - Usage: +* ``label`` - ``file_name_not_regexp`` ``=`` <:ref:`regular-expression `> + Usage: - Prevents the system from loading the file which name does not match - the regular expression specified as value of this property. + ``label`` ``=`` + + Define a label for the section. A label is just an informative + string that might be used by the tool to refer to a type suppression + in error messages. * ``soname_regexp`` @@ -254,16 +267,6 @@ The potential properties of this sections are listed below: property. Note that this property also works on an abixml file if it contains a SONAME property. -* ``label`` - - Usage: - - ``label`` ``=`` - - Define a label for the section. A label is just an informative - string that might be used by the tool to refer to a type suppression - in error messages. - ``[suppress_type]`` $$$$$$$$$$$$$$$$$$$ @@ -274,154 +277,124 @@ of the following properties must be provided: ``file_name_regexp``, ``file_name_not_regexp``, ``soname_regexp``, ``soname_not_regexp``, ``name``, ``name_regexp``, - ``name_not_regexp``, ``type_kind``, ``source_location_not_in``, - ``source_location_not_regexp``. + ``name_not_regexp``, ``source_location_not_in``, + ``source_location_not_regexp``, ``type_kind``. If none of the above properties are provided, then the ``[suppress_type]`` directive is simply ignored. The potential properties of this sections are listed below: -* ``file_name_regexp`` - - Usage: - - ``file_name_regexp`` ``=`` <:ref:`regular-expression `> - - Suppresses change reports about ABI artifacts that are defined in a - binary file which name matches the regular expression specified as - value of this property. - -* ``file_name_not_regexp`` - - Usage: - - ``file_name_not_regexp`` ``=`` <:ref:`regular-expression `> - Suppresses change reports about ABI artifacts that are defined in a - binary file which name does not match the regular expression - specified as value of this property. + .. _suppr_accessed_through_property_label: +* ``accessed_through`` -* ``soname_regexp`` + Usage: - Usage: + ``accessed_through`` ``=`` - ``soname_regexp`` ``=`` <:ref:`regular-expression `> + Suppress change reports involving a type which is referred to either + directly or through a pointer or a reference. The potential values + of this property are the predefined keywords below: - Suppresses change reports about ABI artifacts that are defined in a - shared library which SONAME property matches the regular expression - specified as value of this property. + * ``direct`` -* ``soname_not_regexp`` + So if the ``[suppress_type]`` contains the property + description: :: - Usage: + accessed_through = direct - ``soname_not_regexp`` ``=`` <:ref:`regular-expression `> + then changes about a type that is referred-to + directly (i.e, not through a pointer or a reference) + are going to be suppressed. - Suppresses change reports about ABI artifacts that are defined in a - shared library which SONAME property does not match the regular - expression specified as value of this property. + * ``pointer`` -* ``name_regexp`` + If the ``accessed_through`` property is set to the + value ``pointer`` then changes about a type that is + referred-to through a pointer are going to be + suppressed. - Usage: + * ``reference`` - ``name_regexp`` ``=`` <:ref:`regular-expression `> + If the ``accessed_through`` property is set to the + value ``reference`` then changes about a type that is + referred-to through a reference are going to be + suppressed. - Suppresses change reports involving types whose name matches the - regular expression specified as value of this property. + * ``reference-or-pointer`` + If the ``accessed_through`` property is set to the + value ``reference-or-pointer`` then changes about a + type that is referred-to through either a reference + or a pointer are going to be suppressed. -* ``name_not_regexp`` + For an extensive example of how to use this property, please check + out the example below about :ref:`suppressing change reports about + types accessed either directly or through pointers + `. - Usage: - ``name_not_regexp`` ``=`` <:ref:`regular-expression `> +.. _suppr_changed_enumerators_label: - Suppresses change reports involving types whose name does *NOT* match - the regular expression specified as value of this property. Said - otherwise, this property specifies which types to keep, rather than - types to suppress from reports. +* ``changed_enumerators`` -* ``name`` + Usage: - Usage: + ``changed_enumerators`` ``=`` + + Suppresses change reports involving changes in the value of + enumerators of a given enum type. This property is applied if the + ``type_kind`` property is set to the value ``enum``, at least. The + value of the ``changed_enumerators`` is a comma-separated list of + the enumerators that the user expects to change. For instance: :: - ``name`` ``=`` + changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1 - Suppresses change reports involving types whose name equals the value - of this property. -* ``type_kind`` +* ``drop`` Usage: - ``type_kind`` ``=`` ``class`` | ``struct`` | ``union`` | ``enum`` | - ``array`` | ``typedef`` | ``builtin`` - - Suppresses change reports involving a certain kind of type. The kind - of type to suppress change reports for is specified by the possible - values listed above: - - - ``class``: suppress change reports for class types. Note that - even if class types don't exist for C, this value still - triggers the suppression of change reports for struct types, - in C. In C++ however, it should do what it suggests. - - - ``struct``: suppress change reports for struct types in C or C++. - Note that the value ``class`` above is a super-set of this - one. - - - ``union``: suppress change reports for union types. - - - ``enum``: suppress change reports for enum types. - - - ``array``: suppress change reports for array types. - - - ``typedef``: suppress change reports for typedef types. - - - ``builtin``: suppress change reports for built-in (or native) - types. Example of built-in types are char, int, unsigned int, - etc. + ``drop`` ``=`` yes | no - .. _suppr_source_location_not_in_label: + If a type is matched by a suppression specification which contains + the "drop" property set to "yes" (or to "true") then the type is not + even going to be represented in the internal representation of the + ABI being analyzed. This property makes its enclosing suppression + specification to be applied in the :ref:`early suppression + specification mode `. The net effect + is that it potentially reduces the memory used to represent the ABI + being analyzed. -* ``source_location_not_in`` + Please note that for this property to be effective, the enclosing + suppression specification must have at least one of the following + properties specified: ``name_regexp``, ``name``, ``name_regexp``, + ``source_location_not_in`` or ``source_location_not_regexp``. - Usage: - ``source_location_not_in`` ``=`` <``list-of-file-paths``> +* ``file_name_not_regexp`` - Suppresses change reports involving a type which is defined in a file - which path is *NOT* listed in the value ``list-of-file-paths``. Note - that the value is a comma-separated list of file paths e.g, this - property :: - - source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h + Usage: - suppresses change reports about all the types that are *NOT* defined - in header files whose path end up with the strings - libabigail/abg-ir.h or libabigail/abg-dwarf-reader.h. + ``file_name_not_regexp`` ``=`` <:ref:`regular-expression `> - .. _suppr_source_location_not_regexp_label: + Suppresses change reports about ABI artifacts that are defined in a + binary file which name does not match the regular expression + specified as value of this property. -* ``source_location_not_regexp`` - Usage: +* ``file_name_regexp`` - ``source_location_not_regexp`` ``=`` <:ref:`regular-expression `> + Usage: - Suppresses change reports involving a type which is defined in a file - which path does *NOT* match the :ref:`regular expression - ` provided as value of the property. E.g, this - property :: + ``file_name_regexp`` ``=`` <:ref:`regular-expression `> - source_location_not_regexp = libabigail/abg-.*\\.h + Suppresses change reports about ABI artifacts that are defined in a + binary file which name matches the regular expression specified as + value of this property. - suppresses change reports involving all the types that are *NOT* - defined in header files whose path match the regular expression - provided a value of the property. .. _suppr_has_data_member_label: @@ -471,6 +444,7 @@ whose names match the regular expression ``^private_data_member``. In other words, it would match any type which contains data members whose names start with the string "private_data_member". + .. _suppr_has_data_member_inserted_at_label: * ``has_data_member_inserted_at`` @@ -616,6 +590,7 @@ names start with the string "private_data_member". } + .. _suppr_has_size_change_property_label: * ``has_size_change`` @@ -632,103 +607,144 @@ and Those properties will not match a type change if the size of the type changes, unless the ``has_size_changes`` property is set to ``yes``. + .. _suppr_label_property_label: - .. _suppr_accessed_through_property_label: - -* ``accessed_through`` +* ``label`` Usage: - ``accessed_through`` ``=`` + ``label`` ``=`` - Suppress change reports involving a type which is referred to either - directly or through a pointer or a reference. The potential values - of this property are the predefined keywords below: + Define a label for the section. A label is just an informative + string that might be used by a tool to refer to a type suppression in + error messages. - * ``direct`` - So if the ``[suppress_type]`` contains the property - description: :: +* ``name`` - accessed_through = direct + Usage: - then changes about a type that is referred-to - directly (i.e, not through a pointer or a reference) - are going to be suppressed. + ``name`` ``=`` - * ``pointer`` + Suppresses change reports involving types whose name equals the value + of this property. - If the ``accessed_through`` property is set to the - value ``pointer`` then changes about a type that is - referred-to through a pointer are going to be - suppressed. - * ``reference`` +* ``name_not_regexp`` - If the ``accessed_through`` property is set to the - value ``reference`` then changes about a type that is - referred-to through a reference are going to be - suppressed. + Usage: - * ``reference-or-pointer`` + ``name_not_regexp`` ``=`` <:ref:`regular-expression `> - If the ``accessed_through`` property is set to the - value ``reference-or-pointer`` then changes about a - type that is referred-to through either a reference - or a pointer are going to be suppressed. + Suppresses change reports involving types whose name does *NOT* match + the regular expression specified as value of this property. Said + otherwise, this property specifies which types to keep, rather than + types to suppress from reports. - For an extensive example of how to use this property, please check - out the example below about :ref:`suppressing change reports about - types accessed either directly or through pointers - `. -* ``drop`` +* ``name_regexp`` Usage: - ``drop`` ``=`` yes | no + ``name_regexp`` ``=`` <:ref:`regular-expression `> - If a type is matched by a suppression specification which contains - the "drop" property set to "yes" (or to "true") then the type is not - even going to be represented in the internal representation of the - ABI being analyzed. This property makes its enclosing suppression - specification to be applied in the :ref:`early suppression - specification mode `. The net effect - is that it potentially reduces the memory used to represent the ABI - being analyzed. + Suppresses change reports involving types whose name matches the + regular expression specified as value of this property. - Please note that for this property to be effective, the enclosing - suppression specification must have at least one of the following - properties specified: ``name_regexp``, ``name``, ``name_regexp``, - ``source_location_not_in`` or ``source_location_not_regexp``. - .. _suppr_label_property_label: +* ``soname_not_regexp`` -* ``label`` + Usage: + + ``soname_not_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports about ABI artifacts that are defined in a + shared library which SONAME property does not match the regular + expression specified as value of this property. + + +* ``soname_regexp`` + + Usage: + + ``soname_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports about ABI artifacts that are defined in a + shared library which SONAME property matches the regular expression + specified as value of this property. + + .. _suppr_source_location_not_in_label: + +* ``source_location_not_in`` Usage: - ``label`` ``=`` + ``source_location_not_in`` ``=`` <``list-of-file-paths``> - Define a label for the section. A label is just an informative - string that might be used by a tool to refer to a type suppression in - error messages. + Suppresses change reports involving a type which is defined in a file + which path is *NOT* listed in the value ``list-of-file-paths``. Note + that the value is a comma-separated list of file paths e.g, this + property :: + + source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h -.. _suppr_changed_enumerators_label: + suppresses change reports about all the types that are *NOT* defined + in header files whose path end up with the strings + libabigail/abg-ir.h or libabigail/abg-dwarf-reader.h. -* ``changed_enumerators`` + .. _suppr_source_location_not_regexp_label: - Usage: - ``changed_enumerators`` ``=`` - - Suppresses change reports involving changes in the value of - enumerators of a given enum type. This property is applied if the - ``type_kind`` property is set to the value ``enum``, at least. The - value of the ``changed_enumerators`` is a comma-separated list of - the enumerators that the user expects to change. For instance: :: +* ``source_location_not_regexp`` + + Usage: + + ``source_location_not_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports involving a type which is defined in a file + which path does *NOT* match the :ref:`regular expression + ` provided as value of the property. E.g, this + property :: + + source_location_not_regexp = libabigail/abg-.*\\.h + + suppresses change reports involving all the types that are *NOT* + defined in header files whose path match the regular expression + provided a value of the property. + + +* ``type_kind`` + + Usage: + + ``type_kind`` ``=`` ``class`` | ``struct`` | ``union`` | ``enum`` | + ``array`` | ``typedef`` | ``builtin`` + + Suppresses change reports involving a certain kind of type. The kind + of type to suppress change reports for is specified by the possible + values listed above: + + - ``class``: suppress change reports for class types. Note that + even if class types don't exist for C, this value still + triggers the suppression of change reports for struct types, + in C. In C++ however, it should do what it suggests. + + - ``struct``: suppress change reports for struct types in C or C++. + Note that the value ``class`` above is a super-set of this + one. + + - ``union``: suppress change reports for union types. + + - ``enum``: suppress change reports for enum types. + + - ``array``: suppress change reports for array types. + + - ``typedef``: suppress change reports for typedef types. + + - ``builtin``: suppress change reports for built-in (or native) + types. Example of built-in types are char, int, unsigned int, + etc. - changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1 ``[suppress_function]`` $$$$$$$$$$$$$$$$$$$$$$$$ @@ -751,25 +767,62 @@ If none of the above properties are provided, then the The potential properties of this sections are: -* ``label`` + + .. _suppr_change_kind_property_label: + +* ``change_kind`` Usage: - ``label`` ``=`` + ``change_kind`` ``=`` - This property is the same as the :ref:`label property - ` defined above. + Specifies the kind of changes this suppression specification should + apply to. The possible values of this property as well as their + meaning are listed below: + - ``function-subtype-change`` -* ``file_name_regexp`` + This suppression specification applies to functions + that which have at least one sub-type that has + changed. - Usage: + - ``added-function`` - ``file_name_regexp`` ``=`` <:ref:`regular-expression `> + This suppression specification applies to functions + that have been added to the binary. - Suppresses change reports about ABI artifacts that are defined in a - binary file which name matches the regular expression specified as - value of this property. + - ``deleted-function`` + + This suppression specification applies to functions + that have been removed from the binary. + + - ``all`` + + This suppression specification applies to functions + that have all of the changes above. Note that not + providing the ``change_kind`` property at all is + equivalent to setting it to the value ``all``. + + +* ``drop`` + + Usage: + + ``drop`` ``=`` yes | no + + If a function is matched by a suppression specification which + contains the "drop" property set to "yes" (or to "true") then the + function is not even going to be represented in the internal + representation of the ABI being analyzed. This property makes its + enclosing suppression specification to be applied in the :ref:`early + suppression specification mode `. The + net effect is that it potentially reduces the memory used to + represent the ABI being analyzed. + + Please note that for this property to be effective, the enclosing + suppression specification must have at least one of the following + properties specified: ``name_regexp``, ``name``, ``name_regexp``, + ``source_location_not_in`` or ``source_location_not_regexp``. * ``file_name_not_regexp`` @@ -782,25 +835,26 @@ The potential properties of this sections are: binary file which name does not match the regular expression specified as value of this property. -* ``soname_regexp`` + +* ``file_name_regexp`` Usage: - ``soname_regexp`` ``=`` <:ref:`regular-expression `> + ``file_name_regexp`` ``=`` <:ref:`regular-expression `> Suppresses change reports about ABI artifacts that are defined in a - shared library which SONAME property matches the regular expression - specified as value of this property. + binary file which name matches the regular expression specified as + value of this property. -* ``soname_not_regexp`` - Usage: +* ``label`` - ``soname_not_regexp`` ``=`` <:ref:`regular-expression `> + Usage: - Suppresses change reports about ABI artifacts that are defined in a - shared library which SONAME property does not match the regular - expression specified as value of this property. + ``label`` ``=`` + + This property is the same as the :ref:`label property + ` defined above. * ``name`` @@ -812,24 +866,6 @@ The potential properties of this sections are: Suppresses change reports involving functions whose name equals the value of this property. -* ``name_regexp`` - - Usage: - - ``name_regexp`` ``=`` <:ref:`regular-expression `> - - Suppresses change reports involving functions whose name matches the - regular expression specified as value of this property. - - Let's consider the case of functions that have several symbol names. - This happens when the underlying symbol for the function has - aliases. Each symbol name is actually one alias name. - - In this case, if the regular expression matches the name of - at least one of the aliases names, then it must match the names of - all of the aliases of the function for the directive to actually - suppress the diff reports for said function. - * ``name_not_regexp`` @@ -843,41 +879,24 @@ The potential properties of this sections are: The rules for functions that have several symbol names are the same rules as for the ``name_regexp`` property above. - .. _suppr_change_kind_property_label: - -* ``change_kind`` +* ``name_regexp`` Usage: - ``change_kind`` ``=`` - - Specifies the kind of changes this suppression specification should - apply to. The possible values of this property as well as their - meaning are listed below: - - - ``function-subtype-change`` - - This suppression specification applies to functions - that which have at least one sub-type that has - changed. - - - ``added-function`` - - This suppression specification applies to functions - that have been added to the binary. - - - ``deleted-function`` + ``name_regexp`` ``=`` <:ref:`regular-expression `> - This suppression specification applies to functions - that have been removed from the binary. + Suppresses change reports involving functions whose name matches the + regular expression specified as value of this property. - - ``all`` + Let's consider the case of functions that have several symbol names. + This happens when the underlying symbol for the function has + aliases. Each symbol name is actually one alias name. - This suppression specification applies to functions - that have all of the changes above. Note that not - providing the ``change_kind`` property at all is - equivalent to setting it to the value ``all``. + In this case, if the regular expression matches the name of + at least one of the aliases names, then it must match the names of + all of the aliases of the function for the directive to actually + suppress the diff reports for said function. * ``parameter`` @@ -928,6 +947,7 @@ The potential properties of this sections are: other words, this is the third parameter and it's a reference on a type that starts with the string "foo". + * ``return_type_name`` Usage: @@ -937,6 +957,7 @@ The potential properties of this sections are: Suppresses change reports involving functions whose return type name equals the value of this property. + * ``return_type_regexp`` Usage: @@ -946,6 +967,29 @@ The potential properties of this sections are: Suppresses change reports involving functions whose return type name matches the regular expression specified as value of this property. + +* ``soname_regexp`` + + Usage: + + ``soname_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports about ABI artifacts that are defined in a + shared library which SONAME property matches the regular expression + specified as value of this property. + + +* ``soname_not_regexp`` + + Usage: + + ``soname_not_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports about ABI artifacts that are defined in a + shared library which SONAME property does not match the regular + expression specified as value of this property. + + * ``symbol_name`` Usage: @@ -955,6 +999,7 @@ The potential properties of this sections are: Suppresses change reports involving functions whose symbol name equals the value of this property. + * ``symbol_name_regexp`` Usage: @@ -972,6 +1017,7 @@ The potential properties of this sections are: the aliases of the function for the directive to actually suppress the diff reports for said function. + * ``symbol_name_not_regexp`` Usage: @@ -981,6 +1027,7 @@ The potential properties of this sections are: Suppresses change reports involving functions whose symbol name does not match the regular expression specified as value of this property. + * ``symbol_version`` Usage: @@ -990,6 +1037,7 @@ The potential properties of this sections are: Suppresses change reports involving functions whose symbol version equals the value of this property. + * ``symbol_version_regexp`` Usage: @@ -999,25 +1047,6 @@ The potential properties of this sections are: Suppresses change reports involving functions whose symbol version matches the regular expression specified as value of this property. -* ``drop`` - - Usage: - - ``drop`` ``=`` yes | no - - If a function is matched by a suppression specification which - contains the "drop" property set to "yes" (or to "true") then the - function is not even going to be represented in the internal - representation of the ABI being analyzed. This property makes its - enclosing suppression specification to be applied in the :ref:`early - suppression specification mode `. The - net effect is that it potentially reduces the memory used to - represent the ABI being analyzed. - - Please note that for this property to be effective, the enclosing - suppression specification must have at least one of the following - properties specified: ``name_regexp``, ``name``, ``name_regexp``, - ``source_location_not_in`` or ``source_location_not_regexp``. ``[suppress_variable]`` $$$$$$$$$$$$$$$$$$$$$$$$