1ABICOMPAT(1)                      Libabigail                      ABICOMPAT(1)
2
3
4

NAME

6       abicompat - check ABI compatibility
7
8       abicompat  checks that an application that links against a given shared
9       library is still ABI compatible  with  a  subsequent  version  of  that
10       library.  If the new version of the library introduces an ABI incompat‐
11       ibility, then abicompat hints the user at what exactly that  incompati‐
12       bility is.
13

INVOCATION

15          abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
16

OPTIONS

18          · --help
19
20            Display a short help about the command and exit.
21
22          · –version | -v
23
24            Display the version of the program and exit.
25
26          · --list-undefined-symbols | -u
27
28            Display the list of undefined symbols of the application and exit.
29
30          · --show-base-names | -b
31
32            In the resulting report emitted by the tool, this option makes the
33            application and libraries be referred to by their base names only;
34            not  by  a  full  absolute  name.   This  can be useful for use in
35            scripts that  wants  to  compare  names  of  the  application  and
36            libraries independently of what their directory names are.
37
38          · --app-debug-info-dir | --appd <path-to-app-debug-info-directory>
39
40            Set the path to the directory under which the debug information of
41            the application is supposed to be laid out.  This  is  useful  for
42            application binaries for which the debug info is in a separate set
43            of files.
44
45          · --lib-debug-info-dir1 | --libd1 <path-to-lib1-debug-info>
46
47            Set the path to the directory under which the debug information of
48            the  first  version  of  the shared library is supposed to be laid
49            out.  This is useful for shared library  binaries  for  which  the
50            debug info is in a separate set of files.
51
52          · --lib-debug-info-dir2 | --libd2 <path-to-lib1-debug-info>
53
54            Set the path to the directory under which the debug information of
55            the second version of the shared library is supposed  to  be  laid
56            out.   This  is  useful  for shared library binaries for which the
57            debug info is in a separate set of files.
58
59          · --suppressions | --suppr <path-to-suppressions>
60
61            Use a suppression specification file located  at  path-to-suppres‐
62            sions.   Note  that  this  option can appear multiple times on the
63            command line; all the suppression  specification  files  are  then
64            taken into account.
65
66          · --no-show-locs
67              Do not show information about where in the second shared library
68              the respective type was changed.
69
70          · --weak-mode
71
72            This triggers the weak mode of abicompat.  In this mode, only  one
73            version of the library is required.  That is, abicompat is invoked
74            like this:
75
76                abicompat --weak-mode <the-application> <the-library>
77
78            Note that the --weak-mode option can even be omitted if  only  one
79            version  of  the  library is given, along with the application; in
80            that case, abicompat automatically switches  to  operate  in  weak
81            mode:
82
83                abicompat <the-application> <the-library>
84
85            In  this  weak mode, the types of functions and variables exported
86            by the library and consumed by the application (as in, the symbols
87            of the these functions and variables are undefined in the applica‐
88            tion and are defined and exported by the library) are compared  to
89            the version of these types as expected by the application.  And if
90            these two versions of types are  different,  abicompat  tells  the
91            user what the differences are.
92
93            In  other  words, in this mode, abicompat checks that the types of
94            the functions and variables exported by the library mean the  same
95            thing  as  what the application expects, as far as the ABI is con‐
96            cerned.
97
98            Note that in this mode, abicompat doesn’t  detect  exported  func‐
99            tions  or variables (symbols) that are expected by the application
100            but that are removed from the library.  That is why it  is  called
101            weak mode.
102

RETURN VALUES

104       The  exit  code  of the abicompat command is either 0 if the ABI of the
105       binaries being compared are equal, or non-zero if they differ or if the
106       tool encountered an error.
107
108       In  the  later  case, the exit code is a 8-bits-wide bit field in which
109       each bit has a specific meaning.
110
111       The first bit, of value 1,  named  ABIDIFF_ERROR  means  there  was  an
112       error.
113
114       The  second  bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
115       an error in the way the user invoked the tool.  It might  be  set,  for
116       instance,  if  the  user  invoked the tool with an unknown command line
117       switch, with a wrong number or argument, etc.  If this bit is set, then
118       the ABIDIFF_ERROR bit must be set as well.
119
120       The  third  bit,  of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
121       the binaries being compared are different.
122
123       The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
124       the  ABI of the binaries compared are different in an incompatible way.
125       If this bit is set, then the ABIDIFF_ABI_CHANGE  bit  must  be  set  as
126       well.   If  the  ABIDIFF_ABI_CHANGE  is  set and the ABIDIFF_INCOMPATI‐
127       BLE_CHANGE is NOT set, then it means that the ABIs being compared might
128       or  might  not  be  compatible.   In  that case, a human being needs to
129       review the ABI changes to decide if they are compatible or not.
130
131       The remaining bits are not used for the moment.
132

