deprecated symbol warnings

[Ken Raeburn]

Some time back, I wrote:
> It might be a bit annoying to do in the source, but what about 
> flagging deprecated symbols while still allowing their use, in the 
> non-"--disable-deprecated" case?
>
> E.g., declare a function SCM_LENGTH, which is declared in the header 
> file with a macro which under recent enough versions of GCC expands to 
> __attribute__((deprecated)) and
[blah blah blah] and kind of volunteered myself to implement it.

Well, I've got a rough version up and limping, that does both 
compile-time and link-time warnings:

% make depr
gcc -I/var/raeburn/guile/guile-afs/Install/include -g   -c -o depr.o 
depr.c
depr.c: In function `main':
depr.c:6: warning: `SCM_ICDR' is deprecated (declared at 
/var/raeburn/guile/guile-afs/Install/include/libguile/deprecated.h:54)
gcc -o depr depr.o -L/var/raeburn/guile/guile-afs/Install/lib -lguile
depr.o(.text+0x15): In function `main':
/var/raeburn/guile/guile-afs/test/depr.c:6: SCM_ICDR is deprecated, 
please don't use it
%

(No warning is printed at run time.)

The warnings can be disabled while building guile (only while building 
deprecated.c, I hope) so that -Werror doesn't kill the build.

In the header files, here's how it's taking shape, roughly:

#if defined(SCM_DISABLE_DEPRECATION_WARNINGS)
# define SCM_DECL_DEPRECATED /* empty */
#elif __GNUC__ >= 3
# define SCM_DECL_DEPRECATED __attribute__((deprecated))
#elif defined _WIN32
/* TBD: How many old versions of the compiler support this?
   Will older ones complain, or ignore it?  */
# define SCM_DECL_DEPRECATED __declspec(deprecated) /* UNTESTED */
#else
# define SCM_DECL_DEPRECATED /* empty, no compile-time warnings */
#endif


/* N.B.: Application code will sometimes test whether one of these
   macros is defined, to figure out if the version of Guile in use
   predates the creation of the macro.  So at deprecation time, we
   still want the macro to be visible.  ANSI C says "#define foo foo"
   is okay, but if we get complaints about it, try switching the
   non-macro name to "foo_" or "foo_deprecated" or something; make it
   a simple concatenation so that we can make the other macros
   continue to be simple.  */

/* From eval.h: Macros for handling ilocs.  These were deprecated in 
guile
 * 1.7.0 on 2004-04-22.  */
extern SCM_DECL_DEPRECATED scm_t_bits SCM_IFRINC;
extern SCM_DECL_DEPRECATED scm_t_bits SCM_ICDR;
#define SCM_IFRINC              SCM_IFRINC
#define SCM_ICDR                SCM_ICDR

extern SCM_DECL_DEPRECATED long SCM_IFRAME(SCM n);
#define SCM_IFRAME              SCM_IFRAME


and in the source files:

#undef SCM_IFRINC
SCM_DEPRECATED (SCM_IFRINC);
scm_t_bits SCM_IFRINC = (0x00000100L);
#undef SCM_ICDR
SCM_DEPRECATED (SCM_ICDR);
scm_t_bits SCM_ICDR = (0x00080000L);

#undef SCM_IFRAME
SCM_DEPRECATED (SCM_IFRAME);
long SCM_IFRAME(SCM n)
{
  return ((long)((SCM_ICDR-SCM_IFRINC)>>8)
          & (SCM_UNPACK (n) >> 8));
}


The link-time warnings are a bit messier.  So far, I'm working with a 
macro SCM_DEPRECATED(SYMBOLNAME) that gets used at the top level 
(outside of any functions), and on systems that support it -- that 
configure test isn't written yet, so basically it's x86-linux 
configurations -- it spits out a string into section 
.gnu.warning.SYMBOLNAME that the GNU linker will use if SYMBOLNAME is 
referenced.  It's a const char array with a synthesized name based on 
the symbol name, so if the symbol in question is a function, it'll be 
easy for the function to use that symbol in a call to 
scm_c_issue_deprecation_warning (though I don't know if I need to worry 
about i18n interactions there).  I'm actually working on a couple 
different forms, one which always causes the message to be available to 
the code, and one which only outputs the message if separate sections 
are supported; the latter would be for the case where the code doesn't 
explicitly use the message, and we'd be wasting space on a platform 
that doesn't support warning sections.

There's also another form of the macro which allows the message to be 
specified separately, so the programmer can be told which other 
functions should be used instead.

(I'm in the process of reworking some of these macros, so I don't have 
a good code sample right now.)

On Windows, actually, I'm told there are pragmas which can produce 
deprecation warnings for uses of macros, without having to mess around 
with turning them into variables.  But this scheme I'm using above 
ought to work on both GNU and Windows compilers, and is less messy than 
trying to handle each separately.  (Note that I haven't tested the 
Windows version yet.)

Comments, before I take this too much further?

Ken