Espressif ESP32-S2 Programming Manual page 1282

Chapter 4. API Guides
• There are matching commands idf.py app-flash, etc. to flash only that single part of the project to the
target.
• idf.py -p PORT erase-flash will use esptool.py to erase the target's entire flash chip.
• idf.py size prints some size information about the app. size-components and size-files are
similar commands which print more detailed per-component or per-source-file information, respectively. If
you define variable -DOUTPUT_JSON=1 when running CMake (or idf.py), the output will be formatted
as JSON not as human readable text. See idf.py-size for more information.
• idf.py reconfigure re-runs
during normal usage, but can be useful after adding/removing files from the source tree, or when modifying
CMake cache variables. For example, idf.py -DNAME='VALUE' reconfigure can be used to set
variable NAME in CMake cache to value VALUE.
• idf.py python-clean deletes generated Python byte code from the IDF directory which may cause
issues when switching between IDF and Python versions. It is advised to run this target after switching versions
of Python.
• idf.py docs will open direct link to documentation for project's chip target and version in browser. To
see all options use idf.py docs --help
The order of multiple idf.py commands on the same invocation is not important, they will automatically be exe-
cuted in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
idf.py options To list all available root level options, run idf.py --help. To list options that are specific for
a subcommand, run idf.py <command> --help, for example idf.py monitor --help. Here is a list
of some useful options:
• -C <dir> allows overriding the project directory from the default current working directory.
• -B <dir> allows overriding the build directory from the default build subdirectory of the project directory.
• --ccache flag can be used to enable
This can dramatically reduce some build times.
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected
then try disabling CCache and build again. CCache can be enabled by default by setting the IDF_CCACHE_ENABLE
environment variable to a non-zero value.
• -v flag causes both idf.py and the build system to produce verbose build output. This can be useful for
debugging build problems.
• --cmake-warn-uninitialized (or -w) will cause CMake to print uninitialized variable warnings in-
side the project directory (not for directories not found inside the project directory). This only controls CMake
variable warnings inside CMake itself, not other types of build warnings. This option can also be set perma-
nently by setting the IDF_CMAKE_WARN_UNINITIALIZED environment variable to a non-zero value.
Start a new project
Use the command idf.py create-project for starting a new project. Execute idf.py create-
project --help for more information.
Example:
idf.py create-project --path my_projects my_new_project
This example will create a new project called my_new_project directly into the directory my_projects.
Using CMake Directly
idf.py is a wrapper around
When idf.py does something, it prints each command that it runs for easy reference. For example, the idf.
py build command is the same as running these commands in a bash shell (or similar commands for Windows
Command Prompt):
Espressif Systems
CMake even if it doesn't seem to need re-running. This isn't necessary
CCache
CMake for convenience. However, you can also invoke CMake directly if you prefer.
Submit Document Feedback
when compiling source files, if the
1271
CCache tool is installed.
Release v4.4