An abstraction of a diff between between two abi corpus. More...

#include <abg-comparison.h>

Classes
class	diff_stats
	This is a document class that aims to capture statistics about the changes carried by a corpus_diff type. More...

struct	priv

Public Types
typedef shared_ptr< diff_stats >	diff_stats_sptr
	A convenience typedef for a shared pointer to diff_stats. More...

Public Member Functions
const string_function_ptr_map &	added_functions ()
	Getter for the added functions of the diff. More...

const string_type_base_sptr_map &	added_unreachable_types () const
	Getter for a map of added types that are not reachable from global functions/variables. More...

const vector< type_base_sptr > &	added_unreachable_types_sorted () const
	Getter of a sorted vector of added types that are not reachable from global functions/variables. More...

const string_elf_symbol_map &	added_unrefed_function_symbols () const
	Getter for function symbols not referenced by any debug info and that got added. More...

const string_elf_symbol_map &	added_unrefed_variable_symbols () const
	Getter for variable symbols not referenced by any debug info and that got added. More...

const string_var_ptr_map &	added_variables () const
	Getter for the added variables of the diff. More...

void	append_child_node (diff_sptr)
	Append a new child node to the vector of children nodes for the current instance of corpus_diff node. More...

const diff_stats &	apply_filters_and_suppressions_before_reporting ()
	Apply the different filters that are registered to be applied to the diff tree; that includes the categorization filters. Also, apply the suppression interpretation filters. More...

bool	architecture_changed () const
	Test if the architecture of the underlying corpus has changed. More...

virtual void	chain_into_hierarchy ()
	Populate the vector of children node of the corpus_diff type. More...

const string_function_decl_diff_sptr_map &	changed_functions () const
	Getter for the functions which signature didn't change, but which do have some indirect changes in their parms. More...

const function_decl_diff_sptrs_type &	changed_functions_sorted () const
	Getter for a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms. More...

const string_diff_sptr_map &	changed_unreachable_types () const
	Getter for a map of changed types that are not reachable from global functions/variables. More...

const vector< diff_sptr > &	changed_unreachable_types_sorted () const
	Getter of a sorted vector of changed types that are not reachable from global functions/variables. More...

const string_var_diff_sptr_map &	changed_variables ()
	Getter for the non-sorted map of variables which signature didn't change but which do have some indirect changes in some sub-types. More...

const var_diff_sptrs_type &	changed_variables_sorted ()
	Getter for the sorted vector of variables which signature didn't change but which do have some indirect changes in some sub-types. More...

const vector< diff * > &	children_nodes () const

const diff_context_sptr	context () const
	Getter of the diff context of this diff. More...

const string_function_ptr_map &	deleted_functions () const
	Getter for the deleted functions of the diff. More...

const string_type_base_sptr_map &	deleted_unreachable_types () const
	Getter for a map of deleted types that are not reachable from global functions/variables. More...

const vector< type_base_sptr > &	deleted_unreachable_types_sorted () const
	Getter of a sorted vector of deleted types that are not reachable from global functions/variables. More...

const string_elf_symbol_map &	deleted_unrefed_function_symbols () const
	Getter for function symbols not referenced by any debug info and that got deleted. More...

const string_elf_symbol_map &	deleted_unrefed_variable_symbols () const
	Getter for variable symbols not referenced by any debug info and that got deleted. More...

const string_var_ptr_map &	deleted_variables () const
	Getter for the variables that got deleted from the first subject of the diff. More...

bool	do_log () const
	Test if logging was requested. More...

void	do_log (bool)
	Request logging, or not. More...

corpus_sptr	first_corpus () const

edit_script &	function_changes () const

diff_maps &	get_leaf_diffs ()
	Get the set of maps that contain leaf nodes. A leaf node being a node with a local change. More...

const diff_maps &	get_leaf_diffs () const
	Get the set of maps that contain leaf nodes. A leaf node being a node with a local change. More...

const string &	get_pretty_representation () const

bool	has_changes () const
	Return true iff the current corpus_diff node carries a change. More...

