Add abi-compliance-checker howto.
This is intentionally committed to the 'master' branch although it is currently only useful for FLTK 1.3.x ABI checks. In the future we will need it for FLTK 1.4.x or higher.
This commit is contained in:
Albrecht Schlosser
parent
e118532c72
commit
f28cead0f0
143
misc/abi-compliance-checker.txt
Normal file
143
misc/abi-compliance-checker.txt
Normal file
@ -0,0 +1,143 @@
|
||||
============================================================================
|
||||
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.
|
||||
|
||||
|
||||
(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).
|
||||
Loading…
Reference in New Issue
Block a user