Proposed standard scheme for maintainers' debugging code

[neroden at twcny dot rr dot com (Nathanael Nerode)]

The following is my draft of a standard scheme for miscellaneous
debugging code (discussed in the thread beginning at 
http://gcc.gnu.org/ml/gcc/2003-06/msg00900.html and some other places).

It's written as a separate header file, but should perhaps be included
in system.h or something else which *everyone* includes (what, precisely?).

Comments?  Is this a reasonable, sensible way to go?

--

#include "system.h"
/* The macros in this file are intended to isolate miscellaneous code used
   by the maintainers to debug GCC; it replaces previous ad-hoc #ifdefs,
   #if 0, if (0), or other such methods.  It's designed to encourage such
   code to stay in the compiler source in a way that makes it easy for
   future maintainers to find and use.

   Here is an example of how to use it. ('...' represents omitted code.)
   This is simplistic enough that you probably would just use a debugger
   instead, but it shows the principle.

     DECLARE_DEBUG_FLAG(foo)
     ...
     int foo(int y)
     {
       int x;
       ...
       if (DEBUGGING(foo)) {
         printf("Foo was passed %d", y);
         printf("Value of x is %d", x);
       }
      ...
     } 

   Normally, DEBUGGING is defined to 0 and the other macros are defined
   to expand to nothing, so there is no overhead at all in in production
   releases of the compiler.

   For debugging, you must configure gcc with --enable-debug-checking.
   Then the boolean variable 'flag_debug_foo' becomes available; if it
   is 0, the appropriate debugging will be off; if it is 1, it will be on.

   Such flags are off by default, but can be turned on in gdb by the
   command 'set debug_flag_foo = 1'.

   If you want to turn a flag on by default (for debugging without using
   a debugger), temporarily replace
     DECLARE_DEBUG_FLAG(foo)
   with
     DECLARE_DEBUG_FLAG_TRUE(foo)
   but please remember to turn it off before committing, so you don't
   interfere with other maintainers debugging other parts of the compiler.

   When you're working privately on a segment, of course, you can put
   the debugging code in unconditionally; but when the time comes to comment
   it out, please use this method.  :-)  Hopefully this is nearly as easy
   as using other methods. It's also intended to be structurally similar to
   other standard methods, so that it's easy to convert from your favorite
   method.
 */

#if ENABLE_CHECKING
  /* Don't change the names of the debug_flag_foo variables without warning;
     it's exposed to the maintainers via the debugger.  Otherwise, feel
     free to make the macros spiffier. */
  /* For recent GCC, we use __builtin_expect to predict that the
     debugging code won't be called; the hope is that this will
     reduce the cost of --enable-checking.  */
  #define DEBUGGING(x) __builtin_expect( debug_flag_ ## x , 0 )
  #define DECLARE_DEBUG_FLAG(x) bool debug_flag_ ## x;
  #define DECLARE_DEBUG_FLAG_TRUE(x) bool debug_flag_ ## x = true;
#else /* not ENABLE_CHECKING */
  /* Optimize all of these into non-existence. */
  #define DEBUGGING(x) 0
  #define DECLARE_DEBUG_FLAG(x)
  #define DECLARE_DEBUG_FLAG_TRUE(x)
#endif /* ENABLE_CHECKING */

-- 
Make sure your vote will count.
http://www.verifiedvoting.org/