Merge branch 'docs/sync_up_build_system_and_partition_tables' into 'master'

docs: sync up CN and EN versions for build-system and partition-tables

Closes DOC-3621

See merge request espressif/esp-idf!19907
pull/9803/head
morris 2022-09-10 10:32:27 +08:00
commit a326e1c2ac
4 zmienionych plików z 45 dodań i 41 usunięć

Wyświetl plik

@ -80,7 +80,7 @@ If using CMake with ``ninja`` or ``make``, there are also targets for more of th
.. _flash-with-ninja-or-make:
Flashing with ninja or make
Flashing with Ninja or Make
^^^^^^^^^^^^^^^^^^^^^^^^^^^
It's possible to build and flash directly from ninja or make by running a target like::
@ -129,7 +129,7 @@ If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache overri
To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default Python version.
Possible issues
Possible Issues
^^^^^^^^^^^^^^^^^^^^^
The user of ``idf.py`` may sometimes experience ``ImportError`` described below.
@ -234,7 +234,7 @@ To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIA
.. _rename-main:
Renaming ``main`` component
Renaming ``main`` Component
----------------------------
The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component causes the loss of these behind-the-scenes heavy lifting, requiring the user to specify the location of the newly renamed component and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows:
@ -244,7 +244,7 @@ The build system provides special treatment to the ``main`` component. It is a c
3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration<cmake_minimal_component_cmakelists>`.
Overriding default build specifications
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.
@ -281,7 +281,7 @@ When CMake runs to configure the project, it logs the components included in the
.. _cmake-components-same-name:
Multiple components with the same name
Multiple Components with the Same Name
--------------------------------------
When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first (``IDF_PATH/components``), then any components in directories specified in ``EXTRA_COMPONENT_DIRS``, and finally the project's components (``PROJECT_DIR/components``). If two or more of these directories contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. If used in this way, the ESP-IDF directory itself can remain untouched.
@ -333,8 +333,7 @@ The following variables are set at the project level, but available for use in c
Build/Project Variables
------------------------
The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property``
from the component CMakeLists.txt:
The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` from the component CMakeLists.txt:
- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file.
- ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable.
@ -403,7 +402,7 @@ Component Requirements
When compiling each component, the ESP-IDF build system recursively evaluates its dependencies. This means each component needs to declare the components that it depends on ("requires").
When writing a component
When Writing a Component
------------------------
.. code-block:: cmake
@ -426,7 +425,7 @@ If a components only supports some target chips (values of ``IDF_TARGET``) then
.. _example component requirements:
Example of component requirements
Example of Component Requirements
---------------------------------
Imagine there is a ``car`` component, which uses the ``engine`` component, which uses the ``spark_plug`` component:
@ -445,7 +444,7 @@ Imagine there is a ``car`` component, which uses the ``engine`` component, which
- spark_plug.c
- spark_plug.h
Car component
Car Component
^^^^^^^^^^^^^
.. highlight:: c
@ -476,7 +475,7 @@ This means the ``car/CMakeLists.txt`` file needs to declare that ``car`` require
- ``INCLUDE_DIRS`` gives the list of public include directories for this component. Because the public interface is ``car.h``, the directory containing ``car.h`` is listed here.
- ``REQUIRES`` gives the list of components required by the public interface of this component. Because ``car.h`` is a public header and includes a header from ``engine``, we include ``engine`` here. This makes sure that any other component which includes ``car.h`` will be able to recursively include the required ``engine.h`` also.
Engine component
Engine Component
^^^^^^^^^^^^^^^^
.. highlight:: c
@ -537,21 +536,21 @@ Each component's source file is compiled with these include path directories, as
- The ``INCLUDE_DIRS`` belonging to all other components listed in the ``REQUIRES`` and ``PRIV_REQUIRES`` parameters (ie all the current component's public and private dependencies).
- Recursively, all of the ``INCLUDE_DIRS`` of those components ``REQUIRES`` lists (ie all public dependencies of this component's dependencies, recursively expanded).
Main component requirements
Main Component Requirements
---------------------------
The component named ``main`` is special because it automatically requires all other components in the build. So it's not necessary to pass ``REQUIRES`` or ``PRIV_REQUIRES`` to this component. See :ref:`renaming main <rename-main>` for a description of what needs to be changed if no longer using the ``main`` component.
.. _component-common-requirements:
Common component requirements
Common Component Requirements
-----------------------------
To avoid duplication, every component automatically requires some "common" IDF components even if they are not mentioned explicitly. Headers from these components can always be included.
The list of common components is: cxx, newlib, freertos, esp_hw_support, heap, log, soc, hal, esp_rom, esp_common, esp_system, xtensa/riscv.
Including components in the build
Including Components in the Build
----------------------------------
- By default, every component is included in the build.
@ -607,7 +606,7 @@ See the `target_link_libraries`_ documentation for more information about this C
.. _component-requirements-implementation:
Requirements in the build system implementation
Requirements in the Build System Implementation
-----------------------------------------------
- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this :ref:`graph may have cycles <component-circular-dependencies>`). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
@ -699,7 +698,7 @@ Here are some more advanced examples of component CMakeLists files.
.. _add_conditional_config:
Adding conditional configuration
Adding Conditional Configuration
--------------------------------
The configuration system can be used to conditionally compile some files depending on the options selected in the project configuration.
@ -765,7 +764,7 @@ This can also be used to select or stub out an implementation, as such:
idf_component_register(SRCS "${srcs}"
...)
Conditions which depend on the target
Conditions Which Depend on the Target
-------------------------------------
The current target is available to CMake files via ``IDF_TARGET`` variable.
@ -861,7 +860,7 @@ ESP-IDF has a feature called linker script generation that enables components to
.. _component-build-full-override:
Fully Overriding The Component Build Process
Fully Overriding the Component Build Process
--------------------------------------------
.. highlight:: cmake
@ -908,8 +907,8 @@ Obviously, there are cases where all these recipes are insufficient for a certai
.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
ExternalProject dependencies, clean builds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ExternalProject Dependencies and Clean Builds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CMake has some unusual behaviour around external project builds:
@ -924,7 +923,7 @@ The best of these approaches for building an external project will depend on the
.. _custom-sdkconfig-defaults:
Custom sdkconfig defaults
Custom Sdkconfig Defaults
=========================
For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
@ -935,7 +934,7 @@ When specifying multiple files, use a semicolon as the list separator. Files lis
Some of the IDF examples include a ``sdkconfig.ci`` file. This is part of the continuous integration (CI) test framework and is ignored by the normal build process.
Target-dependent sdkconfig defaults
Target-dependent Sdkconfig Defaults
-----------------------------------
In addition to ``sdkconfig.defaults`` file, build system will also load defaults from ``sdkconfig.defaults.TARGET_NAME`` file, where ``TARGET_NAME`` is the value of ``IDF_TARGET``. For example, for ``esp32`` target, default settings will be taken from ``sdkconfig.defaults`` first, and then from ``sdkconfig.defaults.esp32``.
@ -946,7 +945,7 @@ For example, if ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"``, a
.. _flash_parameters:
Flash arguments
Flash Arguments
===============
There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
@ -1025,7 +1024,7 @@ It is also possible to wrap a third-party library to be used as a component in t
The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required.
Using ESP-IDF components from external libraries
Using ESP-IDF Components from External Libraries
------------------------------------------------
The above example assumes that the external library ``foo`` (or ``tinyxml`` in the case of the ``import_lib`` example) doesn't need to use any ESP-IDF APIs apart from common APIs such as libc, libstdc++, etc. If the external library needs to use APIs provided by other ESP-IDF components, this needs to be specified in the external CMakeLists.txt file by adding a dependency on the library target ``idf::<componentname>``.
@ -1480,7 +1479,7 @@ No Longer Necessary
- In the legacy Make-based build system, it is required to also set ``COMPONENT_SRCDIRS`` if ``COMPONENT_SRCS`` is set. In CMake, the equivalent is not necessary i.e. specifying ``SRC_DIRS`` to ``idf_component_register`` if ``SRCS`` is also specified (in fact, ``SRCS`` is ignored if ``SRC_DIRS`` is specified).
Flashing from make
Flashing from Make
------------------
``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details.

Wyświetl plik

@ -66,12 +66,12 @@ The CSV format is the same format as printed in the summaries shown above. Howev
* Each non-comment line in the CSV file is a partition definition.
* The "Offset" field for each partition is empty. The gen_esp32part.py tool fills in each blank offset, starting after the partition table and making sure each partition is aligned correctly.
Name field
Name Field
~~~~~~~~~~
Name field can be any meaningful name. It is not significant to the {IDF_TARGET_NAME}. The maximum length of names is 16 bytes, including one null terminator. Names longer than the maximum length will be truncated.
Type field
Type Field
~~~~~~~~~~
Partition type field can be specified as ``app`` (0x00) or ``data`` (0x01). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for ESP-IDF core functions.
@ -134,7 +134,7 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
Extra Partition SubTypes
~~~~~~~~~~~~~~~~~~~~~~~~
A component can define a new partition subtype by setting the ``EXTRA_PARTITION_SUBTYPES`` property. This property is a CMake list, each entry of which is a comma separated string with ``<type>, <subtype>, <value>`` format. The build system uses this property to add extra subtypes and creates fields named ``ESP_PARTITION_SUBTYPE_<type>_<subtype>`` in :cpp:type:`esp_partition_type_t`. The project can use this subtype to define partitions in the partitions table CSV file and use the new fields in :cpp:type:`esp_partition_type_t`.
A component can define a new partition subtype by setting the ``EXTRA_PARTITION_SUBTYPES`` property. This property is a CMake list, each entry of which is a comma separated string with ``<type>, <subtype>, <value>`` format. The build system uses this property to add extra subtypes and creates fields named ``ESP_PARTITION_SUBTYPE_<type>_<subtype>`` in :cpp:type:`esp_partition_subtype_t`. The project can use this subtype to define partitions in the partitions table CSV file and use the new fields in :cpp:type:`esp_partition_subtype_t`.
Offset & Size
~~~~~~~~~~~~~
@ -189,7 +189,7 @@ Currently these checks are performed for the following binaries:
Although the build process will fail if the size check returns an error, the binary files are still generated and can be flashed (although they may not work if they are too large for the available space.)
MD5 checksum
MD5 Checksum
~~~~~~~~~~~~
The binary format of the partition table contains an MD5 checksum computed based on the partition table. This checksum is used for checking the integrity of the partition table during the boot.
@ -203,7 +203,7 @@ The binary format of the partition table contains an MD5 checksum computed based
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :ref:`CONFIG_PARTITION_TABLE_MD5` option.
Flashing the partition table
Flashing the Partition Table
----------------------------
* ``idf.py partition-table-flash``: will flash the partition table with esptool.py.

Wyświetl plik

@ -335,7 +335,6 @@ ESP-IDF 在搜索所有待构建的组件时,会按照 ``COMPONENT_DIRS`` 指
以下是可作为构建属性的构建/项目变量,可通过组件 CMakeLists.txt 中的 ``idf_build_get_property`` 查询其变量值。
- ``PROJECT_NAME``:项目名,在项目 CMakeLists.txt 文件中设置。
- ``PROJECT_DIR``:项目目录(包含项目 CMakeLists 文件)的绝对路径,与 ``CMAKE_SOURCE_DIR`` 变量相同。
- ``COMPONENTS``:此次构建中包含的所有组件的名称,具体格式为用分号隔开的 CMake 列表。
@ -343,6 +342,7 @@ ESP-IDF 在搜索所有待构建的组件时,会按照 ``COMPONENT_DIRS`` 指
- ``IDF_VERSION_MAJOR````IDF_VERSION_MINOR````IDF_VERSION_PATCH``: ESP-IDF 的组件版本,可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量,版本号 ``v4.0-dev-*`` ``v4.0-beta1`` ``v4.0-rc1````v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的,但是 ``IDF_VER`` 的值是不同的。
- ``IDF_TARGET``:项目的硬件目标名称。
- ``PROJECT_VER``:项目版本号。
- ``EXTRA_PARTITION_SUBTYPES``CMake 列表,用于创建额外的分区子类型。子类型的描述由字符串组成,以逗号为分隔,格式为 ``type_name, subtype_name, numeric_value``。组件可通过此列表,添加新的子类型。
* 如果设置 :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` 选项,将会使用 :ref:`CONFIG_APP_PROJECT_VER` 的值。
* 或者,如果在项目 CMakeLists.txt 文件中设置了 ``PROJECT_VER`` 变量,则该变量值可以使用。
@ -626,12 +626,12 @@ CMake 通常会在链接器命令行上重复两次组件库名称来自动处
.. _override_project_config:
覆盖项目的部分设置
------------------
=====================
.. _project_include.cmake:
project_include.cmake
^^^^^^^^^^^^^^^^^^^^^
---------------------
如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行,您可以在组件目录下创建名为 ``project_include.cmake`` 的文件,``project.cmake`` 在运行过程中会导入此 CMake 文件。
@ -646,7 +646,7 @@ project_include.cmake
``project_include.cmake`` 文件中设置变量或目标时要格外小心,这些值被包含在项目的顶层 CMake 文件中,因此他们会影响或破坏所有组件的功能。
KConfig.projbuild
^^^^^^^^^^^^^^^^^
-----------------
``project_include.cmake`` 类似,也可以为组件定义一个 KConfig 文件以实现全局的 :ref:`component-configuration`。如果要在 menuconfig 的顶层添加配置选项,而不是在 “Component Configuration” 子菜单中,则可以在 ``CMakeLists.txt`` 文件所在目录的 KConfig.projbuild 文件中定义这些选项。
@ -657,12 +657,12 @@ KConfig.projbuild
.. _config_only_component:
仅配置组件
^^^^^^^^^^
===========
仅配置组件是一类不包含源文件的特殊组件,仅包含 ``Kconfig.projbuild````KConfig````CMakeLists.txt`` 文件,该 ``CMakeLists.txt`` 文件仅有一行代码,调用了 ``idf_component_register()`` 函数。此函数会将组件导入到项目构建中,但不会构建任何库,也不会将头文件添加到任何 include 搜索路径中。
CMake 调试
----------
===========
请查看 `CMake v3.16 官方文档`_ 获取更多关于 CMake_ 和 CMake 命令的信息。
@ -679,7 +679,7 @@ CMake 调试
.. _warn-undefined-variables:
警告未定义的变量
^^^^^^^^^^^^^^^^
------------------
默认情况下,``idf.py`` 在调用 CMake_ 时会给它传递 ``--warn-uninitialized`` 标志如果在构建的过程中引用了未定义的变量CMake_ 会打印警告。这对查找有错误的 CMake 文件非常有用。
@ -1100,7 +1100,7 @@ ESP-IDF 提供了一个模板 CMake 项目,可以基于此轻松创建应用
ESP-IDF CMake 构建系统 API
==============================
idf 构建命令
ESP-IDF 构建命令
------------------
.. code-block:: none
@ -1163,7 +1163,7 @@ idf 构建命令
.. _cmake-build-properties:
idf 构建属性
ESP-IDF 构建属性
--------------------
可以通过使用构建命令 ``idf_build_get_property`` 来获取构建属性的值。例如,以下命令可以获取构建过程中使用的 Python 解释器的相关信息。
@ -1201,7 +1201,7 @@ idf 构建属性
- SDKCONFIG_JSON - 包含组件配置的 JSON 文件的完整路径;由 ``idf_build_process`` 设置。
- SDKCONFIG_JSON_MENUS - 包含配置菜单的 JSON 文件的完整路径;由 ``idf_build_process`` 设置。
idf 组件命令
ESP-IDF 组件命令
----------------------
.. code-block:: none
@ -1262,7 +1262,7 @@ idf 组件命令
.. _cmake-component-properties:
idf 组件属性
ESP-IDF 组件属性
------------------------
组件的属性值可以通过使用构建命令 ``idf_component_get_property`` 来获取。例如,以下命令可以获取 ``freertos`` 组件的目录。

Wyświetl plik

@ -131,6 +131,11 @@ SubType 字段长度为 8 bit内容与具体分区 Type 有关。目前esp
请注意如果用 C++ 编写,应用程序定义的子类型值需要转换为 :cpp:type:`esp_partition_type_t`,从而与 :ref:`分区 API<api-reference-partition-table>` 一起使用。
额外分区 SubType 字段
~~~~~~~~~~~~~~~~~~~~~~~~
组件可以通过设置 ``EXTRA_PARTITION_SUBTYPES`` 属性来定义额外的分区子类型。 ``EXTRA_PARTITION_SUBTYPES`` 是一个 CMake 列表,其中的每个条目由字符串组成,以逗号为分隔,格式为 ``<type>, <subtype>, <value>``。构建系统通过该属性会自动添加额外的子类型,并在 :cpp:type:`esp_partition_subtype_t` 中插入名为 ``ESP_PARTITION_SUBTYPE_<type>_<subtype>`` 的字段。项目可以使用这个子类型来定义分区表 CSV 文件中的分区,并使用 :cpp:type:`esp_partition_subtype_t` 中的新字段。
Offset 和 Size 字段
~~~~~~~~~~~~~~~~~~~