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