В чём разница между target_include_directories() и include_directories()?

target_include_directories() vs include_directories()

В современном CMake (3.x+) рекомендуется использовать исключительно target_include_directories(). Команда include_directories() считается legacy и создаёт трудноотлаживаемые проблемы в больших проектах.

include_directories() — глобальный подход

# Применяется ко ВСЕМ целям в текущей и дочерних директориях
include_directories(${CMAKE_SOURCE_DIR}/include)
include_directories(/usr/local/mylib/include)

add_executable(app1 src/app1.cpp)
add_executable(app2 src/app2.cpp)
# Обе цели получат оба include-пути — даже если app2 это не нужно

target_include_directories() — целевой подход

add_library(math_lib STATIC src/math.cpp)

target_include_directories(math_lib
  PUBLIC   include/        # видно math_lib И всем, кто линкует math_lib
  PRIVATE  src/internal/   # видно только math_lib, не транзитивно
  INTERFACE proto/         # видно только потребителям, не самой цели
)

add_executable(my_app src/main.cpp)
target_link_libraries(my_app PRIVATE math_lib)
# my_app автоматически получает include/ из PUBLIC math_lib
# my_app НЕ получает src/internal/ (PRIVATE)

Разница в видимости: PRIVATE / PUBLIC / INTERFACE

# Библиотека с публичным API и приватными деталями реализации
add_library(network SHARED
  src/socket.cpp
  src/tls_impl.cpp
)

target_include_directories(network
  PUBLIC    include/network/   # заголовки API — видны потребителям
  PRIVATE   src/              # детали реализации — только для компиляции сети
)

# Заголовочная библиотека — только INTERFACE
add_library(json_fwd INTERFACE)
target_include_directories(json_fwd
  INTERFACE include/json_fwd/
)

Генераторные выражения для разных конфигураций

# Разные пути для in-source build и установленной версии
target_include_directories(mylib PUBLIC
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
  $<INSTALL_INTERFACE:include>
)
# При сборке — абсолютный путь к исходникам
# При install/export — относительный путь для потребителей

Диагностика: посмотреть effective include paths

# В CMakeLists.txt:
get_target_property(DIRS my_app INCLUDE_DIRECTORIES)
message(STATUS "Include dirs for my_app: ${DIRS}")

# Из командной строки:
cmake -B build
cmake --build build -- VERBOSE=1 2>&1 | grep " -I"

Почему include_directories() опасен

# Корневой CMakeLists.txt
include_directories(third_party/openssl/include)  # ГЛОБАЛЬНО!

add_subdirectory(app)
add_subdirectory(tests)   # тесты тоже получат OpenSSL include — неожиданно!
add_subdirectory(tools)   # и tools тоже

Подводные камни

• Смешивание include_directories() и target_include_directories() в одном проекте даёт непредсказуемый порядок поиска заголовков — одно и то же имя файла может разрешиться в разные пути.
• Свойство INCLUDE_DIRECTORIES цели и директории — разные вещи; get_target_property покажет только target-уровень без директорийных добавок.
• PUBLIC include-директории транзитивно передаются потребителям — если случайно пометить как PUBLIC системный путь (/usr/include), это замусорит все зависимые цели.
• При использовании INTERFACE-библиотек как proxy для include-путей, нельзя добавлять PRIVATE-директории — это вызовет ошибку CMake.
• Генераторные выражения BUILD_INTERFACE / INSTALL_INTERFACE обязательны для библиотек, которые устанавливаются и экспортируются; без них потребители получат несуществующие пути.
• В Visual Studio генераторе порядок include-директорий влияет на разрешение конфликтов имён — проверяйте свойство VS_INCLUDE_DIRECTORIES в IDE.

• Объяснять target_include_directories против include_directories только по синтаксису, без жизненного цикла и стоимости.
• Игнорировать ошибки, null/empty состояния, порядок инициализации или режим сборки.
• Давать пример, который работает в демо, но ломается при изменении владельца ресурса.
• Трактовать CMake как shell-скрипт вместо описания графа таргетов.

• Кандидат формулирует точную модель для target_include_directories против include_directories, а не только определение.
• Пример компилируем, безопасен по lifetime и соответствует версии технологии.
• Названы trade-off, ограничения и диагностируемые симптомы ошибки.
• Разделяет configure/generate/build и использует target-based подход.