Are header file names such as bits/vector.tcc standard compliant?

Question

In my code base, I 'hide' implementation details of heavily templated code in .tcc files inside a bits sub-directory, i.e.

// file inc/foo.h:
#ifndef my_foo_h          // include guard
#define my_foo_h
namespace my {
  /* ... */               // templated code available for user
}
#include "bits/foo.tcc"   // includes implementation details
namespace my {
  /* ... */               // more templated code using details from foo.tcc
}
#endif

// file inc/bits/foo.tcc:
#ifndef my_foo_tcc        // include guard
#define my_foo_tcc
#ifndef my_foo_h
#  error foo.tcc must be #included from foo.h
#endif
namespace my { namespace details {
  /* ... */               // defails needed in foo.h
} }
#endif

Of course, there must only be one file bits/foo.tcc in the include path. Otherwise, there will be a clash and (hopefully) a compilation error. This just happened to me with bits/vector.tcc, which is included from gcc's (4.8) vector but also my own header (using #include "bits/vector.tcc" and not #include <bits/vector.h>).

My question: is this formally a bug of gcc (since it uses a name bits/vector.tcc which is not protected by the standard) or correct, i.e. even formally my fault? If the latter, what names for header files are guaranteed to be okay to use?

(note I don't want to hear obvious advices of how to avoid this).

---

Edit The problem is that the header file vector provided by the standard library (shipped by the compiler) has a preprocessor directive #include <bits/vector.tcc> which causes the preprocessor to load my file rather than that provided with the standard library.

Answer 1

Here's what the C++11 standard [cpp.include] has to say about this:

1 A #include directive shall identify a header or source file that can be processed by the implementation.

2 A preprocessing directive of the form

# include < h-char-sequence> new-line

searches a sequence of implementation-defined places for a header identified uniquely by the specified sequence between the < and > delimiters, and causes the replacement of that directive by the entire contents of the header. How the places are specified or the header identified is implementation-defined.

3 A preprocessing directive of the form

# include " q-char-sequence" new-line

causes the replacement of that directive by the entire contents of the source file identified by the specified sequence between the " delimiters. The named source file is searched for in an implementation-defined manner. If this search is not supported, or if the search fails, the directive is reprocessed as if it read

# include < h-char-sequence> new-line

with the identical contained sequence (including > characters, if any) from the original directive.

In other words, #include < > is intended for searching for headers only. A header is one of the things provided by the standard library. I say "things" because the standard doesn't specify what it is - it doesn't have to a file at all (although all compilers I know implement headers as files).

#include " " is intended for "everything else" - in terms of the standard, they're all "source files," although in general speech we usually refer to files intended for being #included as "header files." Also note that if no such source file is found, a (standard library) header will be searched for instead.

So, in your case:

• The standard doesn't say anything about files like bits/vector.tcc; in fact, it doesn't say anything about any files. All of this falls under the "implementation-defined" heading as is thus up to your compiler and its documentation.

  At the same time (thanks to @JamesKanze for pointing this out in the comments), the standard clearly specifies what #include <vector> should do, and never mentions that it could depend on a file's presence or absence. So in this regard, gcc loading your bits/vector.tcc instead of its own is a gcc bug. If gcc loaded its own bits/vector.tcc instead of yours, it would be within its "implementation-defined" scope.

• #include "vector" is primarily intended to include a source file named vector. However, if no such file is found, the effect is the same as including the standard header <vector> (which causes class template std::vector to be considered defined).

Answer 2

The standard is pretty open, but... including <vector> should work; I don't see anything that authorizes it not to (provided you've done #include <vector>, and not #include "vector"), regardless of the names your personal includes.

More generally, the more or less universal algorithm for searching for a header is to first search in the directory which contains the file which does the include. This is done precisely to avoid the type of problems you have encountered. Not doing this (or not using some other mechanism to ensure that includes from standard headers find the file they're supposed to) is an error in the compiler. A serious one, IMHO. (Of course, the compiler may document that certain options introduce certain restrictions, or that you need to use certain options for it to behave in a standard manner. I don't think that g++ documents -I as being incompatible with the standard headers, but it does say that if you use -iquote, it shouldn't influence anything included using <...>.)

EDIT:

The second paragraph above really only applies to the "..." form of the include. #include <vector> should find the standard header, even if you have a file vector in the same directory as the file you are compiling.

In the absense of -I options, this works. Universally, however, the -I option adds the directory in the search lists for both types of include. The reason for this is that you, as a developer, will probably want to treat various third party libraries (e.g. X-Windows) as if they were part of the system as well. (I think Linux does put X-Windows as part of the system, putting its headers in /usr/include, but this wasn't the usual case in other Unices in the past.) So you use -I to specify them, as well as you're other include directories. And if you have a file vector in one of your other directories, it will "override" the system one.

This is clearly a flaw: if I recall correctly (but it's been some time), g++ at one time did have additional options to put a directory in the list for only one type of include. And in modern gcc/g++, there's -iquote (and -I-, which specifies that all of the earlier -I options are for the "..." includes only). These features are little used, however, because gcc/g++ is the only compiler which supported them.

Given all this, the gcc/g++ handling is probably the best you can hope for. And the error isn't in the compiler itself, but the library headers, which use <bits/vector.tcc> when it absolutely wants the include file from the same directory as the file doing the including. (Another way of saying this is that bits/vector.tcc isn't a system header, in any sense of the word, but an implementation header of system library.)

None of which helps the original poster much, unless he feels like modifying the library headers for g++. (If portability isn't any issue, and he's not considering his headers as part of the system, he could change the -I to -iquote.)