Часто встречается ситуация, когда редактор в Visual Studio Code показывает красным подчеркиванием директивы #include. Также на некоторых функциях и макроопределениях не работает просмотр места их определения (Go to Definition, F12). Проблема решается путем добавления в настройки проекта дополнительных путей поиска заголовочных файлов.

Путь поиска подключаемых файлов можно настроить с помощью редактирования файлов settings.json и c_cpp_properties.json.

Примечание: настройки проекта хранятся в файлах формата JSON, находящихся в "скрытой" папке .vscode, так что файлы settings.json и c_cpp_properties.json вы найдете в этой папке проекта.

[Добавление путей поиска в settings.json]

Есть возможность напрямую редактировать эти настройки как текст, однако можно воспользоваться для этого встроенным инструментом через меню File -> Preferences -> Settings.

Для добавления пути поиска заголовочных файлов выполните следующие шаги:

1. Выберите пункт меню File -> Preferences -> Settings. Откроется мастер редактирования настроек.

2. В верхней части редактора настроек есть поле ввода для поиска настроек (Search settings). Введите в это поле includePath, список настроек сократится.

3. В разделе настроек C_Cpp > Default: Include Path кликните на кнопку Add Item, и введите новый путь для поиска подключаемых файлов. Можно вводить как относительные пути, так и абсолютные. Также для пути можно указывать путь относительно домашнего каталога ~.

[Добавление путей поиска в c_cpp_properties.json]

Переменная окружения IDF_PATH. На рабочей станции может быть несколько одновременно установленных тулчейнов ESP-IDF разных версий. Какая версия в настоящий момент активна для текущего shell, определяется запуском скрипта export.sh (для Linux) или export.bat (для Windows), что отражается содержимым переменной окружения IDF_PATH. Таким образом, можно использовать эту переменную окружения IDF_PATH для настройки путей поиска заголовочных файлов, если они находятся внутри каталогов тулчейна ESP-IDF. 

Альтернативно путь поиска заголовочных файлов В VS Code можно настроить через файл .vscode/c_cpp_properties.json. Плагин C/C++ умеет читать переменные окружения через специальный синтаксис: ${env:ИМЯ_ПЕРЕМЕННОЙ}.

Таким образом, если мы пропишем ${env:IDF_PATH} в путях, то VS Code сам подставит нужную директорию для поиска, и "красные линии" на директивах #include пропадут.

1. Откройте или создайте файл конфигурации. Для этого в корневой папке вашего проекта ESP-IDF найдите папку .vscode и внутри неё создайте (или откройте существующий) файл c_cpp_properties.json.

2. Вставьте в файл c_cpp_properties.json следующий код. Скопируйте эту конфигурацию в файл. Она автоматически подтянет путь к IDF и добавит все необходимые заголовочные файлы. Это просто пример, реальные каталоги в вашей системе могут несколько отличаться:

{
   "configurations": [
      {
         "name": "ESP-IDF",
         // Путь к компилятору (берется из IDF_PATH)
         "compilerPath": "${env:IDF_PATH}/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0
         /xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc",
         
         // ГЛАВНОЕ: здесь добавляем пути поиска заголовочных файлов
         "includePath": [
            // Рекурсивно подключаем все компоненты из IDF (используем переменную окружения)
            "${env:IDF_PATH}/components/**",
            // Подключаем папку components вашего проекта
            "${workspaceFolder}/components/**",
            // Все папки вашего проекта (на всякий случай)
            "${workspaceFolder}/**"
         ],
         
         // Файл, который подключается принудительно (нужен для sdkconfig)
         "forcedInclude": [
            "${workspaceFolder}/build/config/sdkconfig.h"
         ],
         
         // Дополнительные аргументы для IntelliSense
         "compilerArgs": [
            "-I${env:IDF_PATH}/components/freertos/include",
            "-I${env:IDF_PATH}/components/esp_event/include"
         ],
         
         "browse": {
            "limitSymbolsToIncludedHeaders": true,
            "databaseFilename": ""
         },
         "cStandard": "c11",
         "cppStandard": "c++17",
         "intelliSenseMode": "gcc-x64"
      }
   ],
   "version": 4
}

Что означают эти строчки?

${env:IDF_PATH} — самая важная часть. VS Code найдёт вашу переменную окружения IDF_PATH (например, C:/esp/esp-idf) и автоматически подставит её вместо этой надписи.
${workspaceFolder} — путь к папке вашего проекта, который открыт в VS Code.
components/** — звёздочки `**` означают, что VS Code будет искать заголовочные файлы во всех вложенных папках рекурсивно. Это критически важно для структуры ESP-IDF.

 Как проверить, что всё работает?

1. Перезапустите VS Code — иногда это нужно, чтобы изменения применились.

2. Откройте любой `.c` или `.h` файл, который использует заголовочные файлы ESP-IDF (например, #include "freertos/FreeRTOS.h").

3. Убедитесь, что:
   - Пропали красные волнистые линии под `#include`.
   - Работает автодополнение (Ctrl+Space).
   - Работает переход к определению (F12 или Ctrl+клик).

Если всё ещё есть ошибки (красные линии), тогда проверьте следующие моменты:

1. Переменная окружения точно задана? Откройте терминал в VS Code и выполните команду:

    - Windows (PowerShell): `echo $env:IDF_PATH`
    - Mac/Linux: `echo $IDF_PATH`

Если ничего не вывелось — значит, переменная не прописана. Нужно открыть консоль терминала, запустить в нем скрипт export.sh (или export.bat), перейти в корневой каталог проекта (командой cd) и VS Code (командой code .).

2. Путь к компилятору (`compilerPath`) устарел? В разных версиях ESP-IDF могут быть разные версии тулчейна (например, вместо `xtensa-esp32-elf` может быть `riscv32-esp-elf` для ESP32-C3). Уточните фактический путь к компилятору в папке $IDF_PATH/tools/.

3. Посмотрите диагностику: нажмите F1, введите `C/C++: Log Diagnostics` и нажмите Enter. В появившемся тексте найдите раздел `Includes`. Там будет список всех папок, которые VS Code реально использует для поиска. Убедитесь, что среди них есть пути, начинающиеся с вашего IDF_PATH.

Этот метод полностью автоматический и переносимый: если вы скопируете проект на другой компьютер, где прописан `IDF_PATH`, VS Code сам подхватит правильные пути.

[Ссылки]

1. VSCode FAQ.
2. Интерфейс командной строки Visual Studio Code.
3. VSCode: использование файла настроек c_cpp_properties.json.