diff options
| -rw-r--r-- | misc/abi-compliance-checker.txt | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/misc/abi-compliance-checker.txt b/misc/abi-compliance-checker.txt new file mode 100644 index 000000000..097daeedb --- /dev/null +++ b/misc/abi-compliance-checker.txt @@ -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). |