ABI checker

[Greg Ercolano]

Been using this thing tonight to check ABI compatibility:
http://ispras.linuxbase.org/index.php/ABI_compliance_checker

*Perhaps something all our devs should consider when making large changes.*

It's easy to use (See "Usage"), and generates a nice HTML report
that is currently a single html file.

It's basically a perl script that you run two compare two lib versions
against each other for ABI breakage checks.

It checks the include files and the binary libs.
In the case of FLTK, you just point it at the ./FL and ./lib
of two FLTK versions, and the html report tells you if there's
any ABI issues.

Here's an example report I generated on linux comparing the 1.3.2 release
version to my offline development version of 1.3.x:
http://seriss.com/people/erco/fltk/tmp/1.3.2_to_1.3.x--compat_report.html

It shows problems with Fl_Tree because I'm in active dev on it;
I'm using this tool exactly for this purpose.

*All devs on 1.3.x might want to look at this report*,
not only to see what it looks like, but because it's catching things
that aren't my changes, and might be worth checking. (See yellow items)

[Albrecht Schlosser]

On 15.01.2014 13:19, Greg Ercolano wrote:
> Been using this thing tonight to check ABI compatibility:
> http://ispras.linuxbase.org/index.php/ABI_compliance_checker
>
> *Perhaps something all our devs should consider when making large changes.*

...

> Here's an example report I generated on linux comparing the 1.3.2 release
> version to my offline development version of 1.3.x:
> http://seriss.com/people/erco/fltk/tmp/1.3.2_to_1.3.x--compat_report.html
>
> It shows problems with Fl_Tree because I'm in active dev on it;
> I'm using this tool exactly for this purpose.
>
> *All devs on 1.3.x might want to look at this report*,
> not only to see what it looks like, but because it's catching things
> that aren't my changes, and might be worth checking. (See yellow items)

Interesting report, but I only took a quick glance at it. However, I
can't see how all these FL_BEEP_* constants would have been removed
(they are still in FL/fl_ask.H), and others I didn't check (yet).

How did you generate the report? Did you set the ABI version number to
enable ABI-breaking features? Then the report as-is would be worthless,
wouldn't it? OTOH, if you did NOT set the ABI version number, then some
of the errors/warnings might be worth to be checked - or they might be
false alarms...

Anyway, that would probably be a good tool to use. How difficult was it
to download/install it? Any prerequisites (except perl, as mentioned
already)?

... Oh, I just looked at the link above and saw that the download is
from github ;-)

[Greg Ercolano]

On 01/15/14 04:49, Albrecht Schlosser wrote:
> Interesting report, but I only took a quick glance at it. However, I
> can't see how all these FL_BEEP_* constants would have been removed
> (they are still in FL/fl_ask.H), and others I didn't check (yet).

> How did you generate the report? Did you set the ABI version number to
> enable ABI-breaking features? Then the report as-is would be worthless,
> wouldn't it? OTOH, if you did NOT set the ABI version number, then some
> of the errors/warnings might be worth to be checked - or they might be
> false alarms...

FLTK_ABI_VERSION commented out.. there'd be volumes if it was on.

The BEEP stuff could be false alarms, they're considered warnings
and not an issue with compatibility. I didn't investigate them,
not sure what it's about.

The Fl_Tree ones are correct though.

> Anyway, that would probably be a good tool to use. How difficult was it
> to download/install it? Any prerequisites (except perl, as mentioned
> already)?

Ha, well I did mention it was easy.. ;)

You make two short xml files that just point to the include
and lib dirs, and one command that refers to the two xmls..
so in my case:

abi-compliance-checker -lib fltk -old 1.3.2.xml -new 1.3.x.xml

..and that's it. See 'Usage' and 'Compare Libraries' sections
at the link:
http://ispras.linuxbase.org/index.php/ABI_compliance_checker

I didn't try the other variations such as creating & comparing
ABI dumps, portability checks, etc.

The link shows what the requirements are (see "System Requirements"),
For linux:

G++ (3.0-4.7, recommended 4.5 or newer)
GNU Binutils (readelf, c++filt, objdump)
Perl 5 (5.8 or newer)
Ctags (5.8 or newer)

For Mac OS, just Xcode and Ctags.

For Windows there's a few things, including MinGW and VS.
Their recommendation for ActiveState Perl is a good one;
it's the best perl for windows.. very good stuff.

[Greg Ercolano]

On 01/15/14 08:25, Greg Ercolano wrote:
> The BEEP stuff could be false alarms, they're considered warnings
> and not an issue with compatibility. I didn't investigate them,
> not sure what it's about.

If you click on the blue FL_BEEP_XXX items in the report,
it tells you in plain error messages what it thinks the issue is.

Clicking on e.g. FL_BEEP_DEFAULT, it says:

"""
The constant FL_BEEP_DEFAULT with value 0 has been removed.
The value of this constant may no longer be properly handled
by new-version library functions.
"""

It flags this as something that doesn't break ABI;
a non-fatal warning.

And in fact when I fixed my offline Fl_Tree issues,
it now says the FLTK ABI is 'compatible', even with the warnings
about FL_BEEP_*.

So in other words it doesn't think they're of concern.

The change it's flagging happened in r9748; a small change
to the way the enum was declared is what I think it's flagging:

BEFORE: enum {
AFTER: enum Fl_Beep {

The values of the constant seem consistent and unchanged.

So seems of no concern, and since the ABI verdict is 'compatible'
in spite of the warnings, sounds like the checker isn't worried
about these either.

[Greg Ercolano]

On 01/15/14 04:19, Greg Ercolano wrote:
> Been using this thing tonight to check ABI compatibility:
> http://ispras.linuxbase.org/index.php/ABI_compliance_checker

Here's some example reports I just generated on svn current
showing the difference between FLTK_ABI_VERSION being unset (default)
vs being set to 10303:

unset: http://seriss.com/people/erco/fltk/tmp/compat-report-svn-current--FLTK_ABI_VERSION--unset.html
10303: http://seriss.com/people/erco/fltk/tmp/compat-report-svn-current--FLTK_ABI_VERSION--10303.html

So 'unset' should show up as 100% compatible (which it does),
and '10303' should show up as incompatible (which it does, by quite a bit).

It did in fact catch an ABI issue I missed in my recent Fl_Tree mods
resulting in r10062 to solve it.

Gives me the warm and fuzzies knowing this tool has my back with the ABI,
as I've been giving our FLTK_ABI_VERSION macro a real workout with my recent
mods to Fl_Tree (with even more to come).

You really have to walk between the raindrops to improve things without
breaking ABI.

[Greg Ercolano]

On 1/15/14 04:49, Albrecht Schlosser wrote:

On 15.01.2014 13:19, Greg Ercolano wrote:

Been using this thing tonight to check ABI compatibility:
http://ispras.linuxbase.org/index.php/ABI_compliance_checker

*Perhaps something all our devs should consider when making large changes.*

    Following up on this old but important thread from 2015:
    that link seems dead, but the ABI/API checking tool lives on.

    Thought I'd follow up with what appear to be the current links:

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

http://seriss.com/people/erco/fltk/tmp/1.3.2_to_1.3.x--compat_report.html
It shows problems with Fl_Tree because I'm in active dev on it;
I'm using this tool exactly for this purpose.
*All devs on 1.3.x might want to look at this report*,
not only to see what it looks like, but because it's catching things
that aren't my changes, and might be worth checking. (See yellow items)

[..]

[Albrecht Schlosser]

On 6/14/24 14:35 Greg Ercolano wrote:
>
>     Following up on this old but important thread from 2015:
>     that link seems dead, but the ABI/API checking tool lives on.
>
>     Thought I'd follow up with what appear to be the current links:
>
> https://lvc.github.io/abi-compliance-checker/
> https://github.com/lvc/abi-compliance-checker/releases

Thanks for the update.

Such a link is already documented in our `misc` directory, i.e. in file
`misc/abi-compliance-checker.txt` together with instructions on how to
use it. I added the link to the docs right now.

I'm using `abi-compliance-checker` on every 'point' release before I'm
packaging it. The
next one to be released is 1.3.10.

1.4.0 doesn't need this check because this is an ABI breaking release
anyway, but 1.4.1 has to be checked again.

[Greg Ercolano]

On 6/17/24 01:29, 'Albrecht Schlosser' via fltk.coredev wrote:

Thanks for the update.

[..]

1.4.0 doesn't need this check because this is an ABI breaking release
anyway, but 1.4.1 has to be checked again.

    I could use it to check ABI breakage for the recent fltk.coredev suggestion
    in the message thread right next to this one (Subject: Fl_Table default row height and column widths)