Утилита командной строки idf.py среды разработки ESP-IDF предоставляет интерфейс верхнего уровня (front-end) для упрощения обслуживания сборок проекта, развертывания и отладки, и т. п. Скрипт idf.py использует несколько инструментов, например:
• CMake, которая конфигурирует проект для сборки. • Ninja, которая собирает проект. • esptool.py для прошивки target.
Руководство по быстрому старту [2] содержит общую информацию о том, как настроить idf.py для конфигурирования, сборки и прошивки проектов.
Важное замечание: утилита idf.py должна запускаться в директории проекта ESP-IDF, т. е. в каталоге, где находится файл CMakeLists.txt верхнего уровня. Проекты более старого стиля, управляемые Makefile, не работают с утилитой idf.py. На операционной системе Windows перед запуском команд idf.py необходимо открыть приглашение командной строки, где уже настроены необходимые переменные окружения (ярлычок ESP-IDF 4.4 CMD). Основные команды idf.py следует запускать после перехода в корневой каталог проекта.
С основными терминами системы сборки, такими как проект, компонент и т. п. можно ознакомиться в документации [3].
Эта команда создаст новый компонент с минимальным набором файлов, необходимых для сборки.
idf.py create-component < имя_компонента>
Может использоваться опция -C, чтобы указать директорию, где будет создан компонент. Для дополнительной информации по компонентам см. раздел "Файлы CMakeLists компонента" в документации [3].
ESP-IDF поддерживает несколько разных target-ов ESP32 (чипов микроконтроллеров). Полный список поддерживаемых target-ов в вашей версии ESP-IDF можно узнать запуском команды idf.py --list-targets.
idf.py set-target < целевой_MCU>
Следующая команда установит target текущего проекта для чипа ESP32-C3:
idf.py set-target esp32c3
Команда idf.py set-target очистит директорию build, и перегенерирует файл sdkconfig заново. Старый sdkconfig будет сохранен как sdkconfig.old.
Поведение команды idf.py set-target эквивалентно следующему:
1. Очищается директория build (idf.py fullclean). 2. Переименовывается текущий файл sdkconfig (mv sdkconfig sdkconfig.old). 3. Конфигурируется проект на новый target (idf.py -DIDF_TARGET=esp32 reconfigure).
Также можно передать желаемый чип через переменную окружения IDF_TARGET (например export IDF_TARGET=esp32s2), или в качестве переменной CMake (например указанием аргумента -DIDF_TARGET=esp32s2 для CMake или idf.py). Установка переменной окружения удобный метод, если Вы часто работаете только с одним типом чипа.
Чтобы указать значение _default_ переменной IDF_TARGET для определенного проекта, добавьте значение CONFIG_IDF_TARGET в файл sdkconfig.defaults. Например, CONFIG_IDF_TARGET="esp32s2". Это значение будет использоваться, если IDF_TARGET не указана каким-либо другим методом: использованием переменной окружения, переменной CMake или командой idf.py set-target.
Если target не был установлен ни одним из этих методов, то система сборки примет esp32 как target по умолчанию.
Запуск этой команды приведет к компиляции проекта в текущей директории. Это может вовлекать несколько шагов:
• Будет создан подкаталог build, если это необходимо. В него будут сохраняться все результаты вывода компиляции. Имя этой папки можно поменять опцией -B. • Запустится CMake при необходимости для конфигурирования проекта и генерации файлов сборки, необходимых для основного инструментария сборки. • Запустится основной инструментарий сборки (Ninja или GNU Make). По умолчанию инструментарий сборки детектируется автоматически, но он может быть явно установлен передачей опции -G в скрипт idf.py.
Сборка инкрементальная, так что если с момента последней сборки не были изменены исходные файлы или конфигурация, то ничего сделано не будет.
Дополнительно команда может быть запущена с аргументами app, bootloader и partition-table, чтобы соответственно собрать приложение, загрузчик или таблицу разделов [4].
Содержимое результатов сборки (выходные файлы) в каталоге build могут быть удалены командой:
idf.py clean
После этого проект будет полностью пересобран после следующей команды сборки (idf.py build). Однако команда idf.py clean не будет очищать результаты вывода конфигурации CMake в папке build.
Запуск этой команды полностью удалит все содержимое подкаталога build. Это также включает вывод всех результатов конфигурирования CMake. При следующем запуске сборки проекта (idf.py build) утилита CMake выполнит конфигурирование заново. Обратите внимание, что команда fullclean рекурсивно удалит все файлы в каталоге build, так что если там есть что-то нужное для вас, то используйте fullclean с осторожностью. Конфигурация проекта (sdkconfig, sdkconfig.defaults) не будет удалена.
Эта команда автоматически при необходимости выполнит сборку проекта (idf.py build), и после этого прошьет результаты сборки в память flash чипа (target). Можно использовать опции -p и -b для установки имени последовательного порта и скорости передачи данных соответственно. Могут быть установлены переменные окружения ESPPORT и ESPBAUD для настройки значений по умолчанию опций -p и -b соответственно. Предоставление этих опций в командной строке переназначит значения по умолчанию.
Подобно команде сборки, команда idf.py flash может быть запущена с аргументами app, bootloader и partition-table, чтобы прошить только приложение, загрузчик или таблицу разделов.
[Важные замечания]
Несколько команд idf.py могут быть скомбинированы в одну. Например, idf.py -p COM4 clean flash monitor выполнит очистку (clean), затем соберет проект (build) и прошьет результаты сборки (flash) в target, и затем запустит монитор последовательного порта (monitor).
Порядок следования нескольких команд idf.py не имеет значения, они автоматически будут выполнены в нужном порядке (например, сборка будет всегда выполнена перед прошивкой, стирание перед прошивкой и т. д.).
Для команд, которые idf.py не знает, будет сделана попытка выполнить сборку системы для выбранной target.
Команда idf.py поддерживает автозаполнение (shell autocompletion) для оболочек команд bash, zsh и fish.
Чтобы поддерживалось автозаполнение, убедитесь, что у Вас установлен как минимумPython 3.5 и click 7.1, или более свежая версия.
Для разрешения автозаполнения команды idf.py для Linux и MacOS используйте настройку переменных окружения командой export [5]. Перебор вариантов автозаполнения инициируется клавишей TAB. Введите idf.py и нажимайте TAB для опций автозаполнения.
Поддержка автозаполнения для PowerShell планируется в будущем.
Следующая команда напечатает размер приложения, включая занятое пространство RAM и FLASH, и размер секции. Подобным образом будет напечатана такая же информация по каждому компоненту, используемому в проекте.
idf.py size
Напечатает информацию о размере для каждого исходного файла в проекте:
idf.py size-files
Если Вы определили переменную -DOUTPUT_JSON=1 то запуск CMake (или idf.py) будет выводить информацию как JSON, не как удобочитаемый текст.
Эта команда перезапустит CMake, даже если по идее это не надо делать (т. е. если конфигурация не была изменена). При нормальном процессе разработки необязательно использовать команду reconfigure, но это может быть полезным после добавления или удаления файлов из дерева исходников, или когда были изменены переменные кэша CMake. Например, idf.py -DNAME='VALUE' reconfigure может использоваться для установки переменной NAME кэша CMake в значение VALUE.
Следующая команда удалит байт-код, сгенерированный python из директории IDF:
idf.py python-clean
Байт-код может приводить к проблемам при переключении между версиями IDF и Python. Рекомендуется запустить эту цель после смены версии Python.
[Глобальные опции]
Для получения полного списка всех опций корневого уровня запустите команду idf.py --help. Для списка опций, которые специфичны для команды, запустите idf.py < команда> --help, например idf.py monitor --help. Вот список самых полезных опций:
-C < dir> позволяет переназначить директорию проекта из текущей рабочей директории по умолчанию.
-B < dir> позволяет переназначить директорию сборки из подкаталога проекта build, применяемого по умолчанию.
--ccache флаг, который может использоваться для разрешения CCache, когда компилируются исходные файлы, если установлен инструментарий CCache. Это кардинально снизит время сборки.
Имейте в виду, что некоторые старые версии CCache на некоторых платформах могут демонстрировать баги, так что если файлы не были собраны как положено, то попробуйте запретить CCache и снова выполнить сборку. CCache можно по умолчанию разрешить установкой в ненулевое значение переменной окружения IDF_CCACHE_ENABLE.
-v флаг, который приводит к подробному выводу лога действий по сборке как для idf.py, так и для системы сборки (verbose build output). This can be useful for debugging build problems.
--cmake-warn-uninitialized (или -w) приведет к тому, что CMake напечатает предупреждения по не инициализированным переменным, найденным только в директории проекта. Это только управляет предупреждениями переменных CMake внутри самой утилиты CMake, не по другим типам предупреждений сборки. Эту опцию можно установить постоянно путем установки переменной окружения IDF_CMAKE_WARN_UNINITIALIZED в ненулевое значение.
[Ссылки]
1. IDF Frontend idf.py site:docs.espressif.com. 2. Get Started site:docs.espressif.com. 3. ESP-IDF Build System. 4. ESP32: таблицы разделов. 5. Standard Toolchain Setup for Linux and macOS site:docs.espressif.com. 6. Ccache fast C/C++ compiler cache site:ccache.dev.
