fltk/misc/abi-compliance-checker.txt

============================================================================
How to use `abi-compliance-checker' to test FLTK ABI compatibility on Linux
============================================================================

This howto explains how to execute the script 'misc/abi-check' to check
two FLTK releases of the same branch for ABI incompatibilities on Linux.
Other platforms may work as well, but then you will likely need to change
the script documented below or do the required steps manually.

The important point is that you build two different FLTK versions with
identical build options and *with* shared libraries.

For documentation on abi-compliance-checker please refer to:

    https://lvc.github.io/abi-compliance-checker/

You need `perl` and everything required to build FLTK installed on your
system before you continue.


(1) Download 'abi-compliance-checker' from GitHub:

    $ cd /path/to/dev
    $ git clone https://github.com/lvc/abi-compliance-checker.git

    Record the path '/path/to/dev/abi-compliance-checker' for later. You
    may add it to your PATH, or you may "install" abi-compliance-checker
    on your system. The latter is untested and not covered by this document.


(2) There are chances that you can use the script 'misc/abi-check' directly
    from the FLTK checkout (branch `master`). There are some variables in
    the script that may need to be edited though. Please check the docs in
    the script for these variables, particularly some paths and the CMake
    generator you use to build (default and recommended is "Ninja").

    If this doesn't work for you, please copy the script 'misc/abi-check'
    (new since FLTK 1.5) to a place of your choice (maybe in your PATH),
    and edit the variables for your build environment, as documented in
    the script. It is not recommended to edit it in place to avoid checking
    it into the repository or causing conflicts when pulling changes.

    You need to do this only once and can keep the edited version, but
    please check for updates in git (branch 'master') and update your file
    if there are relevant changes.


(3) Change your directory (cd) to an empty working directory (recommended)
    and execute the (maybe copied and edited) script 'abi-check' as
    documented at the top of that script.

    Example:

    $ /path/to/abi-check /path/to/fltk-1.4  1.4  2  3

    This would compare the binary versions of git tag 'release-1.4.2'
    with the tip of 'branch-1.4', assuming version number 1.4.3.

    The latter is required and is used to distinguish the different
    build folders and for the ABI compatibility report.

    Note: the working copy checked out at '/path/to/fltk-1.4' must be
    "clean", i.e. there must not be changed files. The script checks
    out the two requested versions and builds and installs them under
    the current working directory. The FLTK working copy is left with
    the tip of the branch (in this example `branch-1.4`) checked out.
    For FLTK 1.5 this would be `master`.

    If all goes well you'll see CMake configuration and build and install
    logs and the log of the ABI checker tool, ending with something like:

        ...
        Checking header(s) 1.4.2 ...
        WARNING: can't find 'ctags' program
        Checking header(s) 1.4.3 ...
        WARNING: can't find 'ctags' program
        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.4.2_to_1.4.3/compat_report.html

    You can safely ignore the "ctags" warnings if you don't have `ctags`
    installed.

    The script will try to open the above mentioned report automatically
    with the default browser (by using `xdg-open`) which may or may not
    work on your system. If it doesn't, please open the report manually
    with your browser.

    In the example above the only warning ("warnings: 1") is obviously
    caused by the changed FLTK patch version (1.4.2 -> 1.4.3) and can
    be ignored.

    If there are errors and other warnings, then the report should be
    checked thoroughly. Maybe there are ABI breaking changes that
    must be fixed by putting the according code under ABI guards as
    documented in 'README.abi-version.txt', or there may be one or more
    commits that must be reverted to prevent ABI breaking changes.


(4) You may want to remove the entire working directory for this ABI check
    when you're done with the checks.


Using this script from time to time is very convenient and can help to
find ABI issues early, i.e. before the branch is ready to be prepared
for the next release.

All FLTK devs and users are encouraged to do this and to report issues
as soon as possible.


Note: There are other recommended methods to use abi-compliance-checker
      together with `abi-dumper` but this is not covered by this document
      (see abi-compliance-checker documentation: link above).