C++ Include Path | 인클루드 경로 가이드

들어가며

빌드가 깨지거나 잘못된 헤더가 끌려오는 문제는 대부분 인클루드 검색 경로 설정에서 시작됩니다. 이 글에서는 <>와 ""의 차이를 바탕으로, 툴체인별로 경로를 추가하는 방법과 읽기 쉬운 프로젝트 구조를 갖추는 데 필요한 기준을 정리합니다.

인클루드 경로는 헤더 파일을 찾는 디렉토리 목록입니다.

---

1. 인클루드 경로란?

기본 개념

#include <iostream>   // 시스템 경로 검색
#include "myheader.h" // 현재 디렉토리 → 시스템 경로

차이점:

• <>: 시스템 헤더 (표준 라이브러리)
• "": 사용자 헤더 (프로젝트 파일)

---

2. 검색 순서

#include “file.h”

1. 현재 디렉토리
2. -I 옵션 경로 (순서대로)
3. 시스템 경로

#include <file.h>

1. -I 옵션 경로 (순서대로)
2. 시스템 경로

---

3. 실전 예시

예시 1: 기본 사용

// main.cpp
#include <iostream>  // 시스템
#include <vector>
#include <string>

#include "myclass.h"  // 사용자
#include "utils.h"

int main() {
    std::cout << "Hello\n";
    return 0;
}

예시 2: 컴파일 옵션

# -I 옵션으로 경로 추가
g++ -I./include main.cpp

# 여러 경로
g++ -I./include -I./lib/include main.cpp

# 상대 경로
g++ -I../common/include main.cpp

# 절대 경로 (비권장)
g++ -I/usr/local/mylib/include main.cpp

예시 3: 디렉토리 구조

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

# 또는 각각 컴파일
g++ -I./include -c src/main.cpp -o build/main.o
g++ -I./include -c src/myclass.cpp -o build/myclass.o
g++ build/main.o build/myclass.o -o build/myapp

예시 4: CMake 설정

# CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(MyApp)

# 인클루드 경로 추가
include_directories(${CMAKE_SOURCE_DIR}/include)
include_directories(${CMAKE_SOURCE_DIR}/lib/include)

# 또는 target 별로
add_executable(myapp
    src/main.cpp
    src/myclass.cpp
)

target_include_directories(myapp PRIVATE
    ${CMAKE_SOURCE_DIR}/include
)

---

4. 시스템 경로 확인

GCC/Clang

# GCC 기본 경로 확인
g++ -v -E -x c++ /dev/null

# 또는
echo | g++ -Wp,-v -x c++ - -fsyntax-only

# Clang
clang++ -v -E -x c++ /dev/null

출력 예시:

#include <...> search starts here:
 /usr/include/c++/11
 /usr/include/x86_64-linux-gnu/c++/11
 /usr/local/include
 /usr/include

---

5. 자주 발생하는 문제

문제 1: 헤더 못 찾음

# 에러
main.cpp:1:10: fatal error: myheader.h: No such file or directory
    1 | #include "myheader.h"

# 해결
g++ -I./include main.cpp

문제 2: 잘못된 경로

# ❌ 절대 경로 (이식성 낮음)
g++ -I/home/user/project/include main.cpp

# ✅ 상대 경로
g++ -I./include main.cpp

# ✅ CMake 변수 사용
include_directories(${CMAKE_SOURCE_DIR}/include)

문제 3: 경로 순서

# 먼저 지정한 경로가 우선
g++ -I./include1 -I./include2 main.cpp

# include1/utils.h가 include2/utils.h보다 우선

문제 4: 이름 충돌

// 두 경로에 같은 이름 헤더
// include1/utils.h
// include2/utils.h

// ❌ 모호함
#include "utils.h"

// ✅ 명시적 경로
#include "include1/utils.h"

// ✅ 네임스페이스 사용
namespace lib1 { /* ... */ }
namespace lib2 { /* ... */ }

---

6. 환경 변수

설정 방법

# Linux/Mac
export C_INCLUDE_PATH=/usr/local/include
export CPLUS_INCLUDE_PATH=/usr/local/include

# Windows (PowerShell)
$env:CPLUS_INCLUDE_PATH="C:\libs\include"

# 사용
g++ main.cpp  # 자동으로 경로 추가

---

7. 실전 예제

예제: 라이브러리 사용

project/
├── external/
│   └── json/
│       └── json.hpp
├── include/
│   └── config.h
└── src/
    └── main.cpp

// main.cpp
#include <iostream>
#include "json.hpp"    // external/json/json.hpp
#include "config.h"    // include/config.h

int main() {
    nlohmann::json j = {{"name", "홍길동"}};
    std::cout << j.dump() << std::endl;
    return 0;
}

# 컴파일
g++ -I./include -I./external/json src/main.cpp -o myapp

CMake 버전

cmake_minimum_required(VERSION 3.10)
project(MyApp)

set(CMAKE_CXX_STANDARD 17)

include_directories(
    ${CMAKE_SOURCE_DIR}/include
    ${CMAKE_SOURCE_DIR}/external/json
)

add_executable(myapp src/main.cpp)

---

정리

핵심 요약

1. <> vs "": 시스템 vs 사용자 헤더
2. -I 옵션: 경로 추가
3. 검색 순서: 현재 → -I → 시스템
4. 상대 경로: 이식성 좋음
5. CMake: include_directories(), target_include_directories()

실전 팁

• 상대 경로 사용: 이식성 향상
• 명시적 경로: 이름 충돌 방지
• CMake 활용: 빌드 자동화
• 시스템 경로 확인: -v 옵션

다음 단계

• C++ Header Files
• C++ CMake
• C++ Compilation Process

---

관련 글

• C++ Header Files |
• C++ 헤더 가드 완벽 가이드 | #ifndef vs #pragma once 실전 비교
• C++ include 에러 |
• C++20 Modules 완벽 가이드 | 헤더 파일을 넘어서
• C++ path |