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 • --ctf
71 When comparing binaries, extract ABI information from CTF debug
73 information, if present.
74 • --fail-no-debug-info
76 If no debug info was found, then this option makes the program to
78 fail. Otherwise, without this option, the program will attempt to
79 compare properties of the binaries that are not related to debug
80 info, like pure ELF properties.
81 • --ignore-soname
83 Ignore differences in the SONAME when doing a comparison
85 • --weak-mode
87 This triggers the weak mode of abicompat. In this mode, only one
89 version of the library is required. That is, abicompat is invoked
90 like this:
91 abicompat --weak-mode <the-application> <the-library>
93 Note that the --weak-mode option can even be omitted if only one
95 version of the library is given, along with the application; in
96 that case, abicompat automatically switches to operate in weak
97 mode:
98 abicompat <the-application> <the-library>
100 In this weak mode, the types of functions and variables exported
102 by the library and consumed by the application (as in, the symbols
103 of the these functions and variables are undefined in the applica‐
104 tion and are defined and exported by the library) are compared to
105 the version of these types as expected by the application. And if
106 these two versions of types are different, abicompat tells the
107 user what the differences are.
108 In other words, in this mode, abicompat checks that the types of
110 the functions and variables exported by the library mean the same
111 thing as what the application expects, as far as the ABI is con‐
112 cerned.
113 Note that in this mode, abicompat doesn’t detect exported func‐
115 tions or variables (symbols) that are expected by the application
116 but that are removed from the library. That is why it is called
117 weak mode.
118
120 The exit code of the abicompat command is either 0 if the ABI of the
121 binaries being compared are equal, or non-zero if they differ or if the
122 tool encountered an error.
123 In the later case, the exit code is a 8-bits-wide bit field in which
125 each bit has a specific meaning.
126 The first bit, of value 1, named ABIDIFF_ERROR means there was an er‐
128 ror.
129 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
131 an error in the way the user invoked the tool. It might be set, for
132 instance, if the user invoked the tool with an unknown command line
133 switch, with a wrong number or argument, etc. If this bit is set, then
134 the ABIDIFF_ERROR bit must be set as well.
135 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
137 the binaries being compared are different.
138 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
140 the ABI of the binaries compared are different in an incompatible way.
141 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
142 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
143 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
144 or might not be compatible. In that case, a human being needs to re‐
145 view the ABI changes to decide if they are compatible or not.
146 The remaining bits are not used for the moment.
148
150 • Detecting a possible ABI incompatibility in a new shared library
151 version:
152 $ cat -n test0.h
154 1 struct foo
155 2 {
156 3 int m0;
157 4
158 5 foo()
159 6 : m0()
160 7 {}
161 8 };
162 9
163 10 foo*
164 11 first_func();
165 12
166 13 void
167 14 second_func(foo&);
168 15
169 16 void
170 17 third_func();
171 $
172 $ cat -n test-app.cc
174 1 // Compile with:
175 2 // g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
176 3
177 4 #include "test0.h"
178 5
179 6 int
180 7 main()
181 8 {
182 9 foo* f = first_func();
183 10 second_func(*f);
184 11 return 0;
185 12 }
186 $
187 $ cat -n test0.cc
189 1 // Compile this with:
190 2 // g++ -g -Wall -shared -o libtest-0.so test0.cc
191 3
192 4 #include "test0.h"
193 5
194 6 foo*
195 7 first_func()
196 8 {
197 9 foo* f = new foo();
198 10 return f;
199 11 }
200 12
201 13 void
202 14 second_func(foo&)
203 15 {
204 16 }
205 17
206 18 void
207 19 third_func()
208 20 {
209 21 }
210 $
211 $ cat -n test1.h
213 1 struct foo
214 2 {
215 3 int m0;
216 4 char m1; /* <-- a new member got added here! */
217 5
218 6 foo()
219 7 : m0(),
220 8 m1()
221 9 {}
222 10 };
223 11
224 12 foo*
225 13 first_func();
226 14
227 15 void
228 16 second_func(foo&);
229 17
230 18 void
231 19 third_func();
232 $
233 $ cat -n test1.cc
235 1 // Compile this with:
236 2 // g++ -g -Wall -shared -o libtest-1.so test1.cc
237 3
238 4 #include "test1.h"
239 5
240 6 foo*
241 7 first_func()
242 8 {
243 9 foo* f = new foo();
244 10 return f;
245 11 }
246 12
247 13 void
248 14 second_func(foo&)
249 15 {
250 16 }
251 17
252 18 /* Let's comment out the definition of third_func()
253 19 void
254 20 third_func()
255 21 {
256 22 }
257 23 */
258 $
259 • Compile the first and second versions of the libraries:
261 libtest-0.so and libtest-1.so:
262 $ g++ -g -Wall -shared -o libtest-0.so test0.cc
264 $ g++ -g -Wall -shared -o libtest-1.so test1.cc
265 • Compile the application and link it against the first version of
267 the library, creating the test-app binary:
268 $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc
270 • Now, use abicompat to see if libtest-1.so is ABI compatible with
272 app, with respect to the ABI of libtest-0.so:
273 $ abicompat test-app libtest-0.so libtest-1.so
275 ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
276 Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
277 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
278 2 functions with some indirect sub-type change:
280 [C]'function foo* first_func()' has some indirect sub-type changes:
282 return type changed:
283 in pointed to type 'struct foo':
284 size changed from 32 to 64 bits
285 1 data member insertion:
286 'char foo::m1', at offset 32 (in bits)
287 [C]'function void second_func(foo&)' has some indirect sub-type changes:
288 parameter 0 of type 'foo&' has sub-type changes:
289 referenced type 'struct foo' changed, as reported earlier
290 $
292 • Now use the weak mode of abicompat, that is, providing just the
294 application and the new version of the library:
295 $ abicompat --weak-mode test-app libtest-1.so
297 functions defined in library
298 'libtest-1.so'
299 have sub-types that are different from what application
300 'test-app'
301 expects:
302 function foo* first_func():
304 return type changed:
305 in pointed to type 'struct foo':
306 size changed from 32 to 64 bits
307 1 data member insertion:
308 'char foo::m1', at offset 32 (in bits)
309 $
311
313 Dodji Seketeli
314
316 2014-2023, Red Hat, Inc.
317 Nov 20, 2023 ABICOMPAT(1)