bool	has_incompatible_changes () const
	Test if the current instance of corpus_diff carries changes that we are sure are incompatible. By incompatible change we mean a change that "breaks" the ABI of the corpus we are looking at. More...

bool	has_net_changes () const
	Test if the current instance of corpus_diff carries changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes. More...

bool	has_net_subtype_changes () const
	Test if the current instance of corpus_diff carries subtype changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes. More...

function_decl_diff_sptrs_type &	incompatible_changed_functions ()
	Getter of the set of diff nodes representing incompatibly changed functions. More...

const function_decl_diff_sptrs_type &	incompatible_changed_functions () const
	Getter of the set of diff nodes representing incompatibly changed functions. More...

var_diff_sptrs_type &	incompatible_changed_variables ()
	Getter of the set of diff nodes representing incompatibly changed global variables. More...

const var_diff_sptrs_type &	incompatible_changed_variables () const
	Getter of the set of diff nodes representing incompatibly changed global variables. More...

void	mark_leaf_diff_nodes ()
	Walks the diff nodes associated to the current corpus diff and mark those that carry local changes. They are said to be leaf diff nodes. More...

virtual void	report (ostream &out, const string &indent="") const
	Report the diff in a serialized form. More...

corpus_sptr	second_corpus () const

bool	soname_changed () const
	Test if the soname of the underlying corpus has changed. More...

virtual bool	traverse (diff_node_visitor &v)
	Traverse the diff sub-tree under the current instance corpus_diff. More...

edit_script &	variable_changes () const

Protected Member Functions
	corpus_diff (corpus_sptr first, corpus_sptr second, diff_context_sptr ctxt=diff_context_sptr())
	Constructor for corpus_diff. More...

void	finish_diff_type ()
	Finish building the current instance of corpus_diff. More...

Friends
void	apply_suppressions (const corpus_diff *diff_tree)
	Walk a corpus_diff tree and appply the suppressions carried by the context. If the suppression applies to a given node then categorize the node into the SUPPRESSED_CATEGORY category and propagate that categorization. More...

corpus_diff_sptr	compute_diff (const corpus_sptr f, const corpus_sptr s, diff_context_sptr ctxt)
	Compute the diff between two instances of corpus. More...

class	default_reporter

class	leaf_reporter

void	maybe_report_unreachable_type_changes (const corpus_diff &d, const corpus_diff::diff_stats &s, const string &indent, ostream &out)
	Report changes about types that are not reachable from global functions and variables, in a given. More...

Detailed Description

An abstraction of a diff between between two abi corpus.

Definition at line 2485 of file abg-comparison.h.

Member Typedef Documentation

◆ diff_stats_sptr

typedef shared_ptr<diff_stats> diff_stats_sptr

A convenience typedef for a shared pointer to diff_stats.

Definition at line 2505 of file abg-comparison.h.

Constructor & Destructor Documentation

◆ corpus_diff()

corpus_diff	(	corpus_sptr	first,
		corpus_sptr	second,
		diff_context_sptr	ctxt = `diff_context_sptr()`
	)

protected

Constructor for corpus_diff.

Parameters

first	the first corpus of the diff.
second	the second corpus of the diff.
ctxt	the diff context to use. Note that this context object must stay alive at least during the life time of the current instance of corpus_diff. Otherwise memory corruption issues occur.

Definition at line 11703 of file abg-comparison.cc.

Member Function Documentation

◆ added_functions()

const string_function_ptr_map & added_functions ( )

Getter for the added functions of the diff.

Returns: the added functions of the diff.

Definition at line 11828 of file abg-comparison.cc.

◆ added_unreachable_types()

const string_type_base_sptr_map & added_unreachable_types ( ) const

Getter for a map of added types that are not reachable from global functions/variables.

Returns: a map that associates pretty representation of added unreachable types and said types.

Definition at line 11987 of file abg-comparison.cc.

◆ added_unreachable_types_sorted()

const vector< type_base_sptr > & added_unreachable_types_sorted ( ) const

Getter of a sorted vector of added types that are not reachable from global functions/variables.

Returns: a sorted vector of added types that are not reachable from global functions/variables. The types are lexicographically sorted by considering their pretty representation.

