forked from espressif/esp-idf
docs: sync up CN and EN versions for build-system and partition-tables
This commit is contained in:
Shang Zhou
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user