From ff18a96f7d4f4f65278ee50f9e9054906c946745 Mon Sep 17 00:00:00 2001 From: Marek Fiala Date: Wed, 11 Aug 2021 15:24:17 +0200 Subject: [PATCH] tools: replace _ with - in idf.py Closes https://github.com/espressif/esp-idf/issues/5126 --- .gitlab/ci/host-test.yml | 2 +- README.md | 4 +- README_CN.md | 6 +-- components/app_update/CMakeLists.txt | 6 ++- components/efuse/CMakeLists.txt | 12 +++-- components/efuse/esp32/esp_efuse_table.csv | 2 +- components/efuse/esp32c3/esp_efuse_table.csv | 2 +- components/efuse/esp32h2/esp_efuse_table.csv | 2 +- components/efuse/esp32s2/esp_efuse_table.csv | 2 +- components/efuse/esp32s3/esp_efuse_table.csv | 2 +- components/partition_table/CMakeLists.txt | 16 ++++--- docs/en/api-guides/build-system.rst | 46 +++++++++---------- docs/en/api-guides/partition-tables.rst | 12 ++--- docs/en/api-reference/storage/nvs_flash.rst | 4 +- docs/en/api-reference/system/efuse.rst | 12 ++--- docs/en/get-started-legacy/make-project.rst | 5 +- docs/zh_CN/api-guides/build-system.rst | 4 +- docs/zh_CN/api-guides/partition-tables.rst | 12 ++--- .../zh_CN/api-reference/storage/nvs_flash.rst | 4 +- .../zh_CN/get-started-legacy/make-project.rst | 2 - examples/security/flash_encryption/README.md | 2 +- examples/storage/nvs_rw_blob/README.md | 3 +- examples/storage/nvs_rw_value/README.md | 3 +- examples/storage/nvs_rw_value_cxx/README.md | 3 +- examples/storage/spiffs/README.md | 2 +- examples/storage/wear_levelling/README.md | 2 +- examples/system/efuse/README.md | 8 ++-- .../efuse/main/esp_efuse_custom_table.csv | 2 +- examples/system/ota/README.md | 2 +- tools/ci/test_build_system_cmake.sh | 12 ++++- tools/cmake/utilities.cmake | 13 ++++++ tools/idf.py | 4 +- tools/idf_py_actions/core_ext.py | 42 ++++++++++++++++- tools/idf_py_actions/debug_ext.py | 18 ++++++++ tools/idf_py_actions/serial_ext.py | 31 ++++++++++--- 35 files changed, 202 insertions(+), 102 deletions(-) diff --git a/.gitlab/ci/host-test.yml b/.gitlab/ci/host-test.yml index 82be5c54aa..9f31b9909a 100644 --- a/.gitlab/ci/host-test.yml +++ b/.gitlab/ci/host-test.yml @@ -208,7 +208,7 @@ test_idf_tools: script: - cd ${IDF_PATH}/components/efuse/ - ./efuse_table_gen.py -t "${IDF_TARGET}" ${IDF_PATH}/components/efuse/${IDF_TARGET}/esp_efuse_table.csv - - git diff --exit-code -- ${IDF_TARGET}/esp_efuse_table.c || { echo 'Differences found for ${IDF_TARGET} target. Please run make efuse_common_table or idf.py efuse_common_table and commit the changes.'; exit 1; } + - git diff --exit-code -- ${IDF_TARGET}/esp_efuse_table.c || { echo 'Differences found for ${IDF_TARGET} target. Please run make efuse_common_table or idf.py efuse-common-table and commit the changes.'; exit 1; } - cd ${IDF_PATH}/components/efuse/test_efuse_host - ./efuse_tests.py diff --git a/README.md b/README.md index 73b855e398..0332dd1cfc 100644 --- a/README.md +++ b/README.md @@ -103,9 +103,9 @@ After the initial flash, you may just want to build and flash just your app, not ## Erasing Flash -The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase_flash`. +The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase-flash`. -This can be combined with other targets, ie `idf.py -p PORT erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table. +This can be combined with other targets, ie `idf.py -p PORT erase-flash flash` will erase everything and then re-flash the new app, bootloader and partition table. # Resources diff --git a/README_CN.md b/README_CN.md index 123bea47ba..da0a00b116 100644 --- a/README_CN.md +++ b/README_CN.md @@ -56,7 +56,7 @@ ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodu * 在主机中安装入门指南中提到的构建所依赖的工具。 * 运行安装脚本来设置构建环境。可为 Windows shell 选择 `install.bat` 或 `install.ps1`，为 Unix shell 选择 `install.sh` 和 `install.fish`。 * 在使用 ESP-IDF 之前，需要在 shell 中运行导出脚本。Windows 下可运行 `export.bat`，Unix 下可运行 `source export.sh`。 - + ## 配置项目 * `idf.py set-target ` 可将项目的目标芯片设置为 ``。运行 `idf.py set-target`，不用带任何参数，可查看所有支持的目标芯片列表。 @@ -103,9 +103,9 @@ ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodu ## 擦除 Flash -`idf.py flash` 并不会擦除 flash 上所有的内容，但是有时候我们需要设备恢复到完全擦除的状态，尤其是分区表发生了变化或者 OTA 应用升级时。要擦除整块 flash 请运行 `idf.py erase_flash`。 +`idf.py flash` 并不会擦除 flash 上所有的内容，但是有时候我们需要设备恢复到完全擦除的状态，尤其是分区表发生了变化或者 OTA 应用升级时。要擦除整块 flash 请运行 `idf.py erase-flash`。 -这条命令还可以和其余命令整合在一起，`idf.py -p PORT erase_flash flash` 会擦除一切然后重新烧写新的应用程序、引导程序和分区表。 +这条命令还可以和其余命令整合在一起，`idf.py -p PORT erase-flash flash` 会擦除一切然后重新烧写新的应用程序、引导程序和分区表。 # 其它参考资源 diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt index 8dd328215c..4fad8a774c 100644 --- a/components/app_update/CMakeLists.txt +++ b/components/app_update/CMakeLists.txt @@ -55,7 +55,7 @@ if(NOT BOOTLOADER_BUILD) "--partition-table-offset;${PARTITION_TABLE_OFFSET}") idf_component_get_property(esptool_py_dir esptool_py COMPONENT_DIR) - add_custom_target(read_otadata DEPENDS "${PARTITION_CSV_PATH}" + add_custom_target(read-otadata DEPENDS "${PARTITION_CSV_PATH}" COMMAND ${CMAKE_COMMAND} -D IDF_PATH="${idf_path}" -D SERIAL_TOOL="${otatool_py}" @@ -65,8 +65,9 @@ if(NOT BOOTLOADER_BUILD) WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} USES_TERMINAL ) + add_deprecated_target_alias(read_otadata read-otadata) - add_custom_target(erase_otadata DEPENDS "${PARTITION_CSV_PATH}" + add_custom_target(erase-otadata DEPENDS "${PARTITION_CSV_PATH}" COMMAND ${CMAKE_COMMAND} -D IDF_PATH="${idf_path}" -D SERIAL_TOOL="${otatool_py}" @@ -76,6 +77,7 @@ if(NOT BOOTLOADER_BUILD) WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} USES_TERMINAL ) + add_deprecated_target_alias(erase_otadata erase-otadata) idf_component_get_property(main_args esptool_py FLASH_ARGS) idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS) diff --git a/components/efuse/CMakeLists.txt b/components/efuse/CMakeLists.txt index 196c5b5c56..fc4da1d4f2 100644 --- a/components/efuse/CMakeLists.txt +++ b/components/efuse/CMakeLists.txt @@ -39,9 +39,10 @@ idf_build_get_property(python PYTHON) # Make common files esp_efuse_table.c and include/esp_efuse_table.h files. set(EFUSE_COMMON_TABLE_CSV_PATH "${COMPONENT_DIR}/${target}/esp_efuse_table.csv") -add_custom_target(efuse_common_table COMMAND "${python}" +add_custom_target(efuse-common-table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py" ${EFUSE_COMMON_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG}) +add_deprecated_target_alias(efuse_common_table efuse-common-table) ################### # Make custom files project/main/esp_efuse_custom_table.c and project/main/include/esp_efuse_custom_table.h files. @@ -51,15 +52,18 @@ if(${CONFIG_EFUSE_CUSTOM_TABLE}) idf_build_get_property(project_dir PROJECT_DIR) get_filename_component(EFUSE_CUSTOM_TABLE_CSV_PATH "${CONFIG_EFUSE_CUSTOM_TABLE_FILENAME}" ABSOLUTE BASE_DIR "${project_dir}") - add_custom_target(efuse_custom_table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py" + add_custom_target(efuse-custom-table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py" ${EFUSE_COMMON_TABLE_CSV_PATH} ${EFUSE_CUSTOM_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG}) + add_deprecated_target_alias(efuse_custom_table efuse-custom-table) else() - add_custom_target(efuse_custom_table COMMAND) + add_custom_target(efuse-custom-table COMMAND) + add_deprecated_target_alias(efuse_custom_table efuse-custom-table) endif()#if(${CONFIG_EFUSE_CUSTOM_TABLE}) -add_custom_target(show_efuse_table COMMAND "${python}" +add_custom_target(show-efuse-table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py" ${EFUSE_COMMON_TABLE_CSV_PATH} ${EFUSE_CUSTOM_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG} "--info") +add_deprecated_target_alias(show_efuse_table show-efuse-table) ################### # Generates files for unit test. This command is run manually. diff --git a/components/efuse/esp32/esp_efuse_table.csv b/components/efuse/esp32/esp_efuse_table.csv index 42cee2eb76..1d8c585cc5 100644 --- a/components/efuse/esp32/esp_efuse_table.csv +++ b/components/efuse/esp32/esp_efuse_table.csv @@ -6,7 +6,7 @@ ########################################################################## # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128. # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/components/efuse/esp32c3/esp_efuse_table.csv b/components/efuse/esp32c3/esp_efuse_table.csv index a9939e912b..4474198d32 100644 --- a/components/efuse/esp32c3/esp_efuse_table.csv +++ b/components/efuse/esp32c3/esp_efuse_table.csv @@ -6,7 +6,7 @@ ########################################################################## # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128. # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/components/efuse/esp32h2/esp_efuse_table.csv b/components/efuse/esp32h2/esp_efuse_table.csv index 08467f0ec0..cab21a1830 100644 --- a/components/efuse/esp32h2/esp_efuse_table.csv +++ b/components/efuse/esp32h2/esp_efuse_table.csv @@ -6,7 +6,7 @@ ########################################################################## # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128. # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/components/efuse/esp32s2/esp_efuse_table.csv b/components/efuse/esp32s2/esp_efuse_table.csv index 9c26819915..37793ae139 100644 --- a/components/efuse/esp32s2/esp_efuse_table.csv +++ b/components/efuse/esp32s2/esp_efuse_table.csv @@ -6,7 +6,7 @@ ########################################################################## # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128. # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/components/efuse/esp32s3/esp_efuse_table.csv b/components/efuse/esp32s3/esp_efuse_table.csv index 40decc2f29..e33c55ac38 100644 --- a/components/efuse/esp32s3/esp_efuse_table.csv +++ b/components/efuse/esp32s3/esp_efuse_table.csv @@ -5,7 +5,7 @@ # | EFUSE_BLK10)| | | # ########################################################################## # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt index 252eab5faf..385d2a5d96 100644 --- a/components/partition_table/CMakeLists.txt +++ b/components/partition_table/CMakeLists.txt @@ -54,15 +54,16 @@ add_custom_target(partition_table_bin DEPENDS "${build_dir}/partition_table/${un "${build_dir}/partition_table/${final_partition_bin}") if(EXISTS ${partition_csv}) - add_custom_target(partition_table + add_custom_target(partition-table DEPENDS partition_table_bin ${partition_table_display} VERBATIM) + add_deprecated_target_alias(partition_table partition-table) else() # If the partition input CSV is not found, create a phony partition_table target that # fails the build. fail_at_build_time also touches CMakeCache.txt to cause a cmake run next time # (to pick up a new CSV if one exists, etc.) - fail_at_build_time(partition_table + fail_at_build_time(partition-table "Partition table CSV ${partition_csv} does not exist." "Either change partition table in menuconfig or create this input file.") endif() @@ -81,7 +82,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME) VERBATIM) else() string(REPLACE ";" " " espsecurepy "${ESPSECUREPY}") - add_custom_command(TARGET partition_table POST_BUILD + add_custom_command(TARGET partition-table POST_BUILD COMMAND ${CMAKE_COMMAND} -E echo "Partition table built but not signed. Sign partition data before flashing:" COMMAND ${CMAKE_COMMAND} -E echo @@ -89,7 +90,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME) VERBATIM) endif() elseif(CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME) - add_custom_command(TARGET partition_table POST_BUILD + add_custom_command(TARGET partition-table POST_BUILD COMMAND ${CMAKE_COMMAND} -E echo "Partition table built:" VERBATIM) endif() @@ -98,9 +99,10 @@ idf_component_get_property(main_args esptool_py FLASH_ARGS) idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS) if(CONFIG_APP_BUILD_GENERATE_BINARIES) - esptool_py_flash_target(partition_table-flash "${main_args}" "${sub_args}") - esptool_py_flash_target_image(partition_table-flash partition_table "${PARTITION_TABLE_OFFSET}" + esptool_py_flash_target(partition-table-flash "${main_args}" "${sub_args}") + esptool_py_flash_target_image(partition-table-flash partition-table "${PARTITION_TABLE_OFFSET}" "${build_dir}/partition_table/${final_partition_bin}") - esptool_py_flash_target_image(flash partition_table "${PARTITION_TABLE_OFFSET}" + esptool_py_flash_target_image(flash partition-table "${PARTITION_TABLE_OFFSET}" "${build_dir}/partition_table/${final_partition_bin}") + add_deprecated_target_alias(partition_table-flash partition-table-flash) endif() diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 03c0d5737f..6bacace9b0 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -87,7 +87,7 @@ The command ``idf.py`` supports `shell autocompletion `_ supported, please make sure you have at least Python 3.5 and `click `_ 7.1 or newer (:ref:`see also `). -To enable autocompletion for ``idf.py`` use the ``export`` command (:ref:`see this `). Autocompletion is initiated by pressing the TAB key. Type "idf.py -" and press the TAB key to autocomplete options. +To enable autocompletion for ``idf.py`` use the ``export`` command (:ref:`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. @@ -96,9 +96,9 @@ The autocomplete support for PowerShell is planned in the future. 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. +- ``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. - 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 -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 CMake_ even if it doesn't seem to need re-running. This isn't necessary 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. @@ -325,7 +325,7 @@ The build system provides special treatment to the ``main`` component. It is a c Overriding default build specifications --------------------------------------- -The build sets some global build specifications (compile flags, definitions, etc.) that gets used in compiling all sources from all components. +The build sets some global build specifications (compile flags, definitions, etc.) that gets used in compiling all sources from all components. .. highlight:: cmake @@ -414,7 +414,7 @@ The following component-specific variables are available for use inside componen - ``COMPONENT_DIR``: The component directory. Evaluates to the absolute path of the directory containing ``CMakeLists.txt``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable. - ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory. - ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component. -- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. +- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. The following variables are set at the project level, but available for use in component CMakeLists: @@ -1175,7 +1175,7 @@ where: - ``target_name``- name that can be used to reference the imported library, such as when linking to other targets - ``lib_path``- path to prebuilt library; may be an absolute or relative path to the component directory -Optional arguments ``REQUIRES`` and ``PRIV_REQUIRES`` specify dependency on other components. These have the same meaning as the arguments for ``idf_component_register``. +Optional arguments ``REQUIRES`` and ``PRIV_REQUIRES`` specify dependency on other components. These have the same meaning as the arguments for ``idf_component_register``. Take note that the prebuilt library must have been compiled for the same target as the consuming project. Configuration relevant to the prebuilt library must also match. If not paid attention to, these two factors may contribute to subtle bugs in the app. @@ -1196,12 +1196,12 @@ It is possible to do so by using the :ref:`build system APIs provided` *property* and store it idf_build_set_property(property val [APPEND]) -Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead. +Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead. .. code-block:: none idf_build_component(component_dir) Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. -All calls to this command must be performed before `idf_build_process`. +All calls to this command must be performed before `idf_build_process`. This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) .. code-block:: none - idf_build_process(target + idf_build_process(target [PROJECT_DIR project_dir] [PROJECT_VER project_ver] [PROJECT_NAME project_name] @@ -1256,7 +1256,7 @@ This command does not guarantee that the component will be processed during buil [COMPONENTS component1 component2 ...]) Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, dependency expansion and resolution. Among these functions, perhaps the most important from a user's perspective is the libraries creation by calling each component's ``idf_component_register``. This command creates the libraries for each component, which are accessible using aliases in the form idf::*component_name*. -These aliases can be used to link the components to the user's own targets, either libraries or executables. +These aliases can be used to link the components to the user's own targets, either libraries or executables. The call requires the target chip to be specified with *target* argument. Optional arguments for the call include: @@ -1266,7 +1266,7 @@ The call requires the target chip to be specified with *target* argument. Option - SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set - SDKCONFIG_DEFAULTS - list of files containing default config to use in the build (list must contain full paths); defaults to empty. For each value *filename* in the list, the config from file *filename.target*, if it exists, is also loaded. - BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR -- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. +- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. Other components are automatically added if they are required in the dependency chain, i.e. the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, so on and so forth. If not specified, all components known to the build system are processed. .. code-block:: none @@ -1333,7 +1333,7 @@ Retrieve a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead. +Set a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead. .. _cmake-component-register: @@ -1352,7 +1352,7 @@ Set a specified *component*'s :ref:`component property Enumeration Enumeration -> Processing Processing -> Finalization } -Initialization +Initialization ^^^^^^^^^^^^^^ This phase sets up necessary parameters for the build. @@ -1515,7 +1515,7 @@ This phase sets up necessary parameters for the build. - Set global build specifications i.e. compile options, compile definitions, include directories for all components in the build. - Add components in :idf:`components` to the build. - The initial part of the custom ``project()`` command performs the following steps: - - Set ``IDF_TARGET`` from environment variable or CMake cache and the corresponding ``CMAKE_TOOLCHAIN_FILE`` to be used. + - Set ``IDF_TARGET`` from environment variable or CMake cache and the corresponding ``CMAKE_TOOLCHAIN_FILE`` to be used. - Add components in ``EXTRA_COMPONENTS_DIRS`` to the build. - Prepare arguments for calling command ``idf_build_process()`` from variables such as ``COMPONENTS``/``EXCLUDE_COMPONENTS``, ``SDKCONFIG``, ``SDKCONFIG_DEFAULTS``. @@ -1539,8 +1539,8 @@ Processing Finalization ^^^^^^^^^^^^ - This phase is everything after ``idf_build_process()``. - + This phase is everything after ``idf_build_process()``. + - Create executable and link the component libraries to it. - Generate project metadata files such as project_description.json and display relevant information about the project built. diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index f0ec74944c..819d92434c 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -16,7 +16,7 @@ The simplest way to use the partition table is to open the project configuration * "Single factory app, no OTA" * "Factory app, two OTA definitions" -In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition_table` then it will print a summary of the partition table. +In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition-table` then it will print a summary of the partition table. Built-in Partition Tables ------------------------- @@ -155,7 +155,7 @@ Generating Binary Partition Table The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. -If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process. +If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition-table``, this conversion is done as part of the build process. To convert CSV to Binary manually:: @@ -165,7 +165,7 @@ To convert binary format back to CSV manually:: python gen_esp32part.py binary_partitions.bin input_partitions.csv -To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition_table`` are generated:: +To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition-table`` are generated:: python gen_esp32part.py binary_partitions.bin @@ -204,14 +204,14 @@ The binary format of the partition table contains an MD5 checksum computed based Flashing the partition table ---------------------------- -* ``idf.py partition_table-flash``: will flash the partition table with esptool.py. +* ``idf.py partition-table-flash``: will flash the partition table with esptool.py. * ``idf.py flash``: Will flash everything including the partition table. -A manual flashing command is also printed as part of ``idf.py partition_table`` output. +A manual flashing command is also printed as part of ``idf.py partition-table`` output. .. note:: - Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. + Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase-flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. Partition Tool (parttool.py) diff --git a/docs/en/api-reference/storage/nvs_flash.rst b/docs/en/api-reference/storage/nvs_flash.rst index 31ae316d8a..8ec01eee95 100644 --- a/docs/en/api-reference/storage/nvs_flash.rst +++ b/docs/en/api-reference/storage/nvs_flash.rst @@ -16,7 +16,7 @@ Currently, NVS uses a portion of main flash memory through the :ref:`esp_partiti Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc. -.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase_flash`` target to erase all contents of the flash chip. +.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase-flash`` target to erase all contents of the flash chip. .. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library. @@ -118,7 +118,7 @@ The XTS encryption keys in the :ref:`nvs_key_partition` can be generated in one i) Build and flash the partition table :: - idf.py partition_table partition_table-flash + idf.py partition-table partition-table-flash ii) Store the keys in the :ref:`nvs_key_partition` (on the flash) with the help of :component_file:`parttool.py` (see Partition Tool section in :doc:`partition-tables ` for more details) :: diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index d6340a1dd4..ec3e1e222f 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -52,8 +52,8 @@ The component has API functions for reading and writing fields. Access to the fi CSV files: -* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse_common_table``). Note that changes in this file can lead to incorrect operation. -* custom - (optional and can be enabled by :ref:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse_custom_table``. +* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse-common-table``). Note that changes in this file can lead to incorrect operation. +* custom - (optional and can be enabled by :ref:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse-custom-table``. Description CSV file @@ -136,7 +136,7 @@ efuse_table_gen.py tool The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional `custom` file is used, it will be checked with the existing `common` file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type `esp_efuse_desc_t`. -To generate a `common` files, use the following command ``idf.py efuse_common_table`` or: +To generate a `common` files, use the following command ``idf.py efuse-common-table`` or: .. code-block:: bash @@ -148,7 +148,7 @@ After generation in the folder $IDF_PATH/components/efuse/`{IDF_TARGET_PATH_NAME * `esp_efuse_table.c` file. * In `include` folder `esp_efuse_table.c` file. -To generate a `custom` files, use the following command ``idf.py efuse_custom_table`` or: +To generate a `custom` files, use the following command ``idf.py efuse-custom-table`` or: .. code-block:: bash @@ -274,7 +274,7 @@ For frequently used fields, special functions are made, like this :cpp:func:`esp How to add a new field ---------------------- -1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show_efuse_table`` or the next command: +1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show-efuse-table`` or the next command: .. code-block:: none @@ -358,7 +358,7 @@ Virtual eFuses The Kconfig option :ref:`CONFIG_EFUSE_VIRTUAL` will virtualize eFuse values inside the eFuse Manager, so writes are emulated and no eFuse values are permanently changed. This can be useful for debugging app and unit tests. During startup, the eFuses are copied to RAM. All eFuse operations (read and write) are performed with RAM instead of the real eFuse registers. -In addition to the :ref:`CONFIG_EFUSE_VIRTUAL` option there is :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` option that adds a feature to keep eFuses in flash memory. To use this mode the partition_table should have the `efuse` partition. partition.csv: ``"efuse_em, data, efuse, , 0x2000,"``. +In addition to the :ref:`CONFIG_EFUSE_VIRTUAL` option there is :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` option that adds a feature to keep eFuses in flash memory. To use this mode the partition_table should have the `efuse` partition. partition.csv: ``"efuse_em, data, efuse, , 0x2000,"``. During startup, the eFuses are copied from flash or, in case if flash is empty, from real eFuse to RAM and then update flash. This option allows keeping eFuses after reboots (possible to test secure_boot and flash_encryption features with this option). espefuse.py diff --git a/docs/en/get-started-legacy/make-project.rst b/docs/en/get-started-legacy/make-project.rst index 4a0e696806..683c8df81e 100644 --- a/docs/en/get-started-legacy/make-project.rst +++ b/docs/en/get-started-legacy/make-project.rst @@ -38,8 +38,8 @@ When ``make all`` finishes, it will print a command line to use esptool.py to fl make flash -This will flash the entire project (app, bootloader and partition table) to a new chip. Also if partition table has ota_data then this command will flash a initial ota_data. -It allows to run the newly loaded app from a factory partition (or the first OTA partition, if factory partition is not present). +This will flash the entire project (app, bootloader and partition table) to a new chip. Also if partition table has ota_data then this command will flash a initial ota_data. +It allows to run the newly loaded app from a factory partition (or the first OTA partition, if factory partition is not present). The settings for serial port flashing can be configured with `make menuconfig`. You don't need to run ``make all`` before running ``make flash``, ``make flash`` will automatically rebuild anything which needs it. @@ -75,4 +75,3 @@ The simplest way to use the partition table is to `make menuconfig` and choose o In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`. - diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 93a3da90d7..67c5111a3c 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -96,9 +96,9 @@ idf.py 高级命令 ^^^^^^^^ -- ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 +- ``idf.py app``，``idf.py bootloader``，``idf.py partition-table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 - ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。 -- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。 +- ``idf.py -p PORT erase-flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。 - ``idf.py size`` 会打印应用程序相关的大小信息，``size-components`` 和 ``size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。详情请查看 ``idf.py-size``。 - ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。 - ``idf.py python-clean`` 会从 IDF 目录中删除生成的 Python 字节码，Python 字节码可能会在切换 IDF 和 Python 版本时引发问题，因此建议在切换 Python 后运行该命令。 diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index 2efde1f858..ad5dbda1eb 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -16,7 +16,7 @@ - "Single factory app, no OTA" - "Factory app, two OTA definitions" -在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition_table` ，即可以打印当前使用分区表的信息摘要。 +在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition-table` ，即可以打印当前使用分区表的信息摘要。 内置分区表 ------------ @@ -155,7 +155,7 @@ Flags 字段 烧写到 {IDF_TARGET_NAME} 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。 -如果您在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。 +如果您在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition-table``。这时，转换将在编译过程中自动完成。 手动将 CSV 文件转换为二进制文件:: @@ -165,7 +165,7 @@ Flags 字段 python gen_esp32part.py binary_partitions.bin input_partitions.csv -在标准输出（stdout）上，打印二进制分区表的内容（运行 ``idf.py partition_table`` 时展示的信息摘要也是这样生成的）:: +在标准输出（stdout）上，打印二进制分区表的内容（运行 ``idf.py partition-table`` 时展示的信息摘要也是这样生成的）:: python gen_esp32part.py binary_partitions.bin @@ -204,14 +204,14 @@ MD5 校验和 烧写分区表 ---------- -- ``idf.py partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 +- ``idf.py partition-table-flash`` ：使用 esptool.py 工具烧写分区表。 - ``idf.py flash`` ：会烧写所有内容，包括分区表。 -在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 +在执行 ``idf.py partition-table`` 命令时，手动烧写分区表的命令也将打印在终端上。 .. note:: - 分区表的更新并不会擦除根据旧分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 + 分区表的更新并不会擦除根据旧分区表存储的数据。此时，您可以使用 ``idf.py erase-flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 分区工具 (parttool.py) diff --git a/docs/zh_CN/api-reference/storage/nvs_flash.rst b/docs/zh_CN/api-reference/storage/nvs_flash.rst index c4dbb5ce62..a9b37e62d3 100644 --- a/docs/zh_CN/api-reference/storage/nvs_flash.rst +++ b/docs/zh_CN/api-reference/storage/nvs_flash.rst @@ -11,11 +11,11 @@ 底层存储 ^^^^^^^^^^^^^^^^^^ -NVS 通过调用 ``spi_flash_{read|write|erase}`` API 对主 flash 的部分空间进行读、写、擦除操作，包括 ``data`` 类型和 ``nvs`` 子类型的所有分区。应用程序可调用 ``nvs_open`` API 选择使用带有 ``nvs`` 标签的分区，也可以通过调用 ``nvs_open_from_part`` API 选择使用指定名称的任意分区。 +NVS 通过调用 ``spi_flash_{read|write|erase}`` API 对主 flash 的部分空间进行读、写、擦除操作，包括 ``data`` 类型和 ``nvs`` 子类型的所有分区。应用程序可调用 ``nvs_open`` API 选择使用带有 ``nvs`` 标签的分区，也可以通过调用 ``nvs_open_from_part`` API 选择使用指定名称的任意分区。 NVS 库后续版本可能会增加其他存储器后端，实现将数据保存至其他 flash 芯片（SPI 或 I2C 接口）、RTC 或 FRAM 中。 -.. note:: 如果 NVS 分区被截断（例如，更改分区表布局时），则应擦除分区内容。可以使用 ESP-IDF 构建系统中的 ``idf.py erase_flash`` 命令擦除 flash 上的所有内容。 +.. note:: 如果 NVS 分区被截断（例如，更改分区表布局时），则应擦除分区内容。可以使用 ESP-IDF 构建系统中的 ``idf.py erase-flash`` 命令擦除 flash 上的所有内容。 .. note:: NVS 最适合存储一些较小的数据，而非字符串或二进制大对象 (BLOB) 等较大的数据。如需存储较大的 BLOB 或者字符串，请考虑使用基于磨损均衡库的 FAT 文件系统。 diff --git a/docs/zh_CN/get-started-legacy/make-project.rst b/docs/zh_CN/get-started-legacy/make-project.rst index db844f878c..f2c36adf4a 100644 --- a/docs/zh_CN/get-started-legacy/make-project.rst +++ b/docs/zh_CN/get-started-legacy/make-project.rst @@ -75,5 +75,3 @@ ESP32 的一块 flash 可以包含多个应用程序，以及多种数据（校 上述两种情况中，factory app 在 flash 中的烧录偏移地址均为 0x10000。运行 ``make partition_table`` 命令可以打印分区表摘要。 更多有关 :doc:`分区表 <../api-guides/partition-tables>` 及自定义分区表的内容，请见 :doc:`相关文档 <../api-guides/partition-tables>`。 - - diff --git a/examples/security/flash_encryption/README.md b/examples/security/flash_encryption/README.md index 7d53618430..0dd247ad8e 100644 --- a/examples/security/flash_encryption/README.md +++ b/examples/security/flash_encryption/README.md @@ -37,7 +37,7 @@ The configuration for NVS encryption involves generating the XTS encryption keys i) Build and flash the partition table: ``` - idf.py partition_table partition_table-flash + idf.py partition-table partition-table-flash ``` ii) Store the `sample_encryption_keys.bin` in the `nvs_key`partition (on the flash) with the help of [parttool.py](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html#partition-tool-parttool-py): ``` diff --git a/examples/storage/nvs_rw_blob/README.md b/examples/storage/nvs_rw_blob/README.md index 62cf36c45d..398418cabf 100644 --- a/examples/storage/nvs_rw_blob/README.md +++ b/examples/storage/nvs_rw_blob/README.md @@ -63,5 +63,4 @@ Run time: 2: 5860 ``` -To reset the counter and run time array, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. - +To reset the counter and run time array, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above. diff --git a/examples/storage/nvs_rw_value/README.md b/examples/storage/nvs_rw_value/README.md index df725b0e04..e5a7f2e909 100644 --- a/examples/storage/nvs_rw_value/README.md +++ b/examples/storage/nvs_rw_value/README.md @@ -78,5 +78,4 @@ Restarting now. Restart counter will increment on each run. -To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. - +To reset the counter, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above. diff --git a/examples/storage/nvs_rw_value_cxx/README.md b/examples/storage/nvs_rw_value_cxx/README.md index 2adce9b494..7ca19cea36 100644 --- a/examples/storage/nvs_rw_value_cxx/README.md +++ b/examples/storage/nvs_rw_value_cxx/README.md @@ -72,5 +72,4 @@ Restarting now. Restart counter will increment on each run. -To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. - +To reset the counter, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above. diff --git a/examples/storage/spiffs/README.md b/examples/storage/spiffs/README.md index d568839563..0216e44957 100644 --- a/examples/storage/spiffs/README.md +++ b/examples/storage/spiffs/README.md @@ -48,4 +48,4 @@ I (19584) example: Read from file: 'Hello World!' I (19584) example: SPIFFS unmounted ``` -To erase the contents of SPIFFS partition, run `idf.py erase_flash` command. Then upload the example again as described above. +To erase the contents of SPIFFS partition, run `idf.py erase-flash` command. Then upload the example again as described above. diff --git a/examples/storage/wear_levelling/README.md b/examples/storage/wear_levelling/README.md index f3e5c420f7..d0341f7443 100644 --- a/examples/storage/wear_levelling/README.md +++ b/examples/storage/wear_levelling/README.md @@ -51,4 +51,4 @@ I (920) example: Unmounting FAT filesystem I (1000) example: Done ``` -To erase the contents of wear levelling partition, run `idf.py erase_flash` command. Then upload the example again as described above. +To erase the contents of wear levelling partition, run `idf.py erase-flash` command. Then upload the example again as described above. diff --git a/examples/system/efuse/README.md b/examples/system/efuse/README.md index 20251e1ba4..10ec84cac5 100644 --- a/examples/system/efuse/README.md +++ b/examples/system/efuse/README.md @@ -5,10 +5,10 @@ This example shows how to use the eFuse API. It demonstrates read and write operations with fields from the common and custom eFuse tables. For more information about eFuse, see the “eFuse Manager” chapter in the documentation and the “eFuse Controller” chapter in ESP32 TRM. The eFuse is a single bit of non-volatile memory with the restriction that once an eFuse bit is programmed to 1, it can not be reverted to 0. -The eFuse fields can be useful to store: device types, serial numbers, some system variables, etc. +The eFuse fields can be useful to store: device types, serial numbers, some system variables, etc. Note that the bits already written cannot be reset to the original state. For debugging purposes, the `CONFIG_EFUSE_VIRTUAL` option is provided. This option will block physical burning. All work happens with an array in RAM. Use `CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` to keep eFuse changes after reboots. -In this example, all write operations are wrapped in `#ifdef CONFIG_EFUSE_VIRTUAL ... # endif` to prevent accidental burn while testing the features. +In this example, all write operations are wrapped in `#ifdef CONFIG_EFUSE_VIRTUAL ... # endif` to prevent accidental burn while testing the features. ## How to use example @@ -157,7 +157,7 @@ I (447) example: Done ### How to create the new custom table -In the main folder of the example there is a custom eFuse table - `esp_efuse_custom_table.csv`. You can add there some fields and run `idf.py efuse_custom_table`, it will generate all the necessary source files. If all is ok then you will see: +In the main folder of the example there is a custom eFuse table - `esp_efuse_custom_table.csv`. You can add there some fields and run `idf.py efuse-custom-table`, it will generate all the necessary source files. If all is ok then you will see: ``` ... @@ -181,4 +181,4 @@ idf_component_register(SRCS "efuse_main.c" "esp_efuse_custom_table.c" INCLUDE_DIRS "." "include") ``` -If you are not sure which eFuse bits are free you can run `idf.py show_efuse_table`. It prints a sorted list of the common and custom tables. +If you are not sure which eFuse bits are free you can run `idf.py show-efuse-table`. It prints a sorted list of the common and custom tables. diff --git a/examples/system/efuse/main/esp_efuse_custom_table.csv b/examples/system/efuse/main/esp_efuse_custom_table.csv index dea1249192..55fad5d6ae 100644 --- a/examples/system/efuse/main/esp_efuse_custom_table.csv +++ b/examples/system/efuse/main/esp_efuse_custom_table.csv @@ -6,7 +6,7 @@ ########################################################################## # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128. # !!!!!!!!!!! # -# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table" +# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table" # this will generate new source files, next rebuild all the sources. # !!!!!!!!!!! # diff --git a/examples/system/ota/README.md b/examples/system/ota/README.md index b1190cfe78..9354b5cd0b 100644 --- a/examples/system/ota/README.md +++ b/examples/system/ota/README.md @@ -138,7 +138,7 @@ In ``native_ota_example``, ``$PROJECT_PATH/version.txt`` is used to define the a If you see this error, check that the configured (and actual) flash size is large enough for the partitions in the partition table. The default "two OTA slots" partition table requires at least 4MB flash size. To use OTA with smaller flash sizes, create a custom partition table CSV (for details see [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html)) and configure it in menuconfig. -Make sure to run "idf.py erase_flash" after making changes to the partition table. +Make sure to run "idf.py erase-flash" after making changes to the partition table. ### Local https server diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh index fe248e3576..7fc5e94e18 100755 --- a/tools/ci/test_build_system_cmake.sh +++ b/tools/ci/test_build_system_cmake.sh @@ -526,7 +526,7 @@ function run_tests() fi print_status "Displays partition table when executing target partition_table" - idf.py partition_table | grep -E "# ESP-IDF .+ Partition Table" + idf.py partition-table | grep -E "# ESP-IDF .+ Partition Table" rm -r build print_status "Make sure a full build never runs '/usr/bin/env python' or similar" @@ -863,6 +863,16 @@ endmenu\n" >> ${IDF_PATH}/Kconfig idf.py docs --no-browser --language en --version v4.2.1 --target esp32 | grep "https://docs.espressif.com/projects/esp-idf/en/v4.2.1/esp32" || failure "'idf.py docs --no-browser --language en --version v4.2.1 --target esp32' failed" idf.py docs --no-browser --language en --version v4.2.1 --target esp32 --starting-page get-started | grep "https://docs.espressif.com/projects/esp-idf/en/v4.2.1/esp32/get-started" || failure "'idf.py docs --no-browser --language en --version v4.2.1 --target esp32 --starting-page get-started' failed" + print_status "Deprecation warning check" + # click warning + idf.py post_debug &> tmp.log + grep "Warning: Command \"post_debug\" is deprecated and will be removed in v5.0." tmp.log || (failure "Missing deprecation warning with command \"post_debug\"") + rm tmp.log + # cmake warning + idf.py efuse_common_table &> tmp.log + grep "Warning: Command efuse_common_table is deprecated and will be removed in the next major release." tmp.log || (failure "Missing deprecation warning with command \"efuse_common_table\"") + rm tmp.log + print_status "All tests completed" if [ -n "${FAILURES}" ]; then echo "Some failures were detected:" diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake index c476e744d2..5a78e068b6 100644 --- a/tools/cmake/utilities.cmake +++ b/tools/cmake/utilities.cmake @@ -340,3 +340,16 @@ function(add_subdirectory_if_exists source_dir) message(STATUS "Subdirectory '${abs_dir}' does not exist, skipped.") endif() endfunction() + + +# add_deprecated_target_alias +# +# Creates an alias for exising target and shows deprectation warning +function(add_deprecated_target_alias old_target new_target) + add_custom_target(${old_target} + COMMAND ${CMAKE_COMMAND} -E echo + "Warning: Command \"${old_target}\" is deprecated and will be removed in the next major release. \ + Please use \"${new_target}\" instead." + ) + add_dependencies(${old_target} ${new_target}) +endfunction() diff --git a/tools/idf.py b/tools/idf.py index 6e4e9fa58e..3e3986ac5e 100755 --- a/tools/idf.py +++ b/tools/idf.py @@ -519,8 +519,8 @@ def init_cli(verbose_output=None): else: if 'app' in actions: print_flashing_message('App', 'app') - if 'partition_table' in actions: - print_flashing_message('Partition Table', 'partition_table') + if 'partition-table' in actions: + print_flashing_message('Partition Table', 'partition-table') if 'bootloader' in actions: print_flashing_message('Bootloader', 'bootloader') diff --git a/tools/idf_py_actions/core_ext.py b/tools/idf_py_actions/core_ext.py index 736117fe0f..53130cbd6d 100644 --- a/tools/idf_py_actions/core_ext.py +++ b/tools/idf_py_actions/core_ext.py @@ -399,40 +399,80 @@ def action_extensions(base_actions, project_path): 'order_dependencies': ['clean', 'fullclean', 'reconfigure'], 'options': global_options, }, + 'efuse-common-table': { + 'callback': build_target, + 'help': 'Generate C-source for IDF\'s eFuse fields. Deprecated alias: "efuse_common_table".', + 'order_dependencies': ['reconfigure'], + 'options': global_options, + }, 'efuse_common_table': { 'callback': build_target, + 'hidden': True, 'help': "Generate C-source for IDF's eFuse fields.", 'order_dependencies': ['reconfigure'], 'options': global_options, }, + 'efuse-custom-table': { + 'callback': build_target, + 'help': 'Generate C-source for user\'s eFuse fields. Deprecated alias: "efuse_custom_table".', + 'order_dependencies': ['reconfigure'], + 'options': global_options, + }, 'efuse_custom_table': { 'callback': build_target, - 'help': "Generate C-source for user's eFuse fields.", + 'hidden': True, + 'help': 'Generate C-source for user\'s eFuse fields.', + 'order_dependencies': ['reconfigure'], + 'options': global_options, + }, + 'show-efuse-table': { + 'callback': build_target, + 'help': 'Print eFuse table. Deprecated alias: "show_efuse_table".', 'order_dependencies': ['reconfigure'], 'options': global_options, }, 'show_efuse_table': { 'callback': build_target, + 'hidden': True, 'help': 'Print eFuse table.', 'order_dependencies': ['reconfigure'], 'options': global_options, }, + 'partition-table': { + 'callback': build_target, + 'help': 'Build only partition table. Deprecated alias: "parititon_table".', + 'order_dependencies': ['reconfigure'], + 'options': global_options, + }, 'partition_table': { 'callback': build_target, + 'hidden': True, 'help': 'Build only partition table.', 'order_dependencies': ['reconfigure'], 'options': global_options, }, 'erase_otadata': { 'callback': build_target, + 'hidden': True, 'help': 'Erase otadata partition.', 'options': global_options, }, + 'erase-otadata': { + 'callback': build_target, + 'help': 'Erase otadata partition. Deprecated alias: "erase_otadata".', + 'options': global_options, + }, 'read_otadata': { 'callback': build_target, + 'hidden': True, 'help': 'Read otadata partition.', 'options': global_options, }, + 'read-otadata': { + 'callback': build_target, + 'help': 'Read otadata partition. Deprecated alias: "read_otadata".', + 'options': global_options, + }, 'build-system-targets': { 'callback': list_build_system_targets, 'help': 'Print list of build system targets.', diff --git a/tools/idf_py_actions/debug_ext.py b/tools/idf_py_actions/debug_ext.py index d9c43cb9e5..53b94e810a 100644 --- a/tools/idf_py_actions/debug_ext.py +++ b/tools/idf_py_actions/debug_ext.py @@ -367,8 +367,26 @@ def action_extensions(base_actions, project_path): 'options': [gdbinit, fail_if_openocd_failed], 'order_dependencies': ['all', 'flash'], }, + 'post-debug': { + 'callback': post_debug, + 'help': 'Utility target to read the output of async debug action and stop them.', + 'options': [ + { + 'names': ['--block', '--block'], + 'help': + ('Set to 1 for blocking the console on the outputs of async debug actions\n'), + 'default': 0, + }, + ], + 'order_dependencies': [], + }, 'post_debug': { 'callback': post_debug, + 'deprecated': { + 'removed': 'v5.0', + 'message': 'Please use "post-debug" instead.', + }, + 'hidden': True, 'help': 'Utility target to read the output of async debug action and stop them.', 'options': [ { diff --git a/tools/idf_py_actions/serial_ext.py b/tools/idf_py_actions/serial_ext.py index e89c765653..4d63e8df2e 100644 --- a/tools/idf_py_actions/serial_ext.py +++ b/tools/idf_py_actions/serial_ext.py @@ -177,10 +177,20 @@ def action_extensions(base_actions, project_path): 'callback': flash, 'help': 'Flash the project.', 'options': global_options + [baud_rate, port], - 'order_dependencies': ['all', 'erase_flash'], + 'order_dependencies': ['all', 'erase-flash'], + }, + 'erase-flash': { + 'callback': erase_flash, + 'help': 'Erase entire flash chip. Deprecated alias: "erase_flash"', + 'options': [baud_rate, port], }, 'erase_flash': { 'callback': erase_flash, + 'deprecated': { + 'removed': 'v5.0', + 'message': 'Please use "erase-flash" instead.', + }, + 'hidden': True, 'help': 'Erase entire flash chip.', 'options': [baud_rate, port], }, @@ -235,39 +245,46 @@ def action_extensions(base_actions, project_path): 'order_dependencies': [ 'flash', 'encrypted-flash', - 'partition_table-flash', + 'partition-table-flash', 'bootloader-flash', 'app-flash', 'encrypted-app-flash', ], }, + 'partition-table-flash': { + 'callback': flash, + 'help': 'Flash partition table only. Deprecated alias: "partition_table-flash".', + 'options': [baud_rate, port], + 'order_dependencies': ['partition-table', 'erase-flash'], + }, 'partition_table-flash': { 'callback': flash, + 'hidden': True, 'help': 'Flash partition table only.', 'options': [baud_rate, port], - 'order_dependencies': ['partition_table', 'erase_flash'], + 'order_dependencies': ['partition-table', 'erase-flash'], }, 'bootloader-flash': { 'callback': flash, 'help': 'Flash bootloader only.', 'options': [baud_rate, port], - 'order_dependencies': ['bootloader', 'erase_flash'], + 'order_dependencies': ['bootloader', 'erase-flash'], }, 'app-flash': { 'callback': flash, 'help': 'Flash the app only.', 'options': [baud_rate, port], - 'order_dependencies': ['app', 'erase_flash'], + 'order_dependencies': ['app', 'erase-flash'], }, 'encrypted-app-flash': { 'callback': flash, 'help': 'Flash the encrypted app only.', - 'order_dependencies': ['app', 'erase_flash'], + 'order_dependencies': ['app', 'erase-flash'], }, 'encrypted-flash': { 'callback': flash, 'help': 'Flash the encrypted project.', - 'order_dependencies': ['all', 'erase_flash'], + 'order_dependencies': ['all', 'erase-flash'], }, }, }