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.įor commands that are not known to idf.py an attempt to execute them as a build system target will be made. Multiple idf.py commands can be combined into one. See IDF Monitor for more details about using the monitor. The -p option can be used to set the serial port name.
Idf.py monitor will display serial output from the target. The -p and -b options can be used to set serial port name and flasher baud rate, respectively. Idf.py flash will automatically build the project if necessary, and then flash it to the target. Note that this option recursively deletes all files in the build directory, so use with care. The next time the project is built, CMake will configure it from scratch. This includes all CMake configuration output. Idf.py fullclean will delete the entire “build” directory contents. Cleaning doesn’t delete CMake configuration output and some other files. 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. By default, the build tool is automatically detected but it can be explicitly set by passing the -G option to idf.py.īuilding is incremental so if no source files or configuration has changed since the last build, nothing will be done. Run the main build tool ( Ninja or GNU Make). Run CMake as necessary to configure the project and generate build files for the main build tool. The sub-directory build is used to hold build output, although this can be changed with the -B option. This can involve multiple steps:Ĭreate the build directory if needed. Idf.py build will build the project found in the current directory. Idf.py menuconfig runs the “menuconfig” tool to configure the project. Idf.py set-target sets the target (chip) for which the project is built. Here are a summary of the most useful ones: Type idf.py -help for a list of commands. Older style projects with a Makefile will not work with idf.py. Idf.py should be run in an ESP-IDF “project” directory, ie one containing a CMakeLists.txt file.
The getting started guide contains a brief introduction to how to set up idf.py to configure, build, and flash projects. It manages the following tools:ĬMake, which configures the project to be builtĪ command line build tool (either Ninja build or GNU Make) The idf.py command line tool provides a front-end for easily managing your project builds. The toolchain should be installed in the system command line PATH. The toolchain for compilation is not part of the project. This allows the IDF framework to be decoupled from your project. Instead it is standalone, and linked to the project via the IDF_PATH environment variable which holds the path of the esp-idf directory. At the moment, ESP-IDF supports esp32, esp32s2 and esp32c3 targets. “Target” is the hardware for which an application is built. Some are provided by ESP-IDF itself, others may be sourced from other places.
“components” are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. A single project will usually build two apps - a “project app” (the main executable, ie your custom firmware) and a “bootloader app” (the initial bootloader program which launches the project app). A single project contains exactly one project configuration.Īn “app” is an executable which is built by ESP-IDF. This configuration file is modified via idf.py menuconfig to customise the configuration of the project. “Project configuration” is held in a single file called sdkconfig in the root directory of the project. Using Prebuilt Libraries with ComponentsĪ “project” is a directory that contains all the files and configuration to build a single “app” (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.Using ESP-IDF components from external libraries.Using Third-Party CMake Projects with Components.Fully Overriding The Component Build Process.Requirements in the build system implementation.Overriding default build specifications.