C++ Reference ยท Preprocessor, Tools and Concepts
The #include directive
Reference for the C++ #include directive: angle brackets versus quotes, search paths, include order, __has_include, and why includes are textual copy-paste.
#include is a preprocessor directive that replaces itself with the entire contents of another file. It runs before the compiler sees any C++ at all, so it is pure text substitution: after preprocessing, your source file and everything it includes form one long translation unit. Headers are how you share declarations (types, function prototypes, templates) between source files.
There are two forms. #include <name> searches the compiler's system include directories and is used for the standard library and installed third-party libraries. #include "name" searches the directory of the including file first, then falls back to the same places as the angle form, and is the usual choice for your own project headers.
#include <vector> // standard library header #include "geometry.h" // a header from your own project
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
#include <header-name> #include "source-file-name" #include pp-tokens // macro-expanded to one of the two forms above #if __has_include(<header>) / __has_include("file")
| Form | Description |
|---|---|
<name> |
Searches the implementation's system directories and any added with -I. For standard headers, an implementation may also treat the name as a built-in. |
"name" |
Searches the including file's directory first (implementation-defined, but this is what GCC, Clang and MSVC do), then behaves like the angle form. |
| Macro form | If neither form matches, the tokens are macro-expanded and must then produce one of the two forms. Rarely useful. |
__has_include(x) |
Evaluates to 1 if the header can be included, else 0. Usable only in #if/#elif. |
Errors: if the file cannot be found, compilation stops with a "No such file or directory" error. Including a file that is part of a cycle is bounded by the compiler's include depth limit, so always guard headers.
Usage notes
- Order matters. A conventional order, from most to least specific: the header matching the
.cppfile first (to prove it is self-contained), then your project headers, then third-party headers, then standard headers. Within a group, sort alphabetically. - Include what you use. Do not rely on one header including another; that is an accident of the implementation and breaks on the next compiler version. Include
<cstdint>yourself when you usestd::uint32_t. - Never
#includea.cppfile to "share code"; it duplicates definitions and breaks the one-definition rule across files. Use a header and link the source file. - Headers hold declarations, plus things that must be visible at every use: templates,
inlineandconstexprfunctions, class definitions. Non-inline function and variable definitions in a header give "multiple definition" link errors. - Put no
using namespacein headers. It leaks into every file that includes yours. - Use C++ names for C headers:
<cstdio>,<cstring>,<cmath>put names instd::(and usually in the global namespace too). Prefer thestd::spelling. - Compile times: every include is re-read for every translation unit. Forward-declare types when a pointer or reference is enough, and include the full header only in the
.cppfile. - Modules (C++20) replace textual inclusion with
import, andimport <vector>;header units exist, but toolchain support is uneven; our runner does not support modules. - Where the compiler looks: add search directories with
-Idir.-isystem dirmarks them as system headers (warnings from them are hidden). - X-macros: an
.deffile included several times, each time after redefining a macro, is a legitimate textual trick for generating enum values and string tables.