Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A user include in C++ is a preprocessor directive that instructs the compiler to insert the contents of a specified local or user-defined header file into the current translation unit. It is distinguished by the use of double quotes (" ") rather than angle brackets (< >), which dictates the specific search path algorithm the preprocessor uses to locate the file. 
#include "filename.h"
#include "relative/path/to/filename.hpp"
During Translation Phase 4, the C++ preprocessor performs a textual substitution, replacing the #include directive with the entire raw text of the referenced file before passing the expanded code to the compiler. The defining characteristic of a user include is its search path resolution. According to the C++ standard, the search process for a double-quote include is strictly implementation-defined. If this implementation-defined search fails to locate the file, or if the compiler does not support it, the standard mandates that the preprocessor falls back to reprocessing the directive as if it were an angle-bracket include (#include <filename.h>). While the standard does not mandate a specific directory hierarchy, major compilers (such as GCC, Clang, and MSVC) typically implement the following search order:
  1. Local Directory Search: The preprocessor first searches for the file in the same directory as the source file that contains the #include directive.
  2. Include Path Search: If the file is not found locally, the preprocessor searches the directories explicitly provided to the compiler via command-line include flags (such as -I for GCC/Clang or /I for MSVC).
  3. System Fallback: If the file remains unresolved, the preprocessor executes the standard-mandated fallback, searching the standard system include directories.
If the preprocessor exhausts all search paths without locating the specified file, it yields a fatal compilation error. 
// Example of nested inclusion syntax
#ifndef MY_HEADER_H
#define MY_HEADER_H

#include "dependency.h" // Implementation-defined search, typically relative to my_header.h

struct MyStruct {
    int data;
};

#endif
Because user includes rely on textual substitution, they are subject to multiple-inclusion issues within a single translation unit. This necessitates the use of include guards (#ifndef / #define / #endif) or the #pragma once directive within the target header file to prevent redefinition errors during the compilation phase.
Master C++ with Deep Grasping Methodology!Learn More