[Bug-gnulib] Re: include-once-only macros

[Simon Josefsson]

Paul Eggert <address@hidden> writes:

> Simon Josefsson <address@hidden> writes:
>
>> I thought that POSIX (or C99?) implied user code shouldn't use CPP
>> symbols that began with '_'?
>
> C99 reserves all identifiers that begin with an underscore and either
> an uppercase letter or another underscore, for any use.  (Some other
> identifiers are also reserved, in some contexts.)

And POSIX doesn't further refine this?  (Honest question, I don't
know, but it seems POSIX sometime do things like that.)

> Personally I think of gnulib more as an "application", since it's
> intended to be dropped directly into application code.  So I prefer
> FOO_H to _FOO_H.  But I'm not dogmatic about it.

Given that my use of gnulib is for libraries, perhaps I should have
been arguing for the _FOO_H version, then.  O well, I guess it is
better to avoid changing existing style.

I sense an addition to the gnulib.texi coming up.  While writing it, I
added a similar discussion about __cplusplus #ifdef.  Please modify
and improve as appropriate, I just tried to summarize my view of
things.

Thanks,
Simon

--- gnulib.texi 24 Sep 2004 14:58:50 +0200      1.3
+++ gnulib.texi 28 Sep 2004 23:29:42 +0200      
@@ -98,6 +98,64 @@
 multiple copies will always remain identical.
 
 
address@hidden Header files
address@hidden Header files
+
address@hidden double inclusion of header files
address@hidden header file include protection
+It is a tradition to use CPP tricks to avoid parsing the same header
+file more than once, which might cause warnings.  The trick is to wrap
+the content of the header file (say, @file{foo.h}) in a block, as in:
+
address@hidden
+#ifndef FOO_H
+# define FOO_H
+...
+body of header file goes here
+...
+#endif /* FOO_H */
address@hidden example
+
+Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
+style.  The C99 standard reserve all identifiers that begin with an
+underscore and either an uppercase letter or another underscore, for
+any use.  Thus, in theory, an application might not safely assume that
address@hidden has not already been defined by a library.  On the other
+hand, using @code{FOO_H} will likely lead the higher risk of
+collisions with other symbols (e.g., @code{COFF_LONG_H} which is a CPP
+macro function).  Your preference may depeend on whether you consider
+the header file under discussion as part of the application (which has
+its own namespace for CPP symbols) or a supporting library (that
+shouldn't interfer with the application's CPP symbol namespace).
+
address@hidden C++ header files
address@hidden Header files and C++
+Adapting C header files for use in C++ applications can use another
+CPP trick, as in:
+
address@hidden
+# ifdef __cplusplus
+extern "C"
+{
+# endif
+...
+body of header file goes here
+...
+# ifdef __cplusplus
+}
+# endif
address@hidden example
+
+The idea here is that @code{__cplusplus} is only defined when C++ run
+the preprocessor.  It will wrap the header file in a @samp{extern "C"}
+block.  Again, whether to use this trick is a matter of taste and
+style.  While the above can be seen as harmless, it could be argued
+that the header file is written in C, and any C++ application using it
+should explicitly use the @samp{extern "C"} block itself.  Your
+preference might depend on whether you consider the API exported by
+your header file as something available for only C programs, or for C
+and C++ programs alike.
+
 @node ctime
 @section ctime
 @findex ctime