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,23 +277,102 @@ 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`` + + .. _suppr_accessed_through_property_label: + +* ``accessed_through`` + + Usage: + + ``accessed_through`` ``=`` + + 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: + + * ``direct`` + + So if the ``[suppress_type]`` contains the property + description: :: + + accessed_through = direct + + then changes about a type that is referred-to + directly (i.e, not through a pointer or a reference) + are going to be suppressed. + + * ``pointer`` + + 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`` + + 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. + + * ``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. + + 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 + `. + + +.. _suppr_changed_enumerators_label: + +* ``changed_enumerators`` Usage: - ``file_name_regexp`` ``=`` <:ref:`regular-expression `> + ``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: :: + + changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1 + + +* ``drop`` + + Usage: + + ``drop`` ``=`` yes | no + + 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. + + 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``. - 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`` @@ -303,125 +385,16 @@ The potential properties of this sections are listed below: 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: - - ``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. - -* ``name_regexp`` - - Usage: - - ``name_regexp`` ``=`` <:ref:`regular-expression `> - - Suppresses change reports involving types whose name matches the - regular expression specified as value of this property. - - -* ``name_not_regexp`` - - Usage: - - ``name_not_regexp`` ``=`` <:ref:`regular-expression `> - - 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. - -* ``name`` - - Usage: - - ``name`` ``=`` - - Suppresses change reports involving types whose name equals the value - of this 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. - - .. _suppr_source_location_not_in_label: - -* ``source_location_not_in`` - - Usage: - - ``source_location_not_in`` ``=`` <``list-of-file-paths``> - - 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 - - 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. - - .. _suppr_source_location_not_regexp_label: - -* ``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. .. _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,76 +607,6 @@ 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_accessed_through_property_label: - -* ``accessed_through`` - - Usage: - - ``accessed_through`` ``=`` - - 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: - - * ``direct`` - - So if the ``[suppress_type]`` contains the property - description: :: - - accessed_through = direct - - then changes about a type that is referred-to - directly (i.e, not through a pointer or a reference) - are going to be suppressed. - - * ``pointer`` - - 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`` - - 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. - - * ``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. - - 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`` - - Usage: - - ``drop`` ``=`` yes | no - - 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. - - 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: * ``label`` @@ -714,21 +619,132 @@ changes, unless the ``has_size_changes`` property is set to ``yes``. string that might be used by a tool to refer to a type suppression in error messages. -.. _suppr_changed_enumerators_label: -* ``changed_enumerators`` +* ``name`` + + Usage: + + ``name`` ``=`` + + Suppresses change reports involving types whose name equals the value + of this property. + + +* ``name_not_regexp`` + + Usage: + + ``name_not_regexp`` ``=`` <:ref:`regular-expression `> + + 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. + + +* ``name_regexp`` + + Usage: + + ``name_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports involving types whose name matches the + regular expression specified as value of this property. + + +* ``soname_not_regexp`` 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: :: + ``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: + + ``source_location_not_in`` ``=`` <``list-of-file-paths``> + + 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 + + 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. + + .. _suppr_source_location_not_regexp_label: + + +* ``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,101 +767,9 @@ If none of the above properties are provided, then the The potential properties of this sections are: -* ``label`` - - Usage: - - ``label`` ``=`` - - This property is the same as the :ref:`label property - ` defined above. - - -* ``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. - -* ``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. - - -* ``name`` - - Usage: - - ``name`` ``=`` - - 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`` - - Usage: - - ``name_not_regexp`` ``=`` <:ref:`regular-expression `> - - Suppresses change reports involving functions whose names don't match - the regular expression specified as value of this property. - - 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`` Usage: @@ -880,6 +804,101 @@ The potential properties of this sections are: 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`` + + 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. + + +* ``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. + + +* ``label`` + + Usage: + + ``label`` ``=`` + + This property is the same as the :ref:`label property + ` defined above. + + +* ``name`` + + Usage: + + ``name`` ``=`` + + Suppresses change reports involving functions whose name equals the + value of this property. + + +* ``name_not_regexp`` + + Usage: + + ``name_not_regexp`` ``=`` <:ref:`regular-expression `> + + Suppresses change reports involving functions whose names don't match + the regular expression specified as value of this property. + + The rules for functions that have several symbol names are the same + rules as for the ``name_regexp`` property above. + + +* ``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. + + * ``parameter`` Usage: @@ -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]`` $$$$$$$$$$$$$$$$$$$$$$$$