1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
============================================================================
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).
|
