148 lines
4.4 KiB
Plaintext
148 lines
4.4 KiB
Plaintext
============================================================================
|
|
How to use `abi-compliance-checker' to test FLTK ABI compatibility (Linux)
|
|
============================================================================
|
|
|
|
This howto uses directories in /git/ as example directories. Please
|
|
adjust versions and directory names as appropriate on your system.
|
|
|
|
In this howto we compare FLTK 1.3.4-1 (last 1.3.x release as of Jan 02, 2019)
|
|
with the current version (1.3.5) before it will be released.
|
|
|
|
For documentation on its usage please refer to:
|
|
|
|
https://lvc.github.io/abi-compliance-checker/
|
|
|
|
|
|
(1) Download 'abi-compliance-checker' from GitHub:
|
|
|
|
$ cd /git
|
|
$ git clone https://github.com/lvc/abi-compliance-checker.git
|
|
|
|
Download directory: /git/abi-compliance-checker/
|
|
|
|
|
|
(2) Use two different Git checkout (working) directories to build libs,
|
|
for instance (as used in this example):
|
|
|
|
(new) /git/fltk-1.3 current version = 1.3.5
|
|
(old) /git/fltk-1.3.4-1 previous version = 1.3.4-1 [1]
|
|
|
|
[1] The second working directory can be created from the first
|
|
git working tree ( /git/fltk-1.3 ) with these commands:
|
|
|
|
$ cd /git/fltk-1.3
|
|
$ git worktree add /git/fltk-1.3.4-1 release-1.3.4-1
|
|
|
|
This creates the worktree in /git/fltk-1.3.4-1 and checks the
|
|
tag 'release-1.3.4-1' out.
|
|
|
|
|
|
(3) Create two xml descriptions to test library compatibility in
|
|
an arbitrary working directory (here: /git/workdir):
|
|
|
|
--- fltk-1.3.4-1.xml ---
|
|
<version>
|
|
1.3.4-1
|
|
</version>
|
|
|
|
<headers>
|
|
/git/fltk-1.3.4-1/FL/
|
|
</headers>
|
|
|
|
<skip_headers>
|
|
win32.H
|
|
mac.H
|
|
</skip_headers>
|
|
|
|
<libs>
|
|
/git/fltk-1.3.4-1/src/
|
|
/git/fltk-1.3.4-1/cairo/
|
|
</libs>
|
|
--- end of file ---
|
|
|
|
--- fltk-1.3.5.xml ---
|
|
<version>
|
|
1.3.5
|
|
</version>
|
|
|
|
<headers>
|
|
/git/fltk-1.3/FL/
|
|
</headers>
|
|
|
|
<skip_headers>
|
|
win32.H
|
|
mac.H
|
|
</skip_headers>
|
|
|
|
<libs>
|
|
/git/fltk-1.3/src/
|
|
/git/fltk-1.3/cairo/
|
|
</libs>
|
|
--- end of file ---
|
|
|
|
|
|
(4) Configure and build both libraries with the same options.
|
|
You *must* include '--enable-cairo' to build and compare the
|
|
Cairo libs and '--enable-shared' to build the shared libs:
|
|
|
|
$ make clean
|
|
$ ./configure --enable-cairo --enable-shared --enable-debug
|
|
$ make
|
|
|
|
Note: you must *not* use '--with-abiversion' because we need to
|
|
build the default ABI version.
|
|
|
|
|
|
(5) Run `abi-compliance-checker.pl':
|
|
|
|
$ cd /git/workdir
|
|
$ /git/abi-compliance-checker/abi-compliance-checker.pl \
|
|
-lib fltk -old fltk-1.3.4-1.xml -new fltk-1.3.5.xml
|
|
Preparing, please wait ...
|
|
Using GCC 7 (x86_64-linux-gnu, target: x86_64)
|
|
WARNING: May not work properly with GCC 4.8.[0-2], 6.* and higher
|
|
due to bug #78040 in GCC. Please try other GCC versions with the
|
|
help of --gcc-path=PATH option or create ABI dumps by ABI Dumper
|
|
tool instead to avoid using GCC. Test selected GCC version first
|
|
by -test option.
|
|
------------------------------------------------------------------
|
|
--> ignore warning (but run `abi-compliance-checker.pl -test')
|
|
------------------------------------------------------------------
|
|
Checking header(s) 1.3.4-1 ...
|
|
WARNING: can't find 'ctags' program
|
|
Checking header(s) 1.3.5 ...
|
|
WARNING: can't find 'ctags' program
|
|
------------------------------------------------------------------
|
|
--> ignore warning (or install 'ctags' and repeat)
|
|
------------------------------------------------------------------
|
|
Comparing ABIs ...
|
|
Comparing APIs ...
|
|
Creating compatibility report ...
|
|
Binary compatibility: 100%
|
|
Source compatibility: 100%
|
|
Total binary compatibility problems: 0, warnings: 0
|
|
Total source compatibility problems: 0, warnings: 1
|
|
Report: compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
|
|
|
|
|
|
(6) Check the generated report (last line above) with a browser:
|
|
|
|
$ firefox compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
|
|
|
|
|
|
(7) You may want to remove the additional worktree created above with:
|
|
|
|
$ cd /git/fltk-1.3
|
|
$ git worktree remove --force /git/fltk-1.3.4-1
|
|
|
|
|
|
(8) Done.
|
|
|
|
|
|
Note 1: The report as given above issued 100% ABI compatibility. The only
|
|
warning was the different patch version number.
|
|
|
|
Note 2: There are other recommended methods to use abi-compliance-checker
|
|
together with abi-dumper, but this is not (yet) covered here (see
|
|
abi-compliance-checker documentation).
|