Definition at line 11997 of file abg-comparison.cc.

◆ added_unrefed_function_symbols()

const string_elf_symbol_map & added_unrefed_function_symbols ( ) const

Getter for function symbols not referenced by any debug info and that got added.

Returns: a map of elf function symbols not referenced by any debug info and that got added.

Definition at line 11934 of file abg-comparison.cc.

◆ added_unrefed_variable_symbols()

const string_elf_symbol_map & added_unrefed_variable_symbols ( ) const

Getter for variable symbols not referenced by any debug info and that got added.

Returns: a map of elf variable symbols not referenced by any debug info and that got added.

Definition at line 11952 of file abg-comparison.cc.

◆ added_variables()

const string_var_ptr_map & added_variables ( ) const

Getter for the added variables of the diff.

Returns: the map of added variable.

Definition at line 11882 of file abg-comparison.cc.

◆ append_child_node()

void append_child_node ( diff_sptr d )

Append a new child node to the vector of children nodes for the current instance of corpus_diff node.

Note that the vector of children nodes for the current instance of corpus_diff node must remain sorted, using diff_less_than_functor.

Parameters

d	the new child node. Note that the life time of the object held by `d` will thus equal the life time of the current instance of corpus_diff.

Definition at line 11761 of file abg-comparison.cc.

◆ apply_filters_and_suppressions_before_reporting()

const corpus_diff::diff_stats & apply_filters_and_suppressions_before_reporting ( )

Apply the different filters that are registered to be applied to the diff tree; that includes the categorization filters. Also, apply the suppression interpretation filters.

After the filters are applied, this function calculates some statistics about the changes carried by the current instance of corpus_diff. These statistics are represented by an instance of corpus_diff::diff_stats.

This member function is called by the reporting function corpus_diff::report().

Note that for a given instance of corpus_diff, this function applies the filters and suppressions only the first time it is invoked. Subsequent invocations just return the instance of corpus_diff::diff_stats that was cached after the first invocation.

Returns: a reference to the statistics about the changes carried by the current instance of corpus_diff.

Definition at line 12196 of file abg-comparison.cc.

◆ architecture_changed()

bool architecture_changed ( ) const

Test if the architecture of the underlying corpus has changed.

Returns: true iff the architecture has changed.

Definition at line 11814 of file abg-comparison.cc.

◆ chain_into_hierarchy()

void chain_into_hierarchy ( )

virtual

Populate the vector of children node of the corpus_diff type.

The children node can then later be retrieved using corpus_diff::children_node().

Definition at line 11683 of file abg-comparison.cc.

◆ changed_functions()

const string_function_decl_diff_sptr_map & changed_functions ( ) const

Getter for the functions which signature didn't change, but which do have some indirect changes in their parms.

Returns: a non-sorted map of functions which signature didn't change, but which do have some indirect changes in their parms. The key of the map is a unique identifier for the function; it's usually made of the name and version of the underlying ELF symbol of the function for corpora that were built from ELF files.

Definition at line 11840 of file abg-comparison.cc.

◆ changed_functions_sorted()

const function_decl_diff_sptrs_type & changed_functions_sorted ( ) const

Getter for a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms.

Returns: a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms.

Definition at line 11849 of file abg-comparison.cc.

◆ changed_unreachable_types()

const string_diff_sptr_map & changed_unreachable_types ( ) const

Getter for a map of changed types that are not reachable from global functions/variables.

Returns: a map that associates pretty representation of changed unreachable types and said types.

Definition at line 12013 of file abg-comparison.cc.

◆ changed_unreachable_types_sorted()

const vector< diff_sptr > & changed_unreachable_types_sorted ( ) const

Getter of a sorted vector of changed types that are not reachable from global functions/variables.

Returns: a sorted vector of changed types that are not reachable from global functions/variables. The diffs are lexicographically sorted by considering their pretty representation.

Definition at line 12023 of file abg-comparison.cc.

◆ changed_variables()

const string_var_diff_sptr_map & changed_variables ( )

Getter for the non-sorted map of variables which signature didn't change but which do have some indirect changes in some sub-types.

Returns: the non-sorted map of changed variables.

