#include directive — Includes another source file
#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