Espressif ESP32-S2 User Manual

Chapter 4. API Guides
4.4.2 Using the Build System
idf.py
The idf.py command-line tool provides a front-end for easily managing your project builds. It manages the fol-
lowing tools:
• CMake, which configures the project to be built
• A command-line build tool (either Ninja build or GNU Make)
• esptool.py for flashing the target.
The getting started guide contains a brief introduction to how to set up idf.py to configure, build, and flash projects.
idf.py should be run in an ESP-IDF “project”directory, i.e. one containing a CMakeLists.txt file. Older
style projects with a Makefile will not work with idf.py.
Type idf.py --help for a list of commands. Here are a summary of the most useful ones:
• idf.py set-target <target> sets the target (chip) for which the project is built. See Selecting the
Target.
• idf.py menuconfig runs the “menuconfig”tool to configure the project.
• idf.py build will build the project found in the current directory. This can involve multiple steps:
– Create the build directory if needed. The sub-directory build is used to hold build output, although
this can be changed with the -B option.
– Run CMake as necessary to configure the project and generate build files for the main build tool.
– Run the main build tool (Ninja or GNU Make). By default, the build tool is automatically detected but it
can be explicitly set by passing the -G option to idf.py.
Building is incremental so if no source files or configuration has changed since the last build, nothing will be
done.
• idf.py clean will “clean”the project by deleting build output files from the build directory, forcing a
“full rebuild”the next time the project is built. Cleaning doesn’t delete CMake configuration output and some
other files.
• idf.py fullclean will delete the entire“build”directory contents. This includes all CMake configuration
output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively
deletes all files in the build directory, so use with care. Project configuration is not deleted.
• idf.py flash will automatically build the project if necessary, and then flash it to the target. The -p and
-b options can be used to set serial port name and flasher baud rate, respectively.
• idf.py monitor will display serial output from the target. The -p option can be used to set the serial port
name. Type Ctrl-] to exit the monitor. See IDF Monitor for more details about using the monitor.
Multiple idf.py commands can be combined into one. For example, idf.py -p COM4 clean flash
monitor will clean the source tree, then build the project and flash it to the target before running the serial monitor.
For commands that are not known to idf.py an attempt to execute them as a build system target will be made.
The command idf.py supports shell autocompletion for bash, zsh and fish shells.
In order to make shell autocompletion supported, please make sure you have at least Python 3.5 and click 7.1 or newer
(see also).
To enable autocompletion for idf.py use the export command (see this). Autocompletion is initiated by pressing
the TAB key. Type “idf.py -”and press the TAB key to autocomplete options.
The autocomplete support for PowerShell is planned in the future.
Note: The environment variables ESPPORT and ESPBAUD can be used to set default values for the -p and -b
options, respectively. Providing these options on the command line overrides the default.
Advanced Commands
• idf.py app, idf.py bootloader, idf.py partition-table can be used to build only the
app, bootloader, or partition table from the project as applicable.
Espressif Systems 1270
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English