USAGE EXAMPLES

134          · Detecting a possible ABI incompatibility in a new  shared  library
135            version:
136
137                $ cat -n test0.h
138                     1  struct foo
139                     2  {
140                     3    int m0;
141                     4
142                     5    foo()
143                     6      : m0()
144                     7    {}
145                     8  };
146                     9
147                    10  foo*
148                    11  first_func();
149                    12
150                    13  void
151                    14  second_func(foo&);
152                    15
153                    16  void
154                    17  third_func();
155                $
156
157                $ cat -n test-app.cc
158                     1  // Compile with:
159                     2  //  g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
160                     3
161                     4  #include "test0.h"
162                     5
163                     6  int
164                     7  main()
165                     8  {
166                     9    foo* f = first_func();
167                    10    second_func(*f);
168                    11    return 0;
169                    12  }
170                $
171
172                $ cat -n test0.cc
173                     1  // Compile this with:
174                     2  //  g++ -g -Wall -shared -o libtest-0.so test0.cc
175                     3
176                     4  #include "test0.h"
177                     5
178                     6  foo*
179                     7  first_func()
180                     8  {
181                     9    foo* f = new foo();
182                    10    return f;
183                    11  }
184                    12
185                    13  void
186                    14  second_func(foo&)
187                    15  {
188                    16  }
189                    17
190                    18  void
191                    19  third_func()
192                    20  {
193                    21  }
194                $
195
196                $ cat -n test1.h
197                     1  struct foo
198                     2  {
199                     3    int  m0;
200                     4    char m1; /* <-- a new member got added here! */
201                     5
202                     6    foo()
203                     7    : m0(),
204                     8      m1()
205                     9    {}
206                    10  };
207                    11
208                    12  foo*
209                    13  first_func();
210                    14
211                    15  void
212                    16  second_func(foo&);
213                    17
214                    18  void
215                    19  third_func();
216                $
217
218                $ cat -n test1.cc
219                     1  // Compile this with:
220                     2  //  g++ -g -Wall -shared -o libtest-1.so test1.cc
221                     3
222                     4  #include "test1.h"
223                     5
224                     6  foo*
225                     7  first_func()
226                     8  {
227                     9    foo* f = new foo();
228                    10    return f;
229                    11  }
230                    12
231                    13  void
232                    14  second_func(foo&)
233                    15  {
234                    16  }
235                    17
236                    18  /* Let's comment out the definition of third_func()
237                    19     void
238                    20     third_func()
239                    21     {
240                    22     }
241                    23  */
242                $
243
244            · Compile   the  first  and  second  versions  of  the  libraries:
245              libtest-0.so and libtest-1.so:
246
247                  $ g++ -g -Wall -shared -o libtest-0.so test0.cc
248                  $ g++ -g -Wall -shared -o libtest-1.so test1.cc
249
250            · Compile the application and link it against the first version of
251              the library, creating the test-app binary:
252
253                  $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
254
255            · Now, use abicompat to see if libtest-1.so is ABI compatible with
256              app, with respect to the ABI of libtest-0.so:
257
258                  $ abicompat test-app libtest-0.so libtest-1.so
259                  ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
260                  Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
261                  Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
262
263                  2 functions with some indirect sub-type change:
264
265                    [C]'function foo* first_func()' has some indirect sub-type changes:
266                      return type changed:
267                        in pointed to type 'struct foo':
268                          size changed from 32 to 64 bits
269                          1 data member insertion:
270                            'char foo::m1', at offset 32 (in bits)
271                    [C]'function void second_func(foo&)' has some indirect sub-type changes:
272                      parameter 0 of type 'foo&' has sub-type changes:
273                        referenced type 'struct foo' changed, as reported earlier
274
275                  $
276
277            · Now use the weak mode of abicompat, that is, providing just  the
278              application and the new version of the library:
279
280                  $ abicompat --weak-mode test-app libtest-1.so
281                  functions defined in library
282                      'libtest-1.so'
283                  have sub-types that are different from what application
284                      'test-app'
285                  expects:
286
287                    function foo* first_func():
288                      return type changed:
289                        in pointed to type 'struct foo':
290                          size changed from 32 to 64 bits
291                          1 data member insertion:
292                            'char foo::m1', at offset 32 (in bits)
293
294                  $
295

AUTHOR

297       Dodji Seketeli
298
300       2014-2019, Red Hat, Inc.
301
302
303
304
305                                 Jul 25, 2019                     ABICOMPAT(1)
Impressum