Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Andy Wingo <wingo@pobox.com>]

Hi!

On Tue 29 Apr 2014 18:33, Doug Evans <xdje42@gmail.com> writes:

> On Sun, Apr 27, 2014 at 6:17 AM, Andy Wingo <wingo@pobox.com> wrote:
>>
>> [...]
>>   7) There is legacy code out there that uses e.g. SCM_SETCDR to set
>>      smob fields.  (This is terrible, but it exists:
>>      https://github.com/search?q=SCM_SETCDR+smob&ref=cmdform&type=Code
>>      for an example.)

(This SMOB case is egregious because the smob is being accessed with
pair macros -- using macros is fine of course.)

> While function declarations are markable as being internal/external in
> published headers (SCM_INTERNAL vs SCM_API), macros are not.
> IWBN to solve this problem for macros too.  If it's in a header and a
> user can get it to work, s/he may just use it - some macros are indeed
> usable, so how does one easily know while reading headers (users will
> do that a lot) which are legitimately usable and which are not?

One can guard macros in #ifdef BUILDING_LIBGUILE, and it's possible to
deprecate them as well by #defining them to invoke SCM_DEPRECATED
functions.  So in short, as a user, you would know if we wanted to
deprecate something, and anything that's there is fair game,
technically.

So that's the minimum API stability barrier.  The higher barrier is
appearing in the documentation.

> [P.S. I'm not sure if SCM_SETCDR is still intended to be usable, I
> wouldn't mind deprecating it, and only publishing the function
> versions.  I can imagine it being ubiquitous enough in existing code
> that that's not possible, even if one wanted to.  At any rate that's a
> separate discussion.  Its presence in the foreign object discussion
> just reminded me of macros in headers.]

This might be a good idea.  Of course deprecation churn is still
unpleasant, so it would have to be a case of actively getting in the way
of some other Guile hacking before SCM_SETCDR could be deprecated in
favor of the (inline) function versions.

Cheers,

Andy
-- 
http://wingolog.org/