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