cvs commit: src/include string.h src/lib/libc/string Makefile.inc memchr.3 memrchr.c src/sys/sys param.h

[Andre Oppermann]

These symbol versioning discussion come up from time to time and
actually as a developer who is not often confronted with it I
have a hard time figuring out what exactly I'm supposed to do
here.

Hence my pretty-please request to the guru(s) in residence to
write up a section for the FreeBSD developers handbook explaining
the concept of symbol versioning, its concrete implementation
in FreeBSD and the rules we apply to versioning (including example
cases like this and some earlier ones that came up).

Thank you!

-- 
Andre

Daniel Eischen wrote:
> On Wed, 28 May 2008, David Schultz wrote:
> 
>> On Tue, May 27, 2008, Xin LI wrote:
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA1
>>>
>>> Maxim Sobolev wrote:
>>> | Xin LI wrote:
>>> |> delphij     2008-05-27 20:04:27 UTC
>>> |>
>>> |>   FreeBSD src repository
>>> |>
>>> |>   Modified files:        (Branch: RELENG_6)
>>> |>     include              string.h     lib/libc/string
>>> |> Makefile.inc memchr.3     sys/sys              param.h   Added
>>> |> files:           (Branch: RELENG_6)
>>> |>     lib/libc/string      memrchr.c   Log:
>>> |>   MFC: Add memrchr(3).
>>> |
>>> | I think this is not very good idea to MFC that into stable releases 
>>> 6.x
>>> | and 7.x. The reason is that configure scripts for some packages might
>>> | detect up this API and enable it. Which means that some binary-only
>>> | packages build for say 6.4 won't work on 6.3 and down. AFAIK, both
>>> | forward and backward compatibility is required (or at least desired?)
>>> | for stable branches.
>>> |
>>> | While it's "nice-to-have" feature, I see no pressing need to MFC this
>>> | interface.
>>>
>>> I don't think so, perhaps I am wrong, but do we really want absolutely
>>> no *new* features on -STABLE branches?
>>
>> ISTR that in prior discussions on symbol versioning, the consensus
>> was that there's nothing wrong with adding new APIs in -STABLE
>> branches, but of course apps that use the new features won't be
>> backwards-compatible.
> 
> There's nothing technically wrong with it in that it will work, but
> for minor features that provide low marginal utility, I'm not sure
> that it is warranted.  I would rather see the bar raised for new
> features added to -stable branches.  But I don't feel strongly
> enough one way or the other to request a backout.
> 
>> By the way, one catch is that once you MFC symbols in the FBSD_1.1
>> namespace, any new symbols in the same library need to go in
>> FBSD_1.2. We do guarantee that public namespaces do not change
>> across stable branches. This is important for API-checking tools
>> like appcert: even if you can't prevent problems like the one
>> described previously, at least you have some assurance as to which
>> versions of FreeBSD will run your app.
> 
> No, all new symbols in 8-current go into FBSD_1.1, not 1.2.  The
> only time we go to 1.2 is when 8.x branches to 9.0.  If for some
> reason memrchr() were to change its ABI, then we would go to 1.1.1
> in -current for the ABI change and any subsequent new symbols, and
> the MFC to 7.x would also be 1.1.1.
> 
> It is ok for a FBSD_1.1 in -current to be a superset of FBSD_1.1
> in a previous branch.  In fact you can't prevent them from being
> different unless you mandate that all new symbols get MFC'd to
> their respective namespaces in previous branches.
> 
> One side note - this commit does show the proper way to MFC a new
> symbol to a previous branch.  That doesn't mean that it should
> have been done, just that it was done properly :-)
>