GCC/G++ 編譯器添加頭文件目錄與庫文件目錄完整指南

前言

在 Linux/Unix 環境下使用 GCC/G++ 編譯 C/C++ 專案時，正確配置頭文件搜尋路徑與庫文件搜尋路徑是構建成功的關鍵。本文系統整理編譯選項與環境變量兩大配置方式。

一、頭文件目錄配置

方法 1：編譯選項 -I (推薦，專案級)

# 單個目錄
gcc -I/usr/local/include/myLib main.c

# 多個目錄
g++ -I../include -I../../common/include -I/opt/boost/include main.cpp

# Makefile 中
CFLAGS += -I$(PROJECT_ROOT)/include
CXXFLAGS += -I$(PROJECT_ROOT)/include

優點：顯式、可移植、構建腳本中易維護、不污染環境。

方法 2：環境變量 (系統級/用戶級)

注意：多路徑用冒號 : 分隔 (Windows 用分號 ;)。

二、庫文件目錄配置

方法 1：編譯選項 -L (推薦)

# 指定庫搜尋目錄
gcc -L/usr/local/lib -L../lib main.c

# 關鍵區別：
# -L 指定目錄
# -l 指定庫名稱 (去掉 lib 前綴和 .so/.a 後綴)
gcc -L/opt/mysql/lib -lmysqlclient main.c  # 鏈接 libmysqlclient.so

方法 2：環境變量 LIBRARY_PATH

export LIBRARY_PATH=/opt/mysql/lib:/opt/boost/lib:$LIBRARY_PATH

作用範圍：僅影響編譯時期鏈接器尋找庫文件，不影響運行時動態庫加載。

三、運行時動態庫搜尋路徑 (關鍵區別)

運行時配置三種方式優先級遞減：

1. rpath (推薦，嵌入可執行文件)

   
   gcc -Wl,-rpath,/opt/mysql/lib -L/opt/mysql/lib -lmysqlclient main.c
   # 或 CMake: set(CMAKE_INSTALL_RPATH "/opt/mysql/lib")
   

2. LD_LIBRARY_PATH (臨時測試用)

   
   export LD_LIBRARY_PATH=/opt/mysql/lib:$LD_LIBRARY_PATH
   ./myapp
   

3. /etc/ld.so.conf (系統級永久)

   
   echo "/opt/mysql/lib" >> /etc/ld.so.conf
   ldconfig  # 更新緩存
   

四、庫命名規則與 -l 參數對應關係

# 實際文件名          -l 參數
libm.so               -lm
libpthread.a          -lpthread
libmysqlclient.so     -lmysqlclient
libboost_system.a     -lboost_system

# 規則：去掉 "lib" 前綴 和 ".so/.a" 後綴

五、完整編譯實戰範例

# 專案結構
myProject/
├── include/          # 頭文件
├── lib/              # 庫文件
├── src/
│   └── main.cpp
└── build/

# 編譯命令
cd build
g++ -I../include \
    -L../lib \
    -Wl,-rpath,../lib \
    ../src/main.cpp \
    -lmybusiness -lmysqlclient -lpthread \
    -o myapp

# 執行
./myapp

六、常見錯誤與排查

七、CMake 現代化配置 (推薦)

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# 包含目錄
include_directories(${PROJECT_SOURCE_DIR}/include)

# 鏈接目錄
link_directories(${PROJECT_SOURCE_DIR}/lib)

# 目標
add_executable(myapp src/main.cpp)
target_link_libraries(myapp mybusiness mysqlclient pthread)

# 安裝時 rpath
set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")

八、總結

1. 編譯期：用 -I 配置頭文件，-L 配置庫目錄，-l 指定庫名
2. 運行期：優先用 -Wl,-rpath 嵌入路徑，避免環境變量依賴
3. 64位系統：注意庫可能在 /usr/lib64 或 /lib64
4. 構建系統：CMake/Meson 等構建工具可自動管理上述細節，手寫 Makefile 時需格外小心

掌握 GCC/G++ 的路徑配置機制，是 Linux 下 C/C++ 開發者的必備基本功。建議在專案中統一使用 CMake 等構建系統，將路徑配置聲明式化，避免手動維護編譯命令帶來的錯誤。