GCC头文件搜索顺序详解

在C/C++编程中，合理管理头文件的引入路径对于项目的组织至关重要。GCC编译器提供了灵活的机制来指定头文件的搜索路径，这主要通过#include "…"和#include <…>两种形式实现。本文将详细介绍这两种形式的区别以及如何使用-I参数优化头文件的搜索过程。

双引号形式（#include “…”）

当使用双引号形式引入头文件时，如#include “log.h”，GCC首先会在当前源文件所在的目录下查找对应的头文件。如果未能找到，则会转向由-I参数指定的额外搜索路径进行查找。若依然未找到，最终才会在默认的头文件搜索路径中尝试定位该头文件。

尖括号形式（#include <…>）

相比之下，尖括号形式#include <…>则直接跳过当前源文件所在的目录，从默认的头文件搜索路径开始查找。这种方式通常用于引用标准库或第三方库中的头文件，确保快速定位到系统级别的库文件。

实际编译场景分析

假如我们有当前项目结构如下所示

/root/test/
├── src/
│   ├── dsl/
│   │   ├── context/
│   │   │   ├── context.cpp
│   │   │   ├── context.h
│   │   └── task/
│   │       ├── task.cpp
│   │       ├── task.h
│   ├── utils/
│   │   └── log/
│   │       ├── log.h
│   │       ├── log.cpp
├── main.cpp

示例代码

main.cpp

#include "log/log.h"
#include "dsl/context/context.h"
#include "dsl/task/task.h"

int main() {
    // 使用 log.h、context.h 和 task.h 中的功能
    return 0;
}

context.cpp 和 context.h

// context.h
#ifndef CONTEXT_H
#define CONTEXT_H

void context_function();

#endif

// context.cpp
#include "log/log.h"
#include "context.h"

void context_function() {
    // 使用 log.h 中的功能
    log_function("context");
}

task.cpp 和 task.h

// task.h
#ifndef TASK_H
#define TASK_H

void task_function();

#endif

// task.cpp
#include "log/log.h"
#include "context/context.h"
#include "task.h"

void task_function() {
    // 使用 log.h 和 context.h 中的功能
    context_function();  // 调用 context 模块的功能
    log_function("task");
}

log.h 和 log.cpp

// log.h
#ifndef LOG_H
#define LOG_H
#include <iostream>
#include <string>
void log_function(std::string msg);

#endif

// log.cpp
#include "log.h"

void log_function(std::string msg) {
    // 实现日志功能
    std::cout << msg << std::endl;
}

gcc直接编译

g++ main.cpp src/utils/log/log.cpp src/dsl/context.cpp src/dsl/task/task.cpp -o main

直接编译会报找不到头文件的错误，gcc在编译的时候会从当前cpp文件目录下查找.h的路径。例如对于main.cpp文件而言#include log/log.h，会从main.cpp的目录下找log/log.h文件，但是并没有这个文件，因为log.h在src/uitls/log/目录下，因此需要#include "src/uitls/log/log.h"，对于task.cpp而言，#include "dsl/context/context.h"也是找不到的，因为task.cpp目录下面并没有dsl/context/context.h文件，如果要使用相对路径则是#include ../context/context.h

当需要引用位于子目录下的头文件时，比如log/log.h，编译器会根据提供的相对路径从当前源文件目录开始查找。如果不同源文件位于不同的目录结构中，可能会导致查找失败。例如，如果task.cpp位于另一个目录下，直接使用#include "log/log.h"可能会因为找不到对应路径而报错。

// main
#include "src/utils/log/log.h"
#include "src/dsl/context/context.h"
#include "src/dsl/task/task.h"

// log
#include "log.h"

// context
#include "src/utils/log/log.h"
#include "context.h"

//task
#include "src/utils/log/log.h"
#include "src/dsl/context/context.h"
#include "task.h"

gcc统一使用-I参数

假设main.cpp文件需要包含一个名为log.h的头文件。此时，编译器首先会在main.cpp所在目录寻找log.h。如果该文件不存在于当前目录，且没有通过-I参数指定其他可能的位置，编译将会失败。

• 直接导入头文件"#include log.h"
  为了使上述情况成功编译，我们可以使用g++ -I./src/utils/log main.cpp log/log.cpp -o main命令。这样编译器会在./src/utils/log目录下查找log.h文件，从而解决找不到头文件的问题。

// main
#include "log.h" // -I./src/utils/log

// log
#include "log.h"

// context
#include "log.h" // -I./src/utils/log

//task
#include "log.h" // -I./src/utils/log

• 引入部分目录#include "context/context.h"
  为了使上述情况成功编译，我们可以使用g++ -I./src/utils/log -I./src/dsl main.cpp log/log.cpp -o main命令。这样编译器会在./src/utils/log和./src/dsl目录下查找头件，从而解决找不到头文件的问题。

// main
#include "log.h" // -I./src/utils/log
#include "context/context.h"

// log
#include "log.h"

// context
#include "log.h" // -I./src/utils/log
#include "context.h"

//task
#include "log.h" // -I./src/utils/log
#include "context/context.h" // -I.src/dsl
#include "task.h"

