• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. _abicompat_label:
2
3=========
4abicompat
5=========
6
7abicompat checks that an application that links against a given shared
8library is still ABI compatible with a subsequent version of that
9library.  If the new version of the library introduces an ABI
10incompatibility, then abicompat hints the user at what exactly that
11incompatibility is.
12
13.. _abicompat_invocation_label:
14
15Invocation
16==========
17
18::
19
20  abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
21
22.. _abicompat_options_label:
23
24Options
25=======
26
27  * ``--help``
28
29    Display a short help about the command and exit.
30
31  * `--version | -v`
32
33    Display the version of the program and exit.
34
35  * ``--list-undefined-symbols | -u``
36
37    Display the list of undefined symbols of the application and exit.
38
39  * ``--show-base-names | -b``
40
41    In the resulting report emitted by the tool, this option makes the
42    application and libraries be referred to by their base names only;
43    not by a full absolute name.  This can be useful for use in
44    scripts that wants to compare names of the application and
45    libraries independently of what their directory names are.
46
47  * ``--app-debug-info-dir | --appd`` <path-to-app-debug-info-directory>
48
49    Set the path to the directory under which the debug information of
50    the application is supposed to be laid out.  This is useful for
51    application binaries for which the debug info is in a separate set
52    of files.
53
54  * ``--lib-debug-info-dir1 | --libd1`` <path-to-lib1-debug-info>
55
56    Set the path to the directory under which the debug information of
57    the first version of the shared library is supposed to be laid
58    out.  This is useful for shared library binaries for which the
59    debug info is in a separate set of files.
60
61  * ``--lib-debug-info-dir2 | --libd2`` <path-to-lib1-debug-info>
62
63    Set the path to the directory under which the debug information of
64    the second version of the shared library is supposed to be laid
65    out.  This is useful for shared library binaries for which the
66    debug info is in a separate set of files.
67
68  * ``--suppressions | --suppr`` <*path-to-suppressions*>
69
70    Use a :ref:`suppression specification <suppr_spec_label>` file
71    located at *path-to-suppressions*.  Note that this option can
72    appear multiple times on the command line; all the suppression
73    specification files are then taken into account.
74
75  * ``--no-show-locs``
76
77   Do not show information about where in the *second shared library*
78   the respective type was changed.
79
80  * ``--weak-mode``
81
82    This triggers the weak mode of ``abicompat``.  In this mode, only
83    one version of the library is required.  That is, abicompat is
84    invoked like this: ::
85
86        abicompat --weak-mode <the-application> <the-library>
87
88    Note that the ``--weak-mode`` option can even be omitted if only
89    one version of the library is given, along with the application;
90    in that case, ``abicompat`` automatically switches to operate in
91    weak mode: ::
92
93       abicompat <the-application> <the-library>
94
95    In this weak mode, the types of functions and variables exported
96    by the library and consumed by the application (as in, the symbols
97    of the these functions and variables are undefined in the
98    application and are defined and exported by the library) are
99    compared to the version of these types as expected by the
100    application.  And if these two versions of types are different,
101    ``abicompat`` tells the user what the differences are.
102
103    In other words, in this mode, ``abicompat`` checks that the types
104    of the functions and variables exported by the library mean the
105    same thing as what the application expects, as far as the ABI is
106    concerned.
107
108    Note that in this mode, `abicompat` doesn't detect exported
109    functions or variables (symbols) that are expected by the
110    application but that are removed from the library.  That is why it
111    is called ``weak`` mode.
112
113.. _abicompat_return_value_label:
114
115Return values
116=============
117
118The exit code of the ``abicompat`` command is either 0 if the ABI of
119the binaries being compared are equal, or non-zero if they differ or
120if the tool encountered an error.
121
122In the later case, the exit code is a 8-bits-wide bit field in which
123each bit has a specific meaning.
124
125The first bit, of value 1, named ``ABIDIFF_ERROR`` means there was an
126error.
127
128The second bit, of value 2, named ``ABIDIFF_USAGE_ERROR`` means there
129was an error in the way the user invoked the tool.  It might be set,
130for instance, if the user invoked the tool with an unknown command
131line switch, with a wrong number or argument, etc.  If this bit is
132set, then the ``ABIDIFF_ERROR`` bit must be set as well.
133
134The third bit, of value 4, named ``ABIDIFF_ABI_CHANGE`` means the ABI
135of the binaries being compared are different.
136
137The fourth bit, of value 8, named ``ABIDIFF_ABI_INCOMPATIBLE_CHANGE``
138means the ABI of the binaries compared are different in an
139incompatible way.  If this bit is set, then the ``ABIDIFF_ABI_CHANGE``
140bit must be set as well.  If the ``ABIDIFF_ABI_CHANGE`` is set and the
141``ABIDIFF_INCOMPATIBLE_CHANGE`` is *NOT* set, then it means that the
142ABIs being compared might or might not be compatible.  In that case, a
143human being needs to review the ABI changes to decide if they are
144compatible or not.
145
146The remaining bits are not used for the moment.
147
148.. _abicompat_usage_example_label:
149
150Usage examples
151==============
152
153  * Detecting a possible ABI incompatibility in a new shared library
154    version: ::
155
156	$ cat -n test0.h
157	     1	struct foo
158	     2	{
159	     3	  int m0;
160	     4
161	     5	  foo()
162	     6	    : m0()
163	     7	  {}
164	     8	};
165	     9
166	    10	foo*
167	    11	first_func();
168	    12
169	    13	void
170	    14	second_func(foo&);
171	    15
172	    16	void
173	    17	third_func();
174	$
175
176	$ cat -n test-app.cc
177	     1	// Compile with:
178	     2	//  g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
179	     3
180	     4	#include "test0.h"
181	     5
182	     6	int
183	     7	main()
184	     8	{
185	     9	  foo* f = first_func();
186	    10	  second_func(*f);
187	    11	  return 0;
188	    12	}
189	$
190
191	$ cat -n test0.cc
192	     1	// Compile this with:
193	     2	//  g++ -g -Wall -shared -o libtest-0.so test0.cc
194	     3
195	     4	#include "test0.h"
196	     5
197	     6	foo*
198	     7	first_func()
199	     8	{
200	     9	  foo* f = new foo();
201	    10	  return f;
202	    11	}
203	    12
204	    13	void
205	    14	second_func(foo&)
206	    15	{
207	    16	}
208	    17
209	    18	void
210	    19	third_func()
211	    20	{
212	    21	}
213	$
214
215	$ cat -n test1.h
216	     1	struct foo
217	     2	{
218	     3	  int  m0;
219	     4	  char m1; /* <-- a new member got added here! */
220	     5
221	     6	  foo()
222	     7	  : m0(),
223	     8	    m1()
224	     9	  {}
225	    10	};
226	    11
227	    12	foo*
228	    13	first_func();
229	    14
230	    15	void
231	    16	second_func(foo&);
232	    17
233	    18	void
234	    19	third_func();
235	$
236
237	$ cat -n test1.cc
238	     1	// Compile this with:
239	     2	//  g++ -g -Wall -shared -o libtest-1.so test1.cc
240	     3
241	     4	#include "test1.h"
242	     5
243	     6	foo*
244	     7	first_func()
245	     8	{
246	     9	  foo* f = new foo();
247	    10	  return f;
248	    11	}
249	    12
250	    13	void
251	    14	second_func(foo&)
252	    15	{
253	    16	}
254	    17
255	    18	/* Let's comment out the definition of third_func()
256	    19	   void
257	    20	   third_func()
258	    21	   {
259	    22	   }
260	    23	*/
261	$
262
263
264    * Compile the first and second versions of the libraries:
265      ``libtest-0.so`` and ``libtest-1.so``: ::
266
267	$ g++ -g -Wall -shared -o libtest-0.so test0.cc
268	$ g++ -g -Wall -shared -o libtest-1.so test1.cc
269
270    * Compile the application and link it against the first version of
271      the library, creating the ``test-app`` binary: ::
272
273	$ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
274
275    * Now, use ``abicompat`` to see if libtest-1.so is ABI compatible
276      with app, with respect to the ABI of libtest-0.so: ::
277
278	$ abicompat test-app libtest-0.so libtest-1.so
279	ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
280	Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
281	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
282
283	2 functions with some indirect sub-type change:
284
285	  [C]'function foo* first_func()' has some indirect sub-type changes:
286	    return type changed:
287	      in pointed to type 'struct foo':
288		size changed from 32 to 64 bits
289		1 data member insertion:
290		  'char foo::m1', at offset 32 (in bits)
291	  [C]'function void second_func(foo&)' has some indirect sub-type changes:
292	    parameter 0 of type 'foo&' has sub-type changes:
293	      referenced type 'struct foo' changed, as reported earlier
294
295	$
296
297
298    * Now use the weak mode of abicompat, that is, providing just the
299      application and the new version of the library:  ::
300
301	$ abicompat --weak-mode test-app libtest-1.so
302	functions defined in library
303	    'libtest-1.so'
304	have sub-types that are different from what application
305	    'test-app'
306	expects:
307
308	  function foo* first_func():
309	    return type changed:
310	      in pointed to type 'struct foo':
311		size changed from 32 to 64 bits
312		1 data member insertion:
313		  'char foo::m1', at offset 32 (in bits)
314
315	$
316