mirror of
https://github.com/fltk/fltk.git
synced 2026-02-06 00:01:57 +08:00
4d0c1a2a28
misc/abi-check: This new script can be used (on Linux) to check ABI compatibility between patch releases. It does everything required in one execution (after installing the prerequisites once). Documentation is included in the script. It may be modified for other platforms, or ABI checking can be done manually. README.abi-version.txt: add a chapter regarding ABI checks misc/abi-compliance-checker.txt: update documentation on how to run misc/abi-check. In previous versions (1.4) building was done using configure/make. Thus this file was almost completely rewritten. documentation/src/migration_1_4.dox: an unrelated but tiny correction.
120 lines
5.0 KiB
Plaintext
120 lines
5.0 KiB
Plaintext
============================================================================
|
|
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).
|