• 引入完整目录#include "src/dsl/task/task.h"
  为了使上述情况成功编译，我们可以使用g++ -I. -I./src/utils/log -I./src/dsl main.cpp xxx.cpp -o main命令。这样编译器会在./目录下头文件，从而解决找不到头文件的问题。

// main
#include "log.h" // -I./src/utils/log
#include "context/context.h"  // -I.src/dsl
#include "src/dsl/task/task.h"  // -I.

// log
#include "log.h"

// context
#include "log.h" // -I./src/utils/log
#include "context.h"

//task
#include "log.h" // -I./src/utils/log
#include "context/context.h" // -I.src/dsl
#include "task.h"

为了解决上述问题并保持代码的一致性，可以统一使用-I参数将项目根目录添加到头文件搜索路径中。例如，执行g++ -I. main.cpp xxx.cpp -o main命令，无论哪个源文件引入#include “src/utils/log/log.h”，编译器都会从./目录开始搜索log/log.h文件，从而避免了因文件位置差异导致的路径问题。

// main
#include "src/uitls/log/log.h" // -I.
#include "src/dsl/context/context.h"  // -I.
#include "src/dsl/task/task.h"  // -I.

// log
#include "log.h"

// context
#include "src/uitls/log/log.h" // -I.
#include "context.h"

//task
#include "src/uitls/log/log.h" // -I.
#include "src/dsl/context/context.h" // -I.
#include "task.h"

Cmake引入头文件

/root/test/
├── src/
│   ├── dsl/
│   │   ├── context/
│   │   │   ├── context.cpp
│   │   │   ├── context.h
│   │   │   ├── CMakeLists.txt
│   │   └── task/
│   │       ├── task.cpp
│   │       ├── task.h
│   │       ├── CMakeLists.txt
│   ├── utils/
│   │   └── log/
│   │       ├── log.h
│   │       ├── log.cpp
│   │       ├── CMakeLists.txt
├── main.cpp
├── CMakeLists.txt

根目录的 CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(MyProject)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)

# 添加主程序 main
add_executable(main main.cpp)

# 添加子模块
add_subdirectory(src/utils/log)
add_subdirectory(src/dsl/context)
add_subdirectory(src/dsl/task)

# 链接子模块到主程序
target_link_libraries(main PRIVATE log context task)

log 模块的 CMakeLists.txt

# 添加 log 库
add_library(log log.cpp)

# 添加头文件路径
# 相当于log库编译时增加参数-I./src/utils/log，直接可以使用log.h
target_include_directories(log PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

context 模块的 CMakeLists.txt

# 添加 context 可执行文件
add_library(context context.cpp)

# 添加头文件路径
# 相当于context库编译时增加参数-I./src/dsl/context，直接使用context.h
target_include_directories(context PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# 相当于log库编译时增加参数-I./src/utils，所以可以直接导入log/log.h
target_include_directories(context PRIVATE ${CMAKE_SOURCE_DIR}/utils)

# 链接到 log 模块
target_link_libraries(context PRIVATE log)

task 模块的 CMakeLists.txt

# 添加 task 可执行文件
add_library(task task.cpp)

# 添加头文件路径
# 相当于task库编译时增加参数-I./src/dsl/task
target_include_directories(task PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# 相当于task库编译时增加参数-I./src/utils，可以直接是使用log/log.h
target_include_directories(task PRIVATE ${CMAKE_SOURCE_DIR}/src/utils)

# 相当于task库编译时增加参数-I./src/dsl，可以直接是使用context/context.h
target_include_directories(task PRIVATE ${CMAKE_SOURCE_DIR}/src/dsl)

# 链接到 log 模块
target_link_libraries(task PRIVATE context log)

target_include_directories

gcc -I指定的头文件搜索路径作用在所有的文件上，而target_include_directories可以精细的控制每个库的头文件搜索路径，如果设置PRIVATE则是只有这个模块增加-I./xxx/yyy参数，如果是PUBLIC，则link了这个模块的模块或库都相当于增加了-I./xxx/yyy参数，头文件路径相当于传递下去了。举个例子

# 添加 log 库
add_library(log log.cpp)

# 添加头文件路径
# 相当于log库编译时增加参数-I./src/utils/log，直接可以使用log.h
target_include_directories(log PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# 相当于log库编译时增加参数-I./src/utils，直接可以使用log/log.h
target_include_directories(log PUBLIC ${CMAKE_SOURCE_DIR}/utils)

${CMAKE_SOURCE_DIR}/utils目录使用的是PUBLIC，如果哪个库link了log库，则可以直接使用#include "log/log.h"，因为传递下去了，例如context模块引入了log库
context 模块的 CMakeLists.txt

# 添加 context 可执行文件
add_library(context context.cpp)

# 添加头文件路径
# 相当于context库编译时增加参数-I./src/dsl/context，直接使用context.h
target_include_directories(context PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# 由于log模块的搜索路径是PUBLIC，context链接了log库，直接继承了头文件的搜索路径，所以不需要再target_include_directories(context PRIVATE ${CMAKE_SOURCE_DIR}/utils)了

# 链接到 log 模块
target_link_libraries(context PRIVATE log)