[boost] Re: #include <boost/...> to #include "boost/..." transition?

From: Dan'l Miller (optikos_at_[hidden])
Date: 2002-07-21 10:22:48

> Subject: [boost] #include <boost/...> to #include "boost/..." transition?
> Date: Sat, 20 Jul 2002 09:30:51 -0400
> From: Beman Dawes <bdawes_at_[hidden]>
> To: boost_at_[hidden]
> 
> As has been discussed many times in the past, the C++ standard provides
> #include <...> for "headers" (which are only well-defined in the standard
> for the standard library), and #include "..." for "source files" (which
> includes the Boost header files).  See section 16.2.
> 
> For historical reasons relating to problem compilers, Boost code has always
> used <boost/...> instead of "boost/...", and thus relies on
> implementation-defined behavior (16.2/2).
> 
> The historical reasons no longer apply.  Should we being to transition
> Boost code to the more correct #include "boost/..." form?
> 
> My personal feeling is that, yes, we should begin a gradual transition. New
> code should begin to use the  #include "boost/..." form. Existing code
> should be modified over time, particularly when other changes are being
> made that will force recompilation anyhow.
> 
> Comments?
> 
> --Beman

  No, absolutely not.  Neither Boost nor any publically-distributed library should use #include "relativePath" to include files, whether they be "header" files, "source" files, "declaration" files, "definition"/"template noninline function-definition"/"inline function-definition" files, "package" files, or otherwise.  Doing so implies that the C++ code knows what the current working directory of the build environment is (or knows what some other implementation-defined #include-"relativePath"-search directory scheme is).  Even if the Boost Jamfiles know what the current working directory is and that the current working directory matches the directory housing the relative-paths to include, many people using Boost reject the Jamfile-based build environment, opting instead of various self-written styles of makefiles which conform to their local larger build environment's conventions.  Recursive makefiles sometimes do have a definition of current working directory which matches the directory at which the to-be-in
cluded relative-path is found.  Often nonrecursive makefiles do not change the working directory as the build progresses, but rather rely on absolute pathnames throughout a build as the current working directory remains, say, in the account's home directory or at some fixed directory in a ClearCase view.

  As stated in ISO/IEC 14882 section 16.2 [cpp.include], the *only* difference between #include "relativePath" and #include <relativePath> is that the former searches an implementation-defined set of directories (e.g., current working directory) before searching the directories implied by #include <relativePath> (e.g., sequence of -I command-line arguments on many compilers directories which in turn are searched before the default system directories [e.g., /usr/include on UNIX-family operating systems]).  All of the ensuing debate about the arcane reinterpretations of the definitions of "header" file versus "source" file is 100% misguided.

  The *only* reasons to use #include "relativePath" versus #include <relativePath> must be confined to this *only* difference.  Injecting anything other than current working directory (or different analogous #include-"relativePath" semantics from a nonUNIX-family operating system) into the conversation is 100% misguided.  To cause a compiler to search an ill-defined current working directory (i.e., ill-defined in one build environment versus another) wastes the compiler's time searching the wrong/current-working directory.

  No publically-distributed library's C++ code should make any implications/prescriptions or assumptions about the directory layout of that code.  Especially, no publically-distributed library's C++ code should make any implications/prescriptions or assumptions about how a set of makefiles/jamfiles in a build environment will treat such implementation-defined things as current working directory.

  Boost must not imaginatively fabricate a new interpretation of #include <relativePath> versus #include "relativePath".  Boost must not imaginatively fabricate a new redefinition of "header" files and "source" files.  Boost must obey the multidecade-old existing practices regarding #include <relativePath> versus #include "relativePath" semantics which I relay herein:  the difference (on UNIX-family and UNIX-influenced platforms) is whether the current working directory of the build environment is searched or not.  Using syntax which is founded upon that CWD difference is unacceptably out of bounds unless Boost is willing to dictate that only one particular style of build environment (e.g., only Boost's jamfiles which would need to enforce current-working-directory conventions) is to be used to build Boost.

  Beman, for these reasons I expect you to withdraw your request to switch from #include <relativePath> to #include "relativePath".

 Dan'l Miller