C++ Include Paths: #include '...' vs <...>, -I, and CMake

C++ Include Paths: #include '...' vs <...>, -I, and CMake

· 20분 읽기 · 수정 초급 Tutorial
C++ Include Paths: #include '...' vs <...>, -I, and CMake

이 글의 핵심

How the compiler searches for headers: angle vs quotes, -I order, CMake target_include_directories, and fixing “No such file or directory” errors.

Introduction

Broken builds and wrong headers usually start with include search path configuration. This article explains "" vs <>, how to add -I paths per toolchain, and how to structure projects for clarity.

Include paths are the directories the preprocessor searches for headers.

1. What is an include path?

Basics

#include <iostream>   // system / toolchain paths
#include "myheader.h" // often project-relative first

Rough mental model:

  • <>: standard and system headers
  • "": project headers (still needs correct -I or relative path)

2. Search order (typical)

#include "file.h"

  1. Directory of the file containing the #include
  2. Paths from -I (in order)
  3. System paths

#include <file.h>

  1. -I paths (in order)
  2. System paths

(Exact rules depend on the compiler; treat this as a practical model.)

3. Examples

Basic usage

#include <iostream>
#include <vector>
#include <string>

#include "myclass.h"
#include "utils.h"

Compiler flags

g++ -I./include main.cpp
g++ -I./include -I./lib/include main.cpp
g++ -I../common/include main.cpp

Project layout

project/
├── include/
│   ├── myclass.h
│   └── utils.h
├── src/
│   ├── main.cpp
│   ├── myclass.cpp
│   └── utils.cpp
└── build/
g++ -I./include src/main.cpp src/myclass.cpp -o build/myapp

CMake

cmake_minimum_required(VERSION 3.10)
project(MyApp)

include_directories(${CMAKE_SOURCE_DIR}/include)

add_executable(myapp src/main.cpp src/myclass.cpp)

target_include_directories(myapp PRIVATE
    ${CMAKE_SOURCE_DIR}/include
)

4. Inspecting system paths (GCC/Clang)

g++ -v -E -x c++ /dev/null
# or
echo | g++ -Wp,-v -x c++ - -fsyntax-only

5. Common problems

Problem 1: header not found

fatal error: myheader.h: No such file or directory

Fix: g++ -I./include main.cpp (or correct relative path).

Problem 2: brittle absolute paths

Prefer -I./include or ${CMAKE_SOURCE_DIR}/include.

Problem 3: -I order matters

Earlier -I wins when multiple trees contain the same filename.

Problem 4: name clashes

Use subdirectories in includes (e.g. #include "lib1/utils.h") or namespaces.

6. Environment variables

export CPLUS_INCLUDE_PATH=/usr/local/include
g++ main.cpp

7. External library example

g++ -I./include -I./external/json src/main.cpp -o myapp

Summary

  1. "" vs <> — project vs system conventions
  2. -I adds search directories
  3. Order matters for shadowing
  4. CMake automates paths
  5. Verify with -v when debugging

Next: Header files, CMake, Compilation process.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. How the compiler searches for headers: angle vs quotes, -I order, CMake target_include_directories, and fixing “No such … 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

이 글에서 다루는 키워드 (관련 검색어)

C++, include, path, header, build 등으로 검색하시면 이 글이 도움이 됩니다.