1ABICOMPAT(1) Libabigail ABICOMPAT(1)
2
6 abicompat - check ABI compatibility
7 abicompat checks that an application that links against a given shared
9 library is still ABI compatible with a subsequent version of that li‐
10 brary. If the new version of the library introduces an ABI incompati‐
11 bility, then abicompat hints the user at what exactly that incompati‐
12 bility is.
13
15 abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]
16
18 • --help
19 Display a short help about the command and exit.
21 • –version | -v
23 Display the version of the program and exit.
25 • --list-undefined-symbols | -u
27 Display the list of undefined symbols of the application and exit.
29 • --show-base-names | -b
31 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 li‐
36 braries independently of what their directory names are.
37 • --app-debug-info-dir | --appd <path-to-app-debug-info-directory>
39 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 • --lib-debug-info-dir1 | --libd1 <path-to-lib1-debug-info>
46 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 de‐
50 bug info is in a separate set of files.
51 • --lib-debug-info-dir2 | --libd2 <path-to-lib1-debug-info>
53 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 de‐
57 bug info is in a separate set of files.
58 • --suppressions | --suppr <path-to-suppressions>
60 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 • --no-show-locs
67 Do not show information about where in the second shared library
68 the respective type was changed.
69 • --weak-mode
71 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 abicompat --weak-mode <the-application> <the-library>
77 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 abicompat <the-application> <the-library>
84 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 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 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
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 In the later case, the exit code is a 8-bits-wide bit field in which
109 each bit has a specific meaning.
110 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
112 ror.
113 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 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
121 the binaries being compared are different.
122 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 re‐
129 view the ABI changes to decide if they are compatible or not.
130 The remaining bits are not used for the moment.
132
134 • Detecting a possible ABI incompatibility in a new shared library
135 version:
136 $ 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 $ 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 $ 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 $ 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 $ 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 • Compile the first and second versions of the libraries:
245 libtest-0.so and libtest-1.so:
246 $ g++ -g -Wall -shared -o libtest-0.so test0.cc
248 $ g++ -g -Wall -shared -o libtest-1.so test1.cc
249 • Compile the application and link it against the first version of
251 the library, creating the test-app binary:
252 $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
254 • 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 $ 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 2 functions with some indirect sub-type change:
264 [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 $
276 • Now use the weak mode of abicompat, that is, providing just the
278 application and the new version of the library:
279 $ 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 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 $
295
297 Dodji Seketeli
298
300 2014-2021, Red Hat, Inc.
301 Oct 04, 2021 ABICOMPAT(1)