What are the rules on #include "xxx.h" Vs #include ?

Question

If I have my own library projects, which style should I use to #include the headers from them in my application? Are there strict rules, and do the two actually have different meanings to the compiler/preprocessor or is it about standards only?

Answer 1

There are few rules, according to the ISO standard. Both forms are implementation-dependent as to where they look for the header files. They don't even have to be files.

Section 2.9 of C++11 makes no distinction between the two varieties other than the fact you can include " in the <> variant and > in the "" variant but few people would be silly enough to use those characters in file names :-)

Section 16.2 further states:

---

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.

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.

---

I tend to use <> for system headers and "" for my own headers, but that's personal preference only. I would note that the aforementioned C++11 document states:

Note: Although an implementation may provide a mechanism for making arbitrary source files available to the <> search, in general programmers should use the <> form for headers provided with the implementation, and the "" form for sources outside the control of the implementation.

This isn't mandated but it's a good idea nonetheless.

Answer 2

Usually, by using quotes you mean that header files are located in relative positions to your project's directory. If you use angle brackets, on the other hand, compiler would expect your header files locations to be standard locations. Such as /usr/include, /usr/local/include or any other default locations for your compiler.

In GCC if you use the -I flag, includes with angle bracket would be searched in the specified locations also.

Example:

$ gcc -Wall -I/path/to/my/library/include myfile.c

So if you have myfile.h in /path/to/my/library/include, you can use #include <myfile.h> in myfile.c source.

Answer 3

After having used dozens of compilers on several different operating systems, my advice is to use <x.h> only for system and operating-specific header includes, and "y.h" for everything else, including your libraries and project headers.

Then you set up the appropriate inclusion search paths using your compiler's -I (or whatever) option. This is easier if you use something like make or ant to do your builds.

For third-party software headers, you could go with either form. If the package is installed and accessible to all users (e.g., in somewhere like /usr/local/bin or /usr/site/bin), then the <x.h> form is probably more correct. If it's installed within your local build tree, then the "y.h" form is more correct, since it's controlled within your build process.

This combination is the most portable.

Answer 4

It affects where the preprocessor searches for the include file. From MSDN:

"Quoted form: This form instructs the preprocessor to look for include files in the same directory of the file that contains the #include statement, and then in the directories of any files that include (#include) that file. The preprocessor then searches along the path specified by the /I compiler option, then along paths specified by the INCLUDE environment variable.

Angle-bracket form: This form instructs the preprocessor to search for include files first along the path specified by the /I compiler option, then, when compiling from the command line, along the path specified by the INCLUDE environment variable."

As a rough guide, I only use quotes when I'm trying to specify a path relative to the directory containing the file with the #include in it. Otherwise, I just use angle brackets. As an example from my current project:

#include <algorithm> // standard library headers
#include <numeric>
#include <stack>

#include <boost/function.hpp> // third-party library headers
#include <boost/lexical_cast.hpp>

#include <common/io/util/LineIO.h> // specified relative to my own base include dir
#include "PartitionForest.h" // a header in the current directory