#include <header>
#include "sourcefile"

The #include directive includes the contents of a standard header or source file. The first form searches for header and replaces the directive with the entire contents of the header. The second form searches for sourcefile and replaces the directive with the entire contents of the named source file.

The basic action of #include is to read the named file or header as though its entire contents appeared in the source file at the position of the #include directive. Typically, common declarations are placed in a separate file, such as decl.h, and #include "decl.h" is used in every source file that depends on those declarations.

If a source file contains the directive #include "filename", and the compiler cannot find the external file named filename, the compiler also tries the form #include <filename>. Most compilers implement these two forms of #include by searching in different folders or directories. For example, the quote form searches in the current directory or in the directory that contains the source file, and the angle-bracket form searches only in "system" directories. Such details are implementation-defined, and some compilers might introduce further distinctions between the two forms.

It is possible, for example, for a compiler to recognize only the standard headers in the <header> form and use built-in knowledge of the standard headers without referencing any external files. This hypothetical compiler might report an error for all other uses of the angle-bracket form and require all external file inclusions to use the quote form. Such a compiler would not be very popular, however, because common practice is to treat <header> and "header" as equivalent forms, except when applying the rules for locating the external file named header.

It is common practice to install third-party libraries in common directories and to configure compilers to look in these directories for <header> inclusions. For example, if you use Boost (described in Appendix B), you might use #include <any.hpp> to obtain the boost::any class template. Another common practice is to install such libraries in subdirectories. On a Unix system, for example, you might install Boost in the boost subdirectory of one of the standard system directories and use #include <boost/any.hpp>. You should be careful, however, because using system-specific filenames is not portable.

The only guarantee that the standard offers is that if filename consists of a sequence of letters and underscore characters followed by a period and a single letter or underscore, then the implementation must provide a unique mapping of filename to a source file (optionally ignoring case distinctions). The standard permits universal characters in filename, but you should avoid them when you need maximum portability because some compilers do not support universal characters.

The implementation defines how and where the preprocessor searches for header or filename, how filename maps to an external filename, whether filenames heed or ignore case distinctions, and whether different character sequences for filename represent distinct external files. For example, under Windows, "foo.h" and "FOO.H" are usually the same file, but under Unix, they are usually different files. If the filesystem supports links, such as Unix, two names such as "foo.h" and "bar.h" might name the same file; in other environments, you might be guaranteed that different filenames refer to distinct files.

The most common convention is that <header> refers only to standard headers and to vendor-supplied extensions to the standard. Compilers typically have a way for you to supply your own additional libraries and use the associated headers as <header> includes. The quoted form is used for all header files that are part of the application, and those are typically located in the same directory or folder as the application's source files. The most common filename convention is to end header names with .h (for header), although .hpp is also common. For example, suppose you wrote a class to represent an employee. Put the class definition in employee.h and the definitions of the members in employee.cpp. Any other file that needs to use the employee class can #include "employee.h" and use the class definition:

#include <set>
#include "employee.h"

class business_group {
private:
  std::set<employee> employees_;
  ...
};

You can use other preprocessor tokens in an #include directive, provided they expand to one of the two standard forms. Each header name or filename must be a single preprocessor token; you cannot combine tokens to form a name. To preserve portability, use macros only for the entire sequence of the #include argument:

#define HEADER "this.h"
#include HEADER

See Also

#if directive