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