Definition at line 11890 of file abg-comparison.cc.

◆ changed_variables_sorted()

const var_diff_sptrs_type & changed_variables_sorted ( )

Getter for the sorted vector of variables which signature didn't change but which do have some indirect changes in some sub-types.

Returns: a sorted vector of changed variables.

Definition at line 11898 of file abg-comparison.cc.

◆ children_nodes()

const vector< diff * > & children_nodes ( ) const

Returns: the children nodes of the current instance of corpus_diff.

Definition at line 11747 of file abg-comparison.cc.

◆ context()

const diff_context_sptr context ( ) const

Getter of the diff context of this diff.

Returns: the diff context for this diff.

Definition at line 12030 of file abg-comparison.cc.

◆ deleted_functions()

const string_function_ptr_map & deleted_functions ( ) const

Getter for the deleted functions of the diff.

Returns: the the deleted functions of the diff.

Definition at line 11821 of file abg-comparison.cc.

◆ deleted_unreachable_types()

const string_type_base_sptr_map & deleted_unreachable_types ( ) const

Getter for a map of deleted types that are not reachable from global functions/variables.

Returns: a map that associates pretty representation of deleted unreachable types and said types.

Definition at line 11961 of file abg-comparison.cc.

◆ deleted_unreachable_types_sorted()

const vector< type_base_sptr > & deleted_unreachable_types_sorted ( ) const

Getter of a sorted vector of deleted types that are not reachable from global functions/variables.

Returns: a sorted vector of deleted types that are not reachable from global functions/variables. The types are lexicographically sorted by considering their pretty representation.

Definition at line 11971 of file abg-comparison.cc.

◆ deleted_unrefed_function_symbols()

const string_elf_symbol_map & deleted_unrefed_function_symbols ( ) const

Getter for function symbols not referenced by any debug info and that got deleted.

Returns: a map of elf function symbols not referenced by any debug info and that got deleted.

Definition at line 11925 of file abg-comparison.cc.

◆ deleted_unrefed_variable_symbols()

const string_elf_symbol_map & deleted_unrefed_variable_symbols ( ) const

Getter for variable symbols not referenced by any debug info and that got deleted.

Returns: a map of elf variable symbols not referenced by any debug info and that got deleted.

Definition at line 11943 of file abg-comparison.cc.

◆ deleted_variables()

const string_var_ptr_map & deleted_variables ( ) const

Getter for the variables that got deleted from the first subject of the diff.

Returns: the map of deleted variable.

Definition at line 11875 of file abg-comparison.cc.

◆ do_log() [1/2]

bool do_log ( ) const

Test if logging was requested.

Returns: true iff logging was requested.

Definition at line 11725 of file abg-comparison.cc.

◆ do_log() [2/2]

void do_log ( bool f )

Request logging, or not.

Parameters

f	true iff logging is requested.

Definition at line 11732 of file abg-comparison.cc.

◆ finish_diff_type()

void finish_diff_type ( )

protected

Finish building the current instance of corpus_diff.

Definition at line 11713 of file abg-comparison.cc.

◆ first_corpus()

corpus_sptr first_corpus ( ) const

Returns: the first corpus of the diff.

Definition at line 11737 of file abg-comparison.cc.

◆ function_changes()

edit_script & function_changes ( ) const

Returns: the bare edit script of the functions changed as recorded by the diff.

Definition at line 11794 of file abg-comparison.cc.

◆ get_leaf_diffs() [1/2]

diff_maps & get_leaf_diffs ( )

Get the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Returns: the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Definition at line 12359 of file abg-comparison.cc.

◆ get_leaf_diffs() [2/2]

const diff_maps & get_leaf_diffs ( ) const

Get the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Returns: the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Definition at line 12368 of file abg-comparison.cc.

◆ get_pretty_representation()

const string & get_pretty_representation ( ) const

Returns: the pretty representation for the current instance of corpus_diff

Definition at line 12036 of file abg-comparison.cc.

◆ has_changes()

bool has_changes ( ) const

Return true iff the current corpus_diff node carries a change.

Returns: true iff the current diff node carries a change.

Definition at line 12055 of file abg-comparison.cc.

◆ has_incompatible_changes()

bool has_incompatible_changes ( ) const

Test if the current instance of corpus_diff carries changes that we are sure are incompatible. By incompatible change we mean a change that "breaks" the ABI of the corpus we are looking at.

In concrete terms, this function considers the following changes as being ABI incompatible for sure:

a soname change
if exported functions or variables got removed

Note that subtype changes *can* represent changes that break ABI too. But they also can be changes that are OK, ABI-wise.

It's up to the user to provide suppression specifications to say explicitely which subtype change is OK. The remaining sub-type changes are then considered to be ABI incompatible. But to test if such ABI incompatible subtype changes are present you need to use the function corpus_diff::has_net_subtype_changes()

Returns: true iff the current instance of corpus_diff carries changes that we are sure are ABI incompatible.

Definition at line 12096 of file abg-comparison.cc.

◆ has_net_changes()

bool has_net_changes ( ) const

Test if the current instance of corpus_diff carries changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes.

Returns: true iff the the current instance of corpus_diff carries subtype changes that are deemed incompatible ABI changes.

Definition at line 12172 of file abg-comparison.cc.

◆ has_net_subtype_changes()

bool has_net_subtype_changes ( ) const

Test if the current instance of corpus_diff carries subtype changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes.

Returns: true iff the the current instance of corpus_diff carries subtype changes that are deemed incompatible ABI changes.

Definition at line 12154 of file abg-comparison.cc.

◆ incompatible_changed_functions() [1/2]

function_decl_diff_sptrs_type & incompatible_changed_functions ( )

Getter of the set of diff nodes representing incompatibly changed functions.

Returns: the set of diff nodes representing incompatibly changed functions

Definition at line 11867 of file abg-comparison.cc.

◆ incompatible_changed_functions() [2/2]

const function_decl_diff_sptrs_type & incompatible_changed_functions ( ) const

Getter of the set of diff nodes representing incompatibly changed functions.

Returns: the set of diff nodes representing incompatibly changed functions

Definition at line 11858 of file abg-comparison.cc.

◆ incompatible_changed_variables() [1/2]

var_diff_sptrs_type & incompatible_changed_variables ( )

Getter of the set of diff nodes representing incompatibly changed global variables.

Returns: the set of diff nodes representing incompatibly changed global variables.

Definition at line 11916 of file abg-comparison.cc.

◆ incompatible_changed_variables() [2/2]

const var_diff_sptrs_type & incompatible_changed_variables ( ) const

Getter of the set of diff nodes representing incompatibly changed global variables.

Returns: the set of diff nodes representing incompatibly changed global variables.

Definition at line 11907 of file abg-comparison.cc.

◆ mark_leaf_diff_nodes()

void mark_leaf_diff_nodes ( )

Walks the diff nodes associated to the current corpus diff and mark those that carry local changes. They are said to be leaf diff nodes.

The marked nodes are available from the corpus_diff::get_leaf_diffs() function.

Definition at line 12334 of file abg-comparison.cc.

◆ report()

void report	(	ostream &	out,
		const string &	indent = `""`
	)		const

virtual

Report the diff in a serialized form.

Parameters

out	the stream to serialize the diff to.
indent	the prefix to use for the indentation of this serialization.

Definition at line 12378 of file abg-comparison.cc.

◆ second_corpus()

corpus_sptr second_corpus ( ) const

Returns: the second corpus of the diff.

Definition at line 11742 of file abg-comparison.cc.

◆ soname_changed()

bool soname_changed ( ) const

Test if the soname of the underlying corpus has changed.

Returns: true iff the soname has changed.

Definition at line 11807 of file abg-comparison.cc.

◆ traverse()

bool traverse ( diff_node_visitor & v )

virtual

Traverse the diff sub-tree under the current instance corpus_diff.

Parameters

v	the visitor to invoke on each diff node of the sub-tree.

Returns: true if the traversing has to keep going on, false otherwise.

Definition at line 12389 of file abg-comparison.cc.

◆ variable_changes()

edit_script & variable_changes ( ) const

Returns: the bare edit script of the variables changed as recorded by the diff.

Definition at line 11800 of file abg-comparison.cc.

Friends And Related Function Documentation

◆ apply_suppressions

void apply_suppressions ( const corpus_diff * diff_tree )

friend

Walk a corpus_diff tree and appply the suppressions carried by the context. If the suppression applies to a given node then categorize the node into the SUPPRESSED_CATEGORY category and propagate that categorization.

Parameters

diff_tree the diff tree to apply the suppressions to.

Definition at line 13357 of file abg-comparison.cc.

◆ compute_diff

corpus_diff_sptr compute_diff	(	const corpus_sptr	f,
		const corpus_sptr	s,
		diff_context_sptr	ctxt
	)

friend

Compute the diff between two instances of corpus.

Note that the two corpora must have been created in the same environment, otherwise, this function aborts.

Parameters

f	the first corpus to consider for the diff.
s	the second corpus to consider for the diff.
ctxt	the diff context to use.

Returns: the resulting diff between the two corpus.

Definition at line 12485 of file abg-comparison.cc.

◆ default_reporter

friend class default_reporter

friend

Definition at line 2656 of file abg-comparison.h.

◆ leaf_reporter

friend class leaf_reporter

friend

Definition at line 2657 of file abg-comparison.h.

◆ maybe_report_unreachable_type_changes

void maybe_report_unreachable_type_changes	(	const corpus_diff &	d,
		const corpus_diff::diff_stats &	s,
		const string &	indent,
		ostream &	out
	)

friend

Report changes about types that are not reachable from global functions and variables, in a given.

Parameters

corpus_diff.
d	the corpus_diff to consider.
s	the statistics of the changes, after filters and suppressions are reported. This is typically what is returned by corpus_diff::apply_filters_and_suppressions_before_reporting().
indent	the indendation string (usually a string of white spaces) to use for indentation during the reporting.
out	the output stream to emit the report to.

Definition at line 1363 of file abg-reporter-priv.cc.

The documentation for this class was generated from the following files:

/home/builder/shared/snapshots/worker/libabigail-snapshots-html-doc/build/include/abg-comparison.h
/home/builder/shared/snapshots/worker/libabigail-snapshots-html-doc/build/src/abg-comparison.cc

Classes

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ diff_stats_sptr

Constructor & Destructor Documentation

◆ corpus_diff()

Member Function Documentation

◆ added_functions()

◆ added_unreachable_types()

◆ added_unreachable_types_sorted()

◆ added_unrefed_function_symbols()

◆ added_unrefed_variable_symbols()

◆ added_variables()

◆ append_child_node()

◆ apply_filters_and_suppressions_before_reporting()

◆ architecture_changed()

◆ chain_into_hierarchy()

◆ changed_functions()

◆ changed_functions_sorted()

◆ changed_unreachable_types()

◆ changed_unreachable_types_sorted()

◆ changed_variables()

◆ changed_variables_sorted()

◆ children_nodes()

◆ context()

◆ deleted_functions()

◆ deleted_unreachable_types()

◆ deleted_unreachable_types_sorted()

◆ deleted_unrefed_function_symbols()

◆ deleted_unrefed_variable_symbols()

◆ deleted_variables()

◆ do_log() [1/2]

◆ do_log() [2/2]

◆ finish_diff_type()

◆ first_corpus()

◆ function_changes()

◆ get_leaf_diffs() [1/2]

◆ get_leaf_diffs() [2/2]

◆ get_pretty_representation()

◆ has_changes()

◆ has_incompatible_changes()

◆ has_net_changes()

◆ has_net_subtype_changes()

◆ incompatible_changed_functions() [1/2]

◆ incompatible_changed_functions() [2/2]

◆ incompatible_changed_variables() [1/2]

◆ incompatible_changed_variables() [2/2]

◆ mark_leaf_diff_nodes()

◆ report()

◆ second_corpus()

◆ soname_changed()

◆ traverse()

◆ variable_changes()

Friends And Related Function Documentation

◆ apply_suppressions

◆ compute_diff

◆ default_reporter

◆ leaf_reporter

◆ maybe_report_unreachable_type_changes