[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [RFC] Preprocessor flags to target code to a specific API version

From: Greg Stein <gstein_at_gmail.com>
Date: Sun, 26 Sep 2010 16:01:53 -0400

On Sat, Sep 25, 2010 at 21:07, Dani Church <dchurch_at_cheri.shyou.org> wrote:
>...
> You're certainly right, it is a big patch-- updating all of the
> SVN_DEPRECATED macros is around a 100KB patch.  I went through and updated
> them all based on the @deprecated tag version, and for the functions that
> were deprecated by a similarly-named one (like svn_client_info =>
> svn_client_info2) or that were related to a deprecated type (like
> svn_client_commit_item_create => svn_client_commit_item3_create) I also
> checked it against the version where the newer function or type was actually
> introduced, and updated the doc comment where there was a mismatch.  It's
> still possible that some functions got the wrong SVN_DEPRECATED tag, but
> that's hardly the end of the world; it just means that sometimes the
> compiler won't spit out the right deprecation warnings if you've set
> SVN_TARGET_API.
>
> I also looked into the other idea I mentioned, tuning the API to give errors
> when you use a function or a type that was introduced in a later API than
> the one you're targeting.  I used ctags and a whole bunch of text processing
> to determine which functions, types, defines, and members were introduced in
> which API version, and put
> #if SVN_TARGET_API >= x ... #endif blocks around all of them.  I can't say
> that the notation was absolutely perfect, but there is this: gcc will
> compile all of the headers without error using any SVN_TARGET_API from 0 to
> 7, and using 7 (or omitting it entirely) produces a set of preprocessed
> headers that are identical to the originals, so at the very least anyone not
> using API targeting won't be affected by the changes.  The patch for this is
> a lot bigger, about 500KB.
>
> I may have gone a bit overboard.
>
> Anyway, I have a couple patches here if anyone wants to look at them, but
> they're probably a bit large to attach to an email.  What should I do with
> them?

First off, if you could somehow extract the patch for fixing the
comments' @deprecated statements, that would be awesome. Fixing those
is a no-brainer and introduces no extra complexity.

Switching from USE_SVN_API to SVN_TARGET_API is good. I was going to
suggest a Proper SVN_ prefix, and woot! You did that already.

Wrapping declarations with #if SVN_TARGET_API is a non-starter, I
believe. That sounds like it would obfuscate the headers a bit too
much. In your original email, you mentioned something about "gcc
poison" which made it sound like you could flag certain declarations
to gcc as "bad to use". I just looked up that poison stuff, and I
don't see how we can magically work that into the SVN_DEPRECATED
macros that occur in each declaration (since you have to list the
function name in there). The closest that I could see would be
something like:

SVN_DEPRECATED_5
svn_error_t *
svn_wc_some_function(arguments,
    more argments);
SVN_MAYBE_POISON_5(svn_wc_some_function);

Where the latter macro expands to: _Pragma("GCC poison
svn_wc_some_function"); (I think that is the right syntax)

But again, that will add even more cruft around the declarations which
I'm not sure will be acceptable (gotta see what people think).

It is also possible to simply deprecate the "future" APIs rather than
declare them poisoned, although it means adding an SVN_DEPRECATED_? to
the true API. Or maybe we could add SVN_CURRENT (or somesuch) to the
current APIs, which become deprecated if you target an older API.

Cheers,
-g
Received on 2010-09-26 22:02:31 CEST

This is an archived mail posted to the Subversion Dev mailing list.