ABI diff between old upstream (1.1.28) and latest libpaper (1.2.4)

[thesamesam]

Following on from #27, I ran abidiff (from libabigail) on 1.1.28 and 1.2.4 and got:

 *  SONAME:-libpaper.so.1(32)
 *    ABI: libpaper.so.1(64) func(+7,~1,-6) vars(+2) [BREAKING]
 * Functions changes summary: 6 Removed, 1 Changed (7 filtered out), 7 Added functions
 * Variables changes summary: 0 Removed, 0 Changed, 2 Added variables
 *
 * 6 Removed functions:
 *
 *   [D] 'function const char* defaultpapersizefile()'    {defaultpapersizefile}
 *   [D] 'function const paper* paperlast()'    {paperlast}
 *   [D] 'function const paper* paperprev(const paper*)'    {paperprev}
 *   [D] 'function int psdimension(const char*, int*)'    {psdimension}
 *   [D] 'function const char* systempapersizefile()'    {systempapersizefile}
 *   [D] 'function float unitfactor(const char*)'    {unitfactor}
 *
 * 7 Added functions:
 *
 *   [A] 'function double paperheight(const paper*)'    {paperheight}
 *   [A] 'function void papersetprefixdir(const char*)'    {papersetprefixdir}
 *   [A] 'function paper_unit paperunit(const paper*)'    {paperunit}
 *   [A] 'function double paperunitfactor(paper_unit)'    {paperunitfactor}
 *   [A] 'function paper_unit paperunitfromname(const char*)'    {paperunitfromname}
 *   [A] 'function const char* paperunitname(paper_unit)'    {paperunitname}
 *   [A] 'function double paperwidth(const paper*)'    {paperwidth}

Obviously the new functions aren't a problem, but the removed ones might be.

Notably, only one of them is in paper.h, so maybe we only have to worry about that one?

$ grep -E -rsin "(defaultpapersizefile|paperlast|paperprev|psdimension|systempapersizefile|unitfactor)" /usr/include/paper.h
149:double paperunitfactor(enum paper_unit n);

What do you think?

(I'm very new to libpaper and its API and I agree some of these old functions are.. whacky.)

[rrthomas]

Thanks very much for looking into this.

I'm a bit baffled by your analysis: on my Ubuntu system, /usr/include/paper.h (from libpaper 1.1.28) contains:

struct paper;

extern int paperinit __PAPER_PROTO((void));
extern int paperdone __PAPER_PROTO((void));

extern __PAPER_CONST char* papername __PAPER_PROTO((const struct paper*));
extern double paperpswidth __PAPER_PROTO((const struct paper*));
extern double paperpsheight __PAPER_PROTO((const struct paper*));

extern __PAPER_CONST char* defaultpapersizefile __PAPER_PROTO((void));
extern __PAPER_CONST char* systempapersizefile __PAPER_PROTO((void));
extern __PAPER_CONST char* defaultpapername __PAPER_PROTO((void));
extern char* systempapername __PAPER_PROTO((void));
extern __PAPER_CONST struct paper* paperinfo __PAPER_PROTO((const char*));
extern __PAPER_CONST struct paper* paperwithsize __PAPER_PROTO((
    double pswidth, double psheight));

extern __PAPER_CONST struct paper* paperfirst __PAPER_PROTO((void));
extern __PAPER_CONST struct paper* paperlast __PAPER_PROTO((void));
extern __PAPER_CONST struct paper* papernext __PAPER_PROTO((
    const struct paper*));
extern __PAPER_CONST struct paper* paperprev __PAPER_PROTO((
    const struct paper*));

In the sources, paperunitfactor is in dimen.h, which is not installed.

[rrthomas]

So by my count, the APIs removed are:

• paperprev
• paperlast
• defaultpapersizefile
• systempapersizefile

The first two are not a big deal (there's no point being able to iterate over the paper sizes backwards), and the last two no longer make sense.

However, to respect semver, I should give the library a major version bump, I guess.

[thesamesam]

Thanks very much for looking into this.

No problem!

I'm a bit baffled by your analysis: on my Ubuntu system, /usr/include/paper.h (from libpaper 1.1.28) contains:

Maybe I was being confusing, sorry: my grep was showing the new libpaper (1.2.4)'s header, to see which we really needed to adjust for, and which were maybe intentionally missing (looking for cases like #27 where it was in header & but not exported).

So by my count, the APIs removed are:

* paperprev

* paperlast

* defaultpapersizefile

* systempapersizefile

The first two are not a big deal (there's no point being able to iterate over the paper sizes backwards), and the last two no longer make sense.

However, to respect semver, I should give the library a major version bump, I guess.

Agreed. Sounds good to me!

[rrthomas]

OK, I think I see the main source of confusion: you said that unitfactor was removed, but in fact it's not, since it's not present in the old paper.h. paperunitfactor is indeed added. Does that make sense?

[thesamesam]

There's a unitfactor in old libpaper, but not in the headers, so I think we can probably ignore it?

$ grep -rsin "unitfactor" /var/tmp/portage/app-text/libpaper-1.1.28/image/usr/include/

$ nm -D /var/tmp/portage/app-text/libpaper-1.1.28/image/usr/lib64/libpaper.so | grep unitf
0000000000001410 T unitfactor

And right, paperunitfactor is added which is fine.

So, there's only these two unaccounted for, but neither were in the old headers either, so we can ignore them:

 *   [D] 'function int psdimension(const char*, int*)'    {psdimension}
 *   [D] 'function float unitfactor(const char*)'    {unitfactor}

[rrthomas]

Thanks; I've released 2.0.0.