api-guides: update CN translation for build-system and build-system-legacy,and fix line break in the EN version

docs/en/api-guides/build-system-legacy.rst

@@ -4,8 +4,7 @@ Build System (Legacy GNU Make)
 
 .. include:: ../gnu-make-legacy.rst
 
-This document explains the legacy GNU Make Espressif IoT Development Framework build system and the
+This document explains the legacy GNU Make Espressif IoT Development Framework build system and the concept of "components"
-concept of "components"
 
 Read this document if you want to know how to organise an ESP-IDF project using GNU Make build system.
 
@@ -19,8 +18,7 @@ The esp-idf README file contains a description of how to use the build system to
 Overview
 ========
 
-An ESP-IDF project can be seen as an amalgamation of a number of components.
+An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be:
-For example, for a webserver that shows the current humidity, there could be:
 
 - The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc)
 - The Wi-Fi drivers
@@ -30,13 +28,7 @@ For example, for a webserver that shows the current humidity, there could be:
 - A driver for the humidity sensor
 - Main code tying it all together
 
-ESP-IDF makes these components explicit and configurable. To do that,
+ESP-IDF makes these components explicit and configurable. To do that, when a project is compiled, the build environment will look up all the components in the ESP-IDF directories, the project directories and (optionally) in additional custom component directories. It then allows the user to configure the ESP-IDF project using a a text-based menu system to customize each component. After the components in the project are configured, the build process will compile the project.
-when a project is compiled, the build environment will look up all the
-components in the ESP-IDF directories, the project directories and
-(optionally) in additional custom component directories. It then
-allows the user to configure the ESP-IDF project using a a text-based
-menu system to customize each component. After the components in the
-project are configured, the build process will compile the project.
 
 Concepts
 --------
@@ -55,7 +47,6 @@ Some things are not part of the project:
 
 - The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration.
 
-
 Example Project
 ---------------
 
@@ -79,9 +70,7 @@ An example project directory tree might look like this::
 
 This example "myProject" contains the following elements:
 
-- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines
+- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which implements the rest of the ESP-IDF build system.
-  other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which
-  implements the rest of the ESP-IDF build system.
 
 - "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
 
@@ -91,8 +80,7 @@ This example "myProject" contains the following elements:
 
 - "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
 
-Component directories contain a component makefile - ``component.mk``. This may contain variable definitions
+Component directories contain a component makefile - ``component.mk``. This may contain variable definitions to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.
-to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.
 
 Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`.
 
@@ -110,7 +98,6 @@ Minimal Example Makefile
 
    include $(IDF_PATH)/make/project.mk
 
-
 Mandatory Project Variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -133,6 +120,8 @@ Any paths in these Makefile variables should be absolute paths. You can convert
 
 These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile.
 
+
+
 Component Makefiles
 -------------------
 
@@ -150,12 +139,10 @@ Running the ``make list-components`` target dumps many of these variables and ca
 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 the
+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 the idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories contain component subdirectories 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 simply copying the component from the esp-idf component directory to the project component tree and then modifying it there.
-idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories
-contain component subdirectories 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 simply copying the component from the esp-idf component directory to the project component tree and then modifying it there.
 If used in this way, the esp-idf directory itself can remain untouched.
 
+
 Minimal Component Makefile
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -201,37 +188,21 @@ The following variables are set at the project level, but exported for use in th
 
 If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
 
+
+
 Optional Project-Wide Component Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following variables can be set inside ``component.mk`` to control build settings across the entire project:
 
-- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
+- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
-  directory, which will be added to the include search path for
+- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for the app executable. Defaults to ``-l$(COMPONENT_NAME)``.  If adding pre-compiled libraries to this directory, add them as absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
-  all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile
+- ``COMPONENT_DEPENDS``: Optional list of component names that should be compiled before this component. This is not necessary for link-time dependencies, because all component include directories are available at all times. It is necessary if one component generates an include file which you then want to include in another component. Most components do not need to set this variable.
-  this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
+- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths to files which should trigger a re-link of the ELF file if they change. Typically used for linker script files and binary libraries. Most components do not need to set this variable.
-- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for
-  the app executable. Defaults to ``-l$(COMPONENT_NAME)``.  If
-  adding pre-compiled libraries to this directory, add them as
-  absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
-- ``COMPONENT_DEPENDS``: Optional list of component names that should
-  be compiled before this component. This is not necessary for
-  link-time dependencies, because all component include directories
-  are available at all times. It is necessary if one component
-  generates an include file which you then want to include in another
-  component. Most components do not need to set this variable.
-- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths
-  to files which should trigger a re-link of the ELF file if they change.
-  Typically used for linker script files and binary libraries. Most components do
-  not need to set this variable.
 
 The following variable only works for components that are part of esp-idf itself:
 
-- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths
+- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths (relative to COMPONENT_PATH) used by the component. These will be checked (and initialised if necessary) by the build process. This variable is ignored if the component is outside the IDF_PATH directory.
-  (relative to COMPONENT_PATH) used by the component. These will be
-  checked (and initialised if necessary) by the build process. This
-  variable is ignored if the component is outside the IDF_PATH
-  directory.
 
 
 Optional Component-Specific Variables
@@ -239,54 +210,17 @@ Optional Component-Specific Variables
 
 The following variables can be set inside ``component.mk`` to control the build of that component:
 
-- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
+- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to the component directory, which will be added to the include search path for this component's source files only.
-  the component directory, which will be added to the include search
+- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when compiling the component's source files. These will be prefixed with '-I' and passed as-is to the compiler.  Similar to the ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not expanded relative to the component directory.
-  path for this component's source files only.
+- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``, ``*.c``, ``*.S``). Defaults to '.', ie the component directory itself. Override this to specify a different list of directories which contain source files.
-- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when
+- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o file for each source file that is found in ``COMPONENT_SRCDIRS``. Overriding this list allows you to exclude source files in ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See `Specifying source files`
-  compiling the component's source files. These will be prefixed with
+- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build directory, of any files that are generated using custom make rules in the component.mk file and which need to be removed as part of ``make clean``. See `Source Code Generation`_ for an example.
-  '-I' and passed as-is to the compiler.  Similar to the
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These targets allow you to fully override the default build behaviour for the component. See `Fully Overriding The Component Makefile`_ for more details.
-  ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not
+- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built), and most other component variables are ignored. This flag is used for IDF internal components which contain only ``KConfig.projbuild`` and/or ``Makefile.projbuild`` files to configure the project, but no source files.
-  expanded relative to the component directory.
+- ``CFLAGS``: Flags passed to the C compiler. A default set of ``CFLAGS`` is defined based on project settings. Component-specific additions can be made via ``CFLAGS +=``. It is also possible (although not recommended) to override this variable completely for a component.
-- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
+- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp and .S files). A default set of ``CPPFLAGS`` is defined based on project settings. Component-specific additions can be made via ``CPPFLAGS +=``. It is also possible (although not recommended) to override this variable completely for a component.
-  component directory, which will be searched for source files (``*.cpp``,
+- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of ``CXXFLAGS`` is defined based on project settings. Component-specific additions can be made via ``CXXFLAGS +=``. It is also possible (although not recommended) to override this variable completely for a component.
-  ``*.c``, ``*.S``). Defaults to '.', ie the component directory
+- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker script generation functionality. See :doc:`Linker Script Generation <linker-script-generation>`.
-  itself. Override this to specify a different list of directories
-  which contain source files.
-- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o
-  file for each source file that is found in ``COMPONENT_SRCDIRS``.
-  Overriding this list allows you to exclude source files in
-  ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See
-  `Specifying source files`
-- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build
-  directory, of any files that are generated using custom make rules
-  in the component.mk file and which need to be removed as part of
-  ``make clean``. See `Source Code Generation`_ for an example.
-- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These
-  targets allow you to fully override the default build behaviour for
-  the component. See `Fully Overriding The Component Makefile`_ for
-  more details.
-- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component
-  produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built),
-  and most other component variables are ignored. This flag is used for IDF
-  internal components which contain only ``KConfig.projbuild`` and/or
-  ``Makefile.projbuild`` files to configure the project, but no source files.
-- ``CFLAGS``: Flags passed to the C compiler. A default set of
-  ``CFLAGS`` is defined based on project settings. Component-specific
-  additions can be made via ``CFLAGS +=``. It is also possible
-  (although not recommended) to override this variable completely for
-  a component.
-- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp
-  and .S files). A default set of ``CPPFLAGS`` is defined based on
-  project settings. Component-specific additions can be made via
-  ``CPPFLAGS +=``. It is also possible (although not recommended) to
-  override this variable completely for a component.
-- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of
-  ``CXXFLAGS`` is defined based on project
-  settings. Component-specific additions can be made via ``CXXFLAGS
-  +=``. It is also possible (although not recommended) to override
-  this variable completely for a component.
-- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker
-  script generation functionality. See :doc:`Linker Script Generation <linker-script-generation>`.
 
 To apply compilation flags to a single source file, you can add a variable override as a target, ie::
 
@@ -297,8 +231,7 @@ This can be useful if there is upstream code that emits warnings.
 Component Configuration
 -----------------------
 
-Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
+Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains configuration settings to add to the "make menuconfig" for this component.
-configuration settings to add to the "make menuconfig" for this component.
 
 These settings are found under the "Component Settings" menu when menuconfig is run.
 
@@ -364,7 +297,6 @@ Advanced Make Targets
 - ``make erase_flash`` and ``make erase_otadata`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively.
 - ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively.
 
-
 Debugging The Make Process
 --------------------------
 
@@ -394,13 +326,9 @@ Overriding Parts of the Project
 Makefile.projbuild
 ^^^^^^^^^^^^^^^^^^
 
-For components that have build requirements that must be evaluated in the top-level
+For components that have build requirements that must be evaluated in the top-level project make pass, you can create a file called ``Makefile.projbuild`` in the component directory. This makefile is included when ``project.mk`` is evaluated.
-project make pass, you can create a file called ``Makefile.projbuild`` in the
-component directory. This makefile is included when ``project.mk`` is evaluated.
 
-For example, if your component needs to add to CFLAGS for the entire
+For example, if your component needs to add to CFLAGS for the entire project (not just for its own source files) then you can set ``CFLAGS +=`` in Makefile.projbuild.
-project (not just for its own source files) then you can set
-``CFLAGS +=`` in Makefile.projbuild.
 
 ``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
 
@@ -411,34 +339,29 @@ Take care when setting variables or targets in this file. As the values are incl
 KConfig.projbuild
 ^^^^^^^^^^^^^^^^^
 
-This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include
+This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file.
-configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file.
 
 Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
 
-
 Makefile.componentbuild
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions
+For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component.
-into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included
-in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're
-included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component.
 
 Configuration-Only Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component.
 
+
+
 Example Component Makefiles
 ---------------------------
 
-Because the build environment tries to set reasonable defaults that will work most
+Because the build environment tries to set reasonable defaults that will work most of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.
-of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.
 
 Here are some more advanced examples of ``component.mk`` makefiles:
 
-
 Adding source directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -448,29 +371,26 @@ system by setting ``COMPONENT_SRCDIRS``::
 
     COMPONENT_SRCDIRS := src1 src2
 
-This will compile all source files in the src1/ and src2/ sub-directories
+This will compile all source files in the src1/ and src2/ sub-directories instead.
-instead.
+
+
 
 Specifying source files
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The standard component.mk logic adds all .S and .c files in the source
+The standard component.mk logic adds all .S and .c files in the source directories as sources to be compiled unconditionally. It is possible to circumvent that logic and hard-code the objects to be compiled by manually setting the ``COMPONENT_OBJS`` variable to the name of the objects that need to be generated::
-directories as sources to be compiled unconditionally. It is possible
-to circumvent that logic and hard-code the objects to be compiled by
-manually setting the ``COMPONENT_OBJS`` variable to the name of the
-objects that need to be generated::
 
     COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
     COMPONENT_SRCDIRS := . thing anotherthing
 
 Note that ``COMPONENT_SRCDIRS`` must be set as well.
 
+
+
 Adding conditional configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The configuration system can be used to conditionally compile some files
+The configuration system can be used to conditionally compile some files depending on the options selected in ``make menuconfig``. For this, ESP-IDF has the compile_only_if and compile_only_if_not macros:
-depending on the options selected in ``make menuconfig``. For this, ESP-IDF
-has the compile_only_if and compile_only_if_not macros:
 
 ``Kconfig``::
 
@@ -483,13 +403,7 @@ has the compile_only_if and compile_only_if_not macros:
 
     $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
 
-
+As can be seen in the example, the ``compile_only_if`` macro takes a condition and a list of object files as parameters. If the condition is true (in this case: if the BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will always be compiled. The opposite goes as well: if the condition is not true, bar.o will never be compiled. ``compile_only_if_not`` does the opposite: compile if the condition is false, not compile if the condition is true.
-As can be seen in the example, the ``compile_only_if`` macro takes a condition and a
-list of object files as parameters. If the condition is true (in this case: if the
-BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will
-always be compiled. The opposite goes as well: if the condition is not true, bar.o
-will never be compiled. ``compile_only_if_not`` does the opposite: compile if the
-condition is false, not compile if the condition is true.
 
 This can also be used to select or stub out an implementation, as such:
 
@@ -522,25 +436,16 @@ This can also be used to select or stub out an implementation, as such:
     #We need font if either console or plot is enabled
     $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
 
-Note the use of the Make 'or' function to include the font file. Other substitution functions,
+Note the use of the Make 'or' function to include the font file. Other substitution functions, like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains only whitespace to be false while a variable with any non-whitespace in it is true.
-like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also
+
-be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains
+(Note: Older versions of this document advised conditionally adding object file names to ``COMPONENT_OBJS``. While this still is possible, this will only work when all object files for a component are named explicitely, and will not clean up deselected object files in a ``make clean`` pass.)
-only whitespace to be false while a variable with any non-whitespace in it is true.
+
 
-(Note: Older versions of this document advised conditionally adding object file names to
-``COMPONENT_OBJS``. While this still is possible, this will only work when all object
-files for a component are named explicitely, and will not clean up deselected object files
-in a ``make clean`` pass.)
 
 Source Code Generation
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Some components will have a situation where a source file isn't
+Some components will have a situation where a source file isn't supplied with the component itself but has to be generated from another file. Say our component has a header file that consists of the converted binary data of a BMP file, converted using a hypothetical tool called bmp2h. The header file is then included in as C source file called graphics_lib.c::
-supplied with the component itself but has to be generated from
-another file. Say our component has a header file that consists of the
-converted binary data of a BMP file, converted using a hypothetical
-tool called bmp2h. The header file is then included in as C source
-file called graphics_lib.c::
 
     COMPONENT_EXTRA_CLEAN := logo.h
 
@@ -549,27 +454,16 @@ file called graphics_lib.c::
     logo.h: $(COMPONENT_PATH)/logo.bmp
         bmp2h -i $^ -o $@
 
-
+In this example, graphics_lib.o and logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a generated file, it needs to be cleaned when make clean is called which why it is added to the COMPONENT_EXTRA_CLEAN variable.
-In this example, graphics_lib.o and logo.h will be generated in the
-current directory (the build directory) while logo.bmp comes with the
-component and resides under the component path. Because logo.h is a
-generated file, it needs to be cleaned when make clean is called which
-why it is added to the COMPONENT_EXTRA_CLEAN variable.
 
 Cosmetic Improvements
 ^^^^^^^^^^^^^^^^^^^^^
 
-Because logo.h is a generated file, it needs to be cleaned when make
+Because logo.h is a generated file, it needs to be cleaned when make clean is called which why it is added to the COMPONENT_EXTRA_CLEAN variable.
-clean is called which why it is added to the COMPONENT_EXTRA_CLEAN
-variable.
 
-Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be
+Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be generated before ``graphics_lib.c`` is compiled.
-generated before ``graphics_lib.c`` is compiled.
 
-If a a source file in another component included ``logo.h``, then this
+If a a source file in another component included ``logo.h``, then this component's name would have to be added to the other component's ``COMPONENT_DEPENDS`` list to ensure that the components were built in-order.
-component's name would have to be added to the other component's
-``COMPONENT_DEPENDS`` list to ensure that the components were built
-in-order.
 
 Embedding Binary Data
 ^^^^^^^^^^^^^^^^^^^^^
@@ -596,25 +490,16 @@ For an example of using this technique, see the "main" component of the file_ser
 Code and Data Placements
 ------------------------
 
-ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through
+ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See :doc:`Linker Script Generation <linker-script-generation>` for a quick start guide as well as a detailed discussion of the mechanism.
-linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking
+
-app binary. See :doc:`Linker Script Generation <linker-script-generation>` for a quick start guide as well as a detailed discussion
+
-of the mechanism.
 
 Fully Overriding The Component Makefile
 ---------------------------------------
 
-Obviously, there are cases where all these recipes are insufficient for a
+Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the component is basically a wrapper around another third-party component not originally intended to be compiled under this build system. In that case, it's possible to forego the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and possibly  COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk`` target. The build target can do anything as long as it creates $(COMPONENT_LIBRARY) for the project make process to link into the app binary.
-certain component, for example when the component is basically a wrapper
-around another third-party component not originally intended to be
-compiled under this build system. In that case, it's possible to forego
-the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and
-possibly  COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk``
-target. The build target can do anything as long as it creates
-$(COMPONENT_LIBRARY) for the project make process to link into the app binary.
 
-(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable
+(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable is overridden then the component can instruct the linker to link other binaries instead.)
-is overridden then the component can instruct the linker to link other binaries instead.)
 
 .. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
 
@@ -631,7 +516,6 @@ For example projects or other projects where you don't want to specify a full sd
 
 To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
 
-
 Save flash arguments
 --------------------
 

docs/zh_CN/api-guides/build-system-legacy.rst

@@ -50,24 +50,23 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
 示例项目
 ~~~~~~~~
 
-示例项目的目录树结构可能如下所示：
+示例项目的目录树结构可能如下所示::
 
-.. code:: 
+    - myProject/
+                 - Makefile
+                 - sdkconfig
+                 - components/ - component1/ - component.mk
+                                             - Kconfig
+                                             - src1.c
+                               - component2/ - component.mk
+                                             - Kconfig
+                                             - src1.c
+                                             - include/ - component2.h
+                 - main/       - src1.c
+                               - src2.c
+                               - component.mk
 
-   - myProject/
+                 - build/
-                - Makefile
-                - sdkconfig
-                - components/ - component1/ - component.mk
-                                            - Kconfig
-                                            - src1.c
-                              - component2/ - component.mk
-                                            - Kconfig
-                                            - src1.c
-                                            - include/ - component2.h
-                - main/       - src1.c
-                              - src2.c
-                              - component.mk
-                - build/
 
 该示例项目 ``myProject`` 包含以下组成部分：
 
@@ -93,7 +92,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
 最小 Makefile 示例
 ^^^^^^^^^^^^^^^^^^
 
-.. code::
+::
 
    PROJECT_NAME := myProject
 
@@ -109,13 +108,13 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
 
 以下这些变量都有默认值，用户可以重写这些变量以自定义构建行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。
 
--  ``PROJECT_PATH``： 顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。
+-  ``PROJECT_PATH``：顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。
--  ``BUILD_DIR_BASE``： 所有对象、库、二进制文件的输出目录，默认为 ``$(PROJECT_PATH)/build``。
+-  ``BUILD_DIR_BASE``：所有对象、库、二进制文件的输出目录，默认为 ``$(PROJECT_PATH)/build``。
--  ``COMPONENT_DIRS``： 组件的搜索目录，默认为 ``$(IDF_PATH)/components``，``$(PROJECT_PATH)/components``，``$(PROJECT_PATH)/main`` 和 ``EXTRA_COMPONENT_DIRS`` 。如果您不希望从这些目录中搜索组件，请重写此变量。
+-  ``COMPONENT_DIRS``：组件的搜索目录，默认为 ``$(IDF_PATH)/components``，``$(PROJECT_PATH)/components``，``$(PROJECT_PATH)/main`` 和 ``EXTRA_COMPONENT_DIRS`` 。如果您不希望从这些目录中搜索组件，请重写此变量。
--  ``EXTRA_COMPONENT_DIRS``： 组件额外的搜索路径，可选。
+-  ``EXTRA_COMPONENT_DIRS``：组件额外的搜索路径，可选。
 -  ``COMPONENTS``： 要构建进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。
 -  ``EXCLUDE_COMPONENTS``： 在构建的过程中需要剔除的组件列表，可选。请注意这只会减少构建的时间，并不会减少最终二进制文件的大小。
--  ``TEST_EXCLUDE_COMPONENTS``： 在构建单元测试的过程中需要剔除的组件列表，可选。
+-  ``TEST_EXCLUDE_COMPONENTS``：在构建单元测试的过程中需要剔除的组件列表，可选。
 
 以上这些 Makefile 变量中的任何路径都要使用绝对路径，您可以使用 ``$(PROJECT_PATH)/xxx``，``$(IDF_PATH)/xxx``，或者使用 Make 内置函数 ``$(abspath xxx)`` 将相对路径转换为绝对路径。
 
@@ -179,6 +178,13 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
 -  ``HOSTCC``，``HOSTLD``，``HOSTAR``： 主机本地工具链中每个工具的全名。
 -  ``IDF_VER``： ESP-IDF 的版本号，可以通过检索 ``$(IDF_PATH)/version.txt`` 文件（假如存在的话）或者使用 git 命令 ``git describe`` 来获取。这里推荐的格式是在一行中指定主 IDF 的发布版本号，例如标记为 ``v2.0`` 的发布版本或者是标记任意一次提交记录的 ``v2.0-275-g0efaa4f``。应用程序可以通过调用 :cpp:func:`esp_get_idf_version` 函数来使用该变量。
 -  ``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`` 的值是不同的。
+- ``PROJECT_VER``：项目版本。
+
+  * 如果设置了 :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` 选项，则将使用 :ref:`CONFIG_APP_PROJECT_VER` 的值作为项目版本。
+  * 如果在项目 Makefile 文件中设置了 ``PROJECT_VER`` 变量，则使用该值作为项目版本。
+  * 如果存在 ``$PROJECT_PATH/version.txt``，则用其内容为 ``PROJECT_VER``。
+  * 如果项目位于 Git 仓库中，将使用 git 描述部分的内容作为项目版本。
+  * 如果以上均不存在，则 ``PROJECT_VER`` 为 "1"。
 
 如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。
 
@@ -214,12 +220,11 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
 -  ``CFLAGS``： 传递给 C 编译器的标志。根据项目设置已经定义一组默认的 ``CFLAGS``，可以通过 ``CFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
 -  ``CPPFLAGS``： 传递给 C 预处理器的标志（用于 ``.c``，``.cpp`` 和 ``.S`` 文件）。根据项目设置已经定义一组默认的 ``CPPFLAGS`` ，可以通过 ``CPPFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
 -  ``CXXFLAGS``： 传递给 C++ 编译器的标志。根据项目设置已经定义一组默认的 ``CXXFLAGS`` ，可以通过 ``CXXFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
+- ``COMPONENT_ADD_LDFRAGMENTS``: 链接器脚本生成功能的链接器片段文件的路径，请查看 :doc:`链接器脚本生成 <linker-script-generation>`.
 
-如果要将编译标志应用于单个源文件，您可以将该源文件的目标规则覆盖，例如：
+如果要将编译标志应用于单个源文件，您可以将该源文件的目标规则覆盖，例如::
 
-.. code:: makefile
+  apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
-
-    apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
 
 如果上游代码在编译的时候发出了警告，那这么做可能会很有效。
 
@@ -329,9 +334,7 @@ Makefile.projbuild
 
 请注意， ``Makefile.projbuild`` 对于最常见的组件不是必需的 - 例如向项目中添加 include 目录，或者将 LDFLAGS 添加到最终链接步骤，同样可以通过 ``component.mk`` 文件来自定义这些值。有关详细信息，请参阅 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ 。
 
-.. warning::
+在此文件中设置变量或者目标时要小心，由于这些值包含在项目的顶层 makefile 中，因此他们可以影响或者破坏所有组件的功能！
-
-	在此文件中设置变量或者目标时要小心，由于这些值包含在项目的顶层 makefile 中，因此他们可以影响或者破坏所有组件的功能！
 
 KConfig.projbuild
 ^^^^^^^^^^^^^^^^^
@@ -375,12 +378,10 @@ Makefile.componentbuild
 指定源文件
 ^^^^^^^^^^
 
-标准 ``component.mk`` 逻辑将源目录中的所有 .S 和 .c 文件添加为无条件编译的源。通过将 ``COMPONENT_OBJS`` 变量手动设置为需要生成的对象的名称，可以绕过该逻辑并对要编译的对象进行硬编码。
+标准 ``component.mk`` 逻辑将源目录中的所有 .S 和 .c 文件添加为无条件编译的源。通过将 ``COMPONENT_OBJS`` 变量手动设置为需要生成的对象的名称，可以绕过该逻辑并对要编译的对象进行硬编码::
 
-.. code:: 
+    COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
-
+    COMPONENT_SRCDIRS := . thing anotherthing
-   COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
-   COMPONENT_SRCDIRS := . thing anotherthing
 
 请注意，还需要另外设置 ``COMPONENT_SRCDIRS`` 。
 
@@ -391,56 +392,49 @@ Makefile.componentbuild
 
 配置系统可用于有条件地编译某些文件，具体取决于 ``make menuconfig`` 中选择的选项。为此，ESP-IDF 具有 ``compile_only_if`` 和 ``compile_only_if_not`` 的宏：
 
-``Kconfig``:
+``Kconfig``::
 
-.. code:: 
+    config FOO_ENABLE_BAR
+        bool "Enable the BAR feature."
+        help
+            This enables the BAR feature of the FOO component.
 
-   config FOO_ENABLE_BAR
+``component.mk``::
-       bool "Enable the BAR feature."
-       help
-           This enables the BAR feature of the FOO component.
 
-``component.mk``:
+    $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
-
-.. code:: 
-
-   $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
 
 从示例中可以看出， ``compile_only_if`` 宏将条件和目标文件列表作为参数。如果条件为真（在这种情况下：如果在 menuconfig 中启用了 BAR 功能），将始终编译目标文件（在本例中为 bar.o）。相反的情况也是如此，如果条件不成立，bar.o 将永远不会被编译。 ``compile_only_if_not`` 执行相反的操作，如果条件为 false 则编译，如果条件为 true 则不编译。
 
 这也可以用于选择或者删除实现，如下所示：
 
-``Kconfig``:
+``Kconfig``::
 
-.. code:: 
+    config ENABLE_LCD_OUTPUT
+        bool "Enable LCD output."
+        help
+            Select this if your board has a LCD.
 
-   config ENABLE_LCD_OUTPUT
+    config ENABLE_LCD_CONSOLE
-       bool "Enable LCD output."
+        bool "Output console text to LCD"
-       help
+        depends on ENABLE_LCD_OUTPUT
-           Select this if your board has a LCD.
+        help
+            Select this to output debugging output to the lcd
 
-   config ENABLE_LCD_CONSOLE
+    config ENABLE_LCD_PLOT
-       bool "Output console text to LCD"
+        bool "Output temperature plots to LCD"
-       depends on ENABLE_LCD_OUTPUT
+        depends on ENABLE_LCD_OUTPUT
-       help
+        help
-           Select this to output debugging output to the lcd
+            Select this to output temperature plots
 
-   config ENABLE_LCD_PLOT
-       bool "Output temperature plots to LCD"
-       depends on ENABLE_LCD_OUTPUT
-       help
-           Select this to output temperature plots
 
-``component.mk``:
+``component.mk``::
 
-.. code:: 
+    # If LCD is enabled, compile interface to it, otherwise compile dummy interface
+    $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
+    $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
 
-   # If LCD is enabled, compile interface to it, otherwise compile dummy interface
+    #We need font if either console or plot is enabled
-   $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
+    $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
-   $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
-
-   #We need font if either console or plot is enabled
-   $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
 
 请注意使用 Make 或者函数来包含字体文件。其他的替换函数，比如 ``and`` 和 ``if`` 也适用于此处。也可以使用不在 menuconfig 中定义的变量，ESP-IDF 使用默认的 Make 策略，将一个空的或者只包含空格的变量视为 false ，而其中任何非空格的比那辆都为 true 。
 
@@ -451,22 +445,22 @@ Makefile.componentbuild
 源代码生成
 ^^^^^^^^^^
 
-某些组件会出现源文件未随组件本身提供，而必须从另外一个文件生成的情况。假设我们的组件有一个头文件，该文件由 BMP 文件转换后的二进制数据组成，假设使用 bmp2h 的工具进行转换，然后将头文件包含在名为 graphics_lib.c 的文件中：
+某些组件会出现源文件未随组件本身提供，而必须从另外一个文件生成的情况。假设我们的组件有一个头文件，该文件由 BMP 文件转换后的二进制数据组成，假设使用 bmp2h 的工具进行转换，然后将头文件包含在名为 graphics_lib.c 的文件中::
 
-.. code:: 
+    COMPONENT_EXTRA_CLEAN := logo.h
 
-   COMPONENT_EXTRA_CLEAN := logo.h
+    graphics_lib.o: logo.h
 
-   graphics_lib.o: logo.h
+    logo.h: $(COMPONENT_PATH)/logo.bmp
-
+        bmp2h -i $^ -o $@
-   logo.h: $(COMPONENT_PATH)/logo.bmp
-       bmp2h -i $^ -o $@
 
 这个示例会在当前目录（构建目录）中生成 graphics_lib.o 和 logo.h 文件，而 logo.bmp 随组件一起提供并位于组件路径下。因为 logo.h 是一个生成的文件，所以当调用 ``make clean`` 时需要清理它，这就是为什么要将它添加到 ``COMPONENT_EXTRA_CLEAN`` 变量中。
 
 润色与改进
 ^^^^^^^^^^
 
+Because logo.h is a generated file, it needs to be cleaned when make clean is called which why it is added to the COMPONENT_EXTRA_CLEAN variable.
+
 将 logo.h 添加作为 ``graphics_lib.o`` 的依赖项会导致在编译 ``graphics_lib.c`` 之前先生成它。
 
 如果另一个组件中的源文件需要使用 logo.h，则必须将此组件的名称添加到另一个组件的 ``COMPONENT_DEPENDS`` 列表中，以确保组件按顺序编译。
@@ -476,28 +470,27 @@ Makefile.componentbuild
 
 有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它重新格式化为 C 源文件。
 
-这时，您可以在 ``component.mk`` 文件中设置变量 ``COMPONENT_EMBED_FILES``，以这种方式指定要嵌入的文件的名称：
+这时，您可以在 ``component.mk`` 文件中设置变量 ``COMPONENT_EMBED_FILES``，以这种方式指定要嵌入的文件的名称::
 
-.. code:: 
+  COMPONENT_EMBED_FILES := server_root_cert.der
 
-   COMPONENT_EMBED_FILES := server_root_cert.der
+或者，如果文件是字符串，则可以使用变量 ``COMPONENT_EMBED_TXTFILES``，这将把文本文件的内容当成以 null 结尾的字符串嵌入::
 
-或者，如果文件是字符串，则可以使用变量 ``COMPONENT_EMBED_TXTFILES``，这将把文本文件的内容当成以 null 结尾的字符串嵌入：
+  COMPONENT_EMBED_TXTFILES := server_root_cert.pem
 
-.. code:: 
+文件的内容会被编译进 flash 中的 .rodata 段，并通过符号名称来访问，如下所示::
 
-   COMPONENT_EMBED_TXTFILES := server_root_cert.pem
+  extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
-
+  extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
-文件的内容会被编译进 flash 中的 .rodata 段，并通过符号名称来访问，如下所示：
-
-.. code:: c
-
-   extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
-   extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
 
 符号名称是根据文件的全名生成的，如 ``COMPONENT_EMBED_FILES`` 中的所示，字符 / ， . ， 等都将会被下划线替代。符号名称中的 ``_binary`` 前缀由 ``objcopy`` 添加，对于文本和二进制文件都是相同的。
 
-有关使用此技术的示例，请参考 :example:`protocols/https_request` - 证书文件的内容会在编译时从 .pem 文件中加载。
+有关使用此技术的示例，请查看 file_serving 示例 :example_file:`protocols/http_server/file_serving/main/CMakeLists.txt` 中的 main 组件，两个文件会在编译时加载并链接到固件中。
+
+代码和数据的存放
+----------------
+
+ESP-IDF 还支持自动生成链接脚本，它允许组件通过链接片段文件定义其代码和数据在内存中的存放位置。构建系统会处理这些链接片段文件，并将处理后的结果扩充进链接脚本，从而指导应用程序二进制文件的链接过程。更多详细信息与快速上手指南，请参阅 :doc:`链接脚本生成机制 <linker-script-generation>`。
 
 .. _fully-overriding-component-makefile:
 
@@ -508,6 +501,12 @@ Makefile.componentbuild
 
 （实际上，这并不是必须的 - 如果 ``COMPONENT_ADD_LDFLAGS`` 变量被覆盖，那么组件可以指示链接器链接其他二进制文件。）
 
+.. note:: 当外部构建系统使用 PSRAM 时，请记得将 ``-mfix-esp32-psram-cache-issue`` 添加到 C 编译器的参数中。关于该标志的更多详细信息，请参考 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。
+
+.. _esp-idf-template: https://github.com/espressif/esp-idf-template
+.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
+
+
 .. _custom-sdkconfig-defaults-legacy:
 
 自定义 sdkconfig 的默认值
@@ -520,17 +519,13 @@ Makefile.componentbuild
 保存 flash 参数
 ~~~~~~~~~~~~~~~
 
-在某些情况下，我们希望在没有 IDF 的情况下烧写目标板卡，对于这种情况，我们希望保存构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以简单编写一段脚本来保存二进制文件和 esptool.py，并且使用命令 ``make print_flash_cmd`` 来查看烧写 flash 时的参数。
+在某些情况下，我们希望在没有 IDF 的情况下烧写目标板卡，对于这种情况，我们希望保存构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以简单编写一段脚本来保存二进制文件和 esptool.py，并且使用命令 ``make print_flash_cmd`` 来查看烧写 flash 时的参数::
 
-.. code:: bash
+    --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 
-   --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
+然后使用这段 flash 参数作为 esptool write_flash 命令的参数::
 
-然后使用这段 flash 参数作为 esptool write_flash 命令的参数：
+    python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
-
-.. code:: bash
-
-   python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 
 构建 Bootloader
 ---------------

docs/zh_CN/api-guides/build-system.rst

@@ -862,7 +862,7 @@ CMake 文件可以使用 ``IDF_TARGET`` 变量来获取当前的硬件目标。
 
 并将这行代码放在项目 CMakeLists.txt 的 ``project()`` 命令之后，修改 ``myproject.elf`` 为你自己的项目名。如果最后一个参数是 ``TEXT``，那么构建系统会嵌入以 null 结尾的字符串，如果最后一个参数被设置为 ``BINARY``，则将文件内容按照原样嵌入。
 
-有关使用此技术的示例，请参考 :example:`protocols/https_request`，证书文件的内容会在编译时从 .pem 文件中加载。
+有关使用此技术的示例，请查看 file_serving 示例 :example_file:`protocols/http_server/file_serving/main/CMakeLists.txt` 中的 main 组件，两个文件会在编译时加载并链接到固件中。
 
 
 .. highlight:: cmake
@@ -1007,6 +1007,7 @@ ESP-IDF 支持多款芯片，它们通过在软件中使用不同的 “目标
 
 * ``esp32`` — 适用于 ESP32-D0WD、ESP32-D2WD、ESP32-S0WD (ESP-SOLO)、ESP32-U4WDH、ESP32-PICO-D4
 * ``esp32s2``— 适用于 ESP32-S2
+* ``esp32c3``— 适用于 ESP32-C3
 
 在构建项目前，请首先根据您的芯片选择正确的软件目标，具体命令为 ``idf.py set-target <target>``。举例 ::