mirror of
git://sourceware.org/git/libabigail.git
synced 2024-12-16 15:04:46 +00:00
d1c2199e08
This patch adds the following convenience command line options
shortcuts:
--suppr, --appd, --libd1, --libd2
for the following command line options:
--suppressions, --app-debug-info-dir, --lib-debug-info-dir1,
--lib-debug-info-dir2
The patch also updates the documentation accordingly.
* doc/manuals/abicompat.rst: Update documentation.
* tools/abicompat.cc (display_usage): Update help strings.
(parse_command_line): Add shortcuts --suppr, --appd, --libd1 and
--libd2.
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
316 lines
8.9 KiB
ReStructuredText
316 lines
8.9 KiB
ReStructuredText
.. _abicompat_label:
|
|
|
|
=========
|
|
abicompat
|
|
=========
|
|
|
|
abicompat checks that an application that links against a given shared
|
|
library is still ABI compatible with a subsequent version of that
|
|
library. If the new version of the library introduces an ABI
|
|
incompatibility, then abicompat hints the user at what exactly that
|
|
incompatibility is.
|
|
|
|
.. _abicompat_invocation_label:
|
|
|
|
Invocation
|
|
==========
|
|
|
|
::
|
|
|
|
abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
|
|
|
|
.. _abicompat_options_label:
|
|
|
|
Options
|
|
=======
|
|
|
|
* ``--help``
|
|
|
|
Display a short help about the command and exit.
|
|
|
|
* `--version | -v`
|
|
|
|
Display the version of the program and exit.
|
|
|
|
* ``--list-undefined-symbols | -u``
|
|
|
|
Display the list of undefined symbols of the application and exit.
|
|
|
|
* ``--show-base-names | -b``
|
|
|
|
In the resulting report emitted by the tool, this option makes the
|
|
application and libraries be referred to by their base names only;
|
|
not by a full absolute name. This can be useful for use in
|
|
scripts that wants to compare names of the application and
|
|
libraries independently of what their directory names are.
|
|
|
|
* ``--app-debug-info-dir | --appd`` <path-to-app-debug-info-directory>
|
|
|
|
Set the path to the directory under which the debug information of
|
|
the application is supposed to be laid out. This is useful for
|
|
application binaries for which the debug info is in a separate set
|
|
of files.
|
|
|
|
* ``--lib-debug-info-dir1 | --libd1`` <path-to-lib1-debug-info>
|
|
|
|
Set the path to the directory under which the debug information of
|
|
the first version of the shared library is supposed to be laid
|
|
out. This is useful for shared library binaries for which the
|
|
debug info is in a separate set of files.
|
|
|
|
* ``--lib-debug-info-dir2 | --libd2`` <path-to-lib1-debug-info>
|
|
|
|
Set the path to the directory under which the debug information of
|
|
the second version of the shared library is supposed to be laid
|
|
out. This is useful for shared library binaries for which the
|
|
debug info is in a separate set of files.
|
|
|
|
* ``--suppressions | --suppr`` <*path-to-suppressions*>
|
|
|
|
Use a :ref:`suppression specification <suppr_spec_label>` file
|
|
located at *path-to-suppressions*. Note that this option can
|
|
appear multiple times on the command line; all the suppression
|
|
specification files are then taken into account.
|
|
|
|
* ``--no-show-locs``
|
|
|
|
Do not show information about where in the *second shared library*
|
|
the respective type was changed.
|
|
|
|
* ``--weak-mode``
|
|
|
|
This triggers the weak mode of ``abicompat``. In this mode, only
|
|
one version of the library is required. That is, abicompat is
|
|
invoked like this: ::
|
|
|
|
abicompat --weak-mode <the-application> <the-library>
|
|
|
|
Note that the ``--weak-mode`` option can even be omitted if only
|
|
one version of the library is given, along with the application;
|
|
in that case, ``abicompat`` automatically switches to operate in
|
|
weak mode: ::
|
|
|
|
abicompat <the-application> <the-library>
|
|
|
|
In this weak mode, the types of functions and variables exported
|
|
by the library and consumed by the application (as in, the symbols
|
|
of the these functions and variables are undefined in the
|
|
application and are defined and exported by the library) are
|
|
compared to the version of these types as expected by the
|
|
application. And if these two versions of types are different,
|
|
``abicompat`` tells the user what the differences are.
|
|
|
|
In other words, in this mode, ``abicompat`` checks that the types
|
|
of the functions and variables exported by the library mean the
|
|
same thing as what the application expects, as far as the ABI is
|
|
concerned.
|
|
|
|
Note that in this mode, `abicompat` doesn't detect exported
|
|
functions or variables (symbols) that are expected by the
|
|
application but that are removed from the library. That is why it
|
|
is called ``weak`` mode.
|
|
|
|
.. _abicompat_return_value_label:
|
|
|
|
Return values
|
|
=============
|
|
|
|
The exit code of the ``abicompat`` command is either 0 if the ABI of
|
|
the binaries being compared are equal, or non-zero if they differ or
|
|
if the tool encountered an error.
|
|
|
|
In the later case, the exit code is a 8-bits-wide bit field in which
|
|
each bit has a specific meaning.
|
|
|
|
The first bit, of value 1, named ``ABIDIFF_ERROR`` means there was an
|
|
error.
|
|
|
|
The second bit, of value 2, named ``ABIDIFF_USAGE_ERROR`` means there
|
|
was an error in the way the user invoked the tool. It might be set,
|
|
for instance, if the user invoked the tool with an unknown command
|
|
line switch, with a wrong number or argument, etc. If this bit is
|
|
set, then the ``ABIDIFF_ERROR`` bit must be set as well.
|
|
|
|
The third bit, of value 4, named ``ABIDIFF_ABI_CHANGE`` means the ABI
|
|
of the binaries being compared are different.
|
|
|
|
The fourth bit, of value 8, named ``ABIDIFF_ABI_INCOMPATIBLE_CHANGE``
|
|
means the ABI of the binaries compared are different in an
|
|
incompatible way. If this bit is set, then the ``ABIDIFF_ABI_CHANGE``
|
|
bit must be set as well. If the ``ABIDIFF_ABI_CHANGE`` is set and the
|
|
``ABIDIFF_INCOMPATIBLE_CHANGE`` is *NOT* set, then it means that the
|
|
ABIs being compared might or might not be compatible. In that case, a
|
|
human being needs to review the ABI changes to decide if they are
|
|
compatible or not.
|
|
|
|
The remaining bits are not used for the moment.
|
|
|
|
.. _abicompat_usage_example_label:
|
|
|
|
Usage examples
|
|
==============
|
|
|
|
* Detecting a possible ABI incompatibility in a new shared library
|
|
version: ::
|
|
|
|
$ cat -n test0.h
|
|
1 struct foo
|
|
2 {
|
|
3 int m0;
|
|
4
|
|
5 foo()
|
|
6 : m0()
|
|
7 {}
|
|
8 };
|
|
9
|
|
10 foo*
|
|
11 first_func();
|
|
12
|
|
13 void
|
|
14 second_func(foo&);
|
|
15
|
|
16 void
|
|
17 third_func();
|
|
$
|
|
|
|
$ cat -n test-app.cc
|
|
1 // Compile with:
|
|
2 // g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
|
|
3
|
|
4 #include "test0.h"
|
|
5
|
|
6 int
|
|
7 main()
|
|
8 {
|
|
9 foo* f = first_func();
|
|
10 second_func(*f);
|
|
11 return 0;
|
|
12 }
|
|
$
|
|
|
|
$ cat -n test0.cc
|
|
1 // Compile this with:
|
|
2 // g++ -g -Wall -shared -o libtest-0.so test0.cc
|
|
3
|
|
4 #include "test0.h"
|
|
5
|
|
6 foo*
|
|
7 first_func()
|
|
8 {
|
|
9 foo* f = new foo();
|
|
10 return f;
|
|
11 }
|
|
12
|
|
13 void
|
|
14 second_func(foo&)
|
|
15 {
|
|
16 }
|
|
17
|
|
18 void
|
|
19 third_func()
|
|
20 {
|
|
21 }
|
|
$
|
|
|
|
$ cat -n test1.h
|
|
1 struct foo
|
|
2 {
|
|
3 int m0;
|
|
4 char m1; /* <-- a new member got added here! */
|
|
5
|
|
6 foo()
|
|
7 : m0(),
|
|
8 m1()
|
|
9 {}
|
|
10 };
|
|
11
|
|
12 foo*
|
|
13 first_func();
|
|
14
|
|
15 void
|
|
16 second_func(foo&);
|
|
17
|
|
18 void
|
|
19 third_func();
|
|
$
|
|
|
|
$ cat -n test1.cc
|
|
1 // Compile this with:
|
|
2 // g++ -g -Wall -shared -o libtest-1.so test1.cc
|
|
3
|
|
4 #include "test1.h"
|
|
5
|
|
6 foo*
|
|
7 first_func()
|
|
8 {
|
|
9 foo* f = new foo();
|
|
10 return f;
|
|
11 }
|
|
12
|
|
13 void
|
|
14 second_func(foo&)
|
|
15 {
|
|
16 }
|
|
17
|
|
18 /* Let's comment out the definition of third_func()
|
|
19 void
|
|
20 third_func()
|
|
21 {
|
|
22 }
|
|
23 */
|
|
$
|
|
|
|
|
|
* Compile the first and second versions of the libraries:
|
|
``libtest-0.so`` and ``libtest-1.so``: ::
|
|
|
|
$ g++ -g -Wall -shared -o libtest-0.so test0.cc
|
|
$ g++ -g -Wall -shared -o libtest-1.so test1.cc
|
|
|
|
* Compile the application and link it against the first version of
|
|
the library, creating the ``test-app`` binary: ::
|
|
|
|
$ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
|
|
|
|
* Now, use ``abicompat`` to see if libtest-1.so is ABI compatible
|
|
with app, with respect to the ABI of libtest-0.so: ::
|
|
|
|
$ abicompat test-app libtest-0.so libtest-1.so
|
|
ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
|
|
Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
|
|
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
|
|
|
|
2 functions with some indirect sub-type change:
|
|
|
|
[C]'function foo* first_func()' has some indirect sub-type changes:
|
|
return type changed:
|
|
in pointed to type 'struct foo':
|
|
size changed from 32 to 64 bits
|
|
1 data member insertion:
|
|
'char foo::m1', at offset 32 (in bits)
|
|
[C]'function void second_func(foo&)' has some indirect sub-type changes:
|
|
parameter 0 of type 'foo&' has sub-type changes:
|
|
referenced type 'struct foo' changed, as reported earlier
|
|
|
|
$
|
|
|
|
|
|
* Now use the weak mode of abicompat, that is, providing just the
|
|
application and the new version of the library: ::
|
|
|
|
$ abicompat --weak-mode test-app libtest-1.so
|
|
functions defined in library
|
|
'libtest-1.so'
|
|
have sub-types that are different from what application
|
|
'test-app'
|
|
expects:
|
|
|
|
function foo* first_func():
|
|
return type changed:
|
|
in pointed to type 'struct foo':
|
|
size changed from 32 to 64 bits
|
|
1 data member insertion:
|
|
'char foo::m1', at offset 32 (in bits)
|
|
|
|
$
|