libabigail/doc/manuals/abidiff.rst

.. _abidiff_label:

=======
abidiff
=======

abidiff compares the Application Binary Interfaces (ABI) of two shared
libraries in `ELF`_ format.  It emits a meaningful report describing the
differences between the two ABIs.

For a comprehensive ABI change report that includes changes about
function and variable sub-types, the two input shared libraries must
be accompanied with their debug information in `DWARF`_ format.
Otherwise, only `ELF`_ symbols that were added or removed are
reported.

Invocation
==========

::

  abidiff [options] <first-shared-library> <second-shared-library>

Options
=======

  * --help

    Displays a short help about the command and exit.

  * --debug-info-dir1 <*di-path1*>

    For cases where the debug information for *first-shared-library*
    is split out into a separate file, tells ``abidiff`` where to find
    that separate debug information file.

    Note that *di-path* must point to the root directory under which
    the debug information is arranged in a tree-like manner.  Under
    Red Hat based systems, that directory is usually
    ``<root>/usr/lib/debug``.

    Note also that this option is not mandatory for split debug
    information installed by your system's package manager because
    then ``abidiff`` knows where to find it.

  * --debug-info-dir2 <*di-path2*>

    Like ``--debug-info-dir1``, this options tells ``abidiff`` where
    to find the split debug information for the
    *second-shared-library* file.

  * --stat

    Rather than displaying the detailed ABI differences between
    *first-shared-library* and *second-shared-library*, just display
    some summary statistics about these differences.

  * --symtabs

    Only display the symbol tables of the *first-shared-library* and
    *second-shared-library*.

  * --deleted-fns

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the globally defined functions that got deleted from
    *first-shared-library*.

  * --changed-fns

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the changes in sub-types of the global functions defined in
    *first-shared-library*.

  * --added-fns

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the globally defined functions that were added to
    *second-shared-library*.

  * --deleted-vars

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the globally defined variables that were deleted from
    *first-shared-library*.

  * --changed-vars

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the changes in the sub-types of the global variables defined in
    *first-shared-library*

  * --added-vars

    In the resulting report about the differences between
    *first-shared-library* and *second-shared-library*, only display
    the global variables that were added (defined) to
    *second-shared-library*.

  * --no-linkage-name 

    In the resulting report, do not display the linkage names of
    the added, removed, or changed functions or variables.

  * --no-unreferenced-symbols

    In the resulting report, do not display change information about
    function and variable symbols that are not referenced by any debug
    information.  Note that for these symbols not referenced by any
    debug information, the change information displayed is either
    added or removed symbols.


  * --suppressions <*path-to-suppressions*>

    Use a :ref:`suppression specification <suppr_spec_label>` file located
    at *path-to-suppressions*.

  * --drop <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, drop the globally defined
    functions and variables which name match the regular expression
    *regex*.  As a result, no change involving these functions or
    variables will be emitted in the diff report.

  * --drop-fn <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, drop the globally defined
    functions which name match the regular expression *regex*.  As a
    result, no change involving these functions will be emitted in the
    diff report.

  * --drop-fn <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, drop the globally defined
    functions matching a the regular expression *regex*.  As a result,
    no change involving these functions will be emitted in the diff
    report.

  * --drop-var <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, drop the globally defined
    variables matching a the regular expression *regex*.

  * --keep <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, keep the globally defined
    functions and variables which names match the regular expression
    *regex*.  All other functions and variables are dropped on the
    floor and will thus not appear in the resulting diff report.

  * --keep-fn <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, keep the globally defined
    functions which name match the regular expression *regex*.  All
    other functions are dropped on the floor and will thus not appear
    in the resulting diff report.

  * --keep-var <*regex*>

    When reading the *first-shared-library* and
    *second-shared-library* ELF input files, keep the globally defined
    which names match the regular expression *regex*.  All other
    variables are dropped on the floor and will thus not appear in the
    resulting diff report.

  * --harmless

    In the diff report, display only the :ref:`harmless
    <harmlesschangeconcept_label>` changes.  By default, the harmless
    changes are filtered out of the diff report keep the clutter to a
    minimum and have a greater change to spot real ABI issues.

  * --no-harmful

    In the diff report, do not display the :ref:`harmful
    <harmfulchangeconcept_label>` changes.  By default, only the
    harmful changes are displayed in diff report.

  * --redundant

    In the diff report, do not display redundant changes.  A redundant
    change is a change that has been displayed elsewhere in the report.

Usage examples
==============

  1. Detecting a change in a sub-type of a function: ::

	$ cat -n test-v0.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
		 3	
		 4	struct S0
		 5	{
		 6	  int m0;
		 7	};
		 8	
		 9	void
		10	foo(S0* /*parameter_name*/)
		11	{
		12	  // do something with parameter_name.
		13	}
	$ 
	$ cat -n test-v1.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
		 3	
		 4	struct type_base
		 5	{
		 6	  int inserted;
		 7	};
		 8	
		 9	struct S0 : public type_base
		10	{
		11	  int m0;
		12	};
		13	
		14	void
		15	foo(S0* /*parameter_name*/)
		16	{
		17	  // do something with parameter_name.
		18	}
	$ 
	$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
	$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
	$ 
	$ ../build/tools/abidiff libtest-v0.so libtest-v1.so
	Functions changes summary: 0 Removed, 1 Changed, 0 Added function
	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

	1 function with some indirect sub-type change:

	  [C]'function void foo(S0*)' has some indirect sub-type changes:
		parameter 0 of type 'S0*' has sub-type changes:
		  in pointed to type 'struct S0':
		    size changed from 32 to 64 bits
		    1 base class insertion:
		      struct type_base
		    1 data member change:
		     'int S0::m0' offset changed from 0 to 32
	$


  2. Detecting another change in a sub-type of a function: ::

	$ cat -n test-v0.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
		 3	
		 4	struct S0
		 5	{
		 6	  int m0;
		 7	};
		 8	
		 9	void
		10	foo(S0& /*parameter_name*/)
		11	{
		12	  // do something with parameter_name.
		13	}
	$ 
	$ cat -n test-v1.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
		 3	
		 4	struct S0
		 5	{
		 6	  char inserted_member;
		 7	  int m0;
		 8	};
		 9	
		10	void
		11	foo(S0& /*parameter_name*/)
		12	{
		13	  // do something with parameter_name.
		14	}
	$ 
	$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
	$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
	$ 
	$ ../build/tools/abidiff libtest-v0.so libtest-v1.so
	Functions changes summary: 0 Removed, 1 Changed, 0 Added function
	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

	1 function with some indirect sub-type change:

	  [C]'function void foo(S0&)' has some indirect sub-type changes:
		parameter 0 of type 'S0&' has sub-type changes:
		  in referenced type 'struct S0':
		    size changed from 32 to 64 bits
		    1 data member insertion:
		      'char S0::inserted_member', at offset 0 (in bits)
		    1 data member change:
		     'int S0::m0' offset changed from 0 to 32


	$

  3. Detecting that functions got removed or added to a library: ::

	$ cat -n test-v0.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
		 3	
		 4	struct S0
		 5	{
		 6	  int m0;
		 7	};
		 8	
		 9	void
		10	foo(S0& /*parameter_name*/)
		11	{
		12	  // do something with parameter_name.
		13	}
	$ 
	$ cat -n test-v1.cc
		 1	// Compile this with:
		 2	//   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
		 3	
		 4	struct S0
		 5	{
		 6	  char inserted_member;
		 7	  int m0;
		 8	};
		 9	
		10	void
		11	bar(S0& /*parameter_name*/)
		12	{
		13	  // do something with parameter_name.
		14	}
	$ 
	$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
	$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
	$ 
	$ ../build/tools/abidiff libtest-v0.so libtest-v1.so
	Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

	1 Removed function:
	  'function void foo(S0&)'    {_Z3fooR2S0}

	1 Added function:
	  'function void bar(S0&)'    {_Z3barR2S0}

	$

.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
.. _DWARF: http://www.dwarfstd.org