1ABICC 2.3 2========= 3 4ABI Compliance Checker (ABICC) — a tool for checking backward binary and source-level compatibility of a C/C++ software library. 5 6Contents 7-------- 8 91. [ About ](#about) 102. [ Install ](#install) 113. [ Usage ](#usage) 124. [ Test suite ](#test-suite) 13 14About 15----- 16 17The tool analyzes changes in API/ABI (ABI=API+compiler ABI) that may break binary compatibility and/or source compatibility: changes in calling stack, v-table changes, removed symbols, renamed fields, etc. 18 19The tool can create and compare ABI dumps for header files and shared objects of a library. The ABI dump for a library can also be created by the ABI Dumper tool (https://github.com/lvc/abi-dumper) if shared objects include debug-info. 20 21The tool is intended for developers of software libraries and Linux maintainers who are interested in ensuring backward compatibility, i.e. allow old applications to run or to be recompiled with newer library versions. 22 23The tool is a core of the ABI Tracker and Upstream Tracker projects: https://abi-laboratory.pro/tracker/ 24 25The tool is developed by Andrey Ponomarenko. 26 27Install 28------- 29 30 sudo make install prefix=/usr 31 32###### Requires 33 34* Perl 5 35* GCC C++ (3.0 or newer) 36* GNU Binutils 37* Ctags 38* ABI Dumper (1.1 or newer) 39 40###### Platforms 41 42* Linux 43* Mac OS X 44* Windows 45 46Usage 47----- 48 49###### With ABI Dumper 50 511. Library should be compiled with `-g -Og` GCC options to contain DWARF debug info 52 532. Create ABI dumps for both library versions using the ABI Dumper (https://github.com/lvc/abi-dumper) tool: 54 55 abi-dumper OLD.so -o ABI-1.dump -lver 1 56 abi-dumper NEW.so -o ABI-2.dump -lver 2 57 583. You can filter public ABI with the help of additional `-public-headers` option of the ABI Dumper tool 59 604. Compare ABI dumps to create report: 61 62 abi-compliance-checker -l NAME -old ABI-1.dump -new ABI-2.dump 63 64###### Compile headers 65 66 abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml 67 68`OLD.xml` and `NEW.xml` are XML-descriptors: 69 70 <version> 71 1.0 72 </version> 73 74 <headers> 75 /path/to/headers/ 76 </headers> 77 78 <libs> 79 /path/to/libraries/ 80 </libs> 81 82###### Adv. usage 83 84For advanced usage, see `doc/index.html` or output of `-help` option. 85 86Test suite 87---------- 88 89The tool is tested properly in the ABI Tracker and Upstream Tracker projects, by the community and by the internal test suite: 90 91 abi-compliance-checker -test 92 93There are about 100 test cases for C and 200 test cases for C++ API/ABI breaks. 94