[Rd] R Include File Guards

[Paul Roebuck]

On Fri, 17 Jun 2005, Prof Brian Ripley wrote:

> On Wed, 15 Jun 2005, Paul Roebuck wrote:
>
> > On Wed, 18 May 2005, Peter Dalgaard wrote:
> >
> >> Paul Roebuck <roebuck at odin.mdacc.tmc.edu> writes:
> >>
> >>> R 2.1.0/src/include from 2005/04/18 download
> >>>
> >>> Naming inconsistent for guards as well but that's pedantic.
> >>> Simple convention:
> >>>   file <foo.h>
> >>>     #ifndef R_FOO_H
> >>>   file <R_ext/bar.h>
> >>>     #ifndef R_EXT_BAR_H
> >>>
> >>> Missing guards:
> >>> <IOStuff.h>
> >>> <Internal.h>
> >>> <Parse.h>
> >>> <R_ext/GraphicsBase.h>
> >>> <R_ext/GraphicsDevice.h>
> >>> <R_ext/GraphicsEngine.h>
> >>> <R_ext/R-ftp-http.h>
> >>> <R_ext/libextern.h>
> >>>
> >>>
> >>> Illegal Guards (leading underscore):
> >>> <Rinternals.h>
> >>> <R_ext/Error.h>
> >>> <config.h.in>
> >>
> >> Thanks. The ones outside R_ext, except Rinternals.h, are not part of
> the
> >> API, so it is not a bug that there are no guards - could still be a
> >> good idea to have them of course. libextern.h explicitly says that you
> >> shouldn't disallow including it more than once. So the ones with real
> >> problems would be
> >>
> >> <R_ext/GraphicsBase.h>
> >> <R_ext/GraphicsDevice.h>
> >> <R_ext/GraphicsEngine.h>
> >> <R_ext/R-ftp-http.h>
> >>
> >> <Rinternals.h>
> >> <R_ext/Error.h>
> >>
> >> What's illegal about leading underscores, BTW?
> >>
> >
> > I downloaded the R-patched for 2005/06/14 and noticed that
> > the guards were never fixed. Should a bug report have been
> > opened instead of simply noting them here?
>
> What is the `bug' here which you suggest reporting?
>
> We have already established that leading underscores are NOT `illegal',
> just reserved and possibly ineffective according to the C99 standard
> (although we don't have any evidence of that being followed by an actual
> compiler). Given that the system includes on all three of my OSes use
> guards with leading underscores, they were VERY unlikely to be `illegal'
> as you stated.  (Looking in /usr/local/include shows that they are very
> widely used in other projects.)

Not sure when "we" established that. I was asked to provide
information about why it was illegal and I did so (per three OS
vendors) but nothing further was discussed. They are illegal exactly
because they are reserved for C compiler implementation vendors.
In essence, only implementation vendors are allowed to have header
files with leading underscores prepended to the guard names; thus
this is exactly the reason the system header files are done that way.
System headers use the leading underscore convention so the vendor is
free to add their own header files without causing problems for
existing user source. Here the situation is reversed as R has header
files that would cease to be included if a vendor added a header file
using the same guard.

As R Core is not a C compiler vendor, it is illegal usage.
Can one find other projects with include file guards with leading
underscores? Of course. Many people drive faster than the posted
speed limit - often without consequence.


<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndeepc/html/deep04202000.asp>
<http://www.cs.huji.ac.il/labs/parallel/Docs/C++/Guide/tic0056.html>
<http://www.belgeler.org/autobook/autobook-GNU-Autotools-in-Practice.html>


> Is there any known platform on which there is a consequential problem?
> If not (and we have no evidence), we do not play around with non-bugs in
> patch releases.

Fair enough.

> Some adjustments have been made in the development version of R.
> BTW: not all files in R_ext are part of the API: however
> GraphicsDevice.h and GraphicsEngine.h are and they are now
> compatible with C++ and have guards.

Thank you.



As an aside, has it ever been advanced that these files
not part of the API have a different naming scheme? Back
in the day, Motif had a convention where they appended
a capital P (for private, I assume) to the file's basename.

Public header:
	#include <foo.h>
Private to the implementation header:
	#include <fooP.h>

One could include the private heaers in code with the full
knowledge that the next release (of Motif) quite possibly
was going to break that code. :)

----------------------------------------------------------
SIGSIG -- signature too long (core dumped)