============================================================================
 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).
