mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
zh_CN translation of build system (cmake version)
This commit is contained in:
Wang Fang
Ivan Grokhotkov
parent
48d3a5804d
commit
19939e5b60
@ -1,6 +1,7 @@
|
||||
Build System (CMake)
|
||||
********************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
.. include:: ../cmake-warning.rst
|
||||
|
||||
.. include:: ../cmake-pending-features.rst
|
||||
@ -161,7 +162,7 @@ When adding custom non-build steps like "flash" to the IDE, it is recommended to
|
||||
|
||||
For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_.
|
||||
|
||||
.. setting-python-interpreter:
|
||||
.. _setting-python-interpreter:
|
||||
|
||||
Setting the Python Interpreter
|
||||
------------------------------
|
||||
@ -232,7 +233,6 @@ Minimal Example CMakeLists
|
||||
Minimal project::
|
||||
|
||||
cmake_minimum_required(VERSION 3.5)
|
||||
|
||||
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
|
||||
project(myProject)
|
||||
|
||||
@ -242,9 +242,9 @@ Minimal project::
|
||||
Mandatory Parts
|
||||
---------------
|
||||
|
||||
The inclusion of these four lines, in the order shown above, is necessary for every project:
|
||||
The inclusion of these three lines, in the order shown above, is necessary for every project:
|
||||
|
||||
- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
|
||||
- ``cmake_minimum_required(VERSION 3.5)`` tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
|
||||
- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
|
||||
- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
|
||||
|
||||
@ -330,22 +330,22 @@ Preset Component Variables
|
||||
|
||||
The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
|
||||
|
||||
- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
|
||||
- ``COMPONENT_PATH``: 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_TARGET``: Name of the library target 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:
|
||||
|
||||
- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file.
|
||||
- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
|
||||
- ``PROJECT_PATH``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable.
|
||||
- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
|
||||
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
|
||||
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
|
||||
- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
|
||||
- ``IDF_TARGET``: Name of the target for which the project is being built.
|
||||
- ``PROJECT_VER``: Project version.
|
||||
|
||||
* If ``PROJECT_VER`` variable set in project CMakeLists.txt file, its value will be used.
|
||||
* Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
|
||||
* Else, if the ``${PROJECT_PATH}/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
|
||||
* Else, if the project is located inside a Git repository, the output of git describe will be used.
|
||||
* Otherwise, ``PROJECT_VER`` will be "1".
|
||||
|
||||
@ -367,7 +367,7 @@ If you modify any of these variables inside ``CMakeLists.txt`` then this will no
|
||||
Optional Component-Specific Variables
|
||||
-------------------------------------
|
||||
|
||||
The following variables can be set inside ``component.mk`` to control the build of that component:
|
||||
The following variables can be set inside ``CMakeLists.txt`` to control the build of that component:
|
||||
|
||||
- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
|
||||
the component directory, which will be added to the include search
|
||||
@ -426,8 +426,8 @@ Preprocessor Definitions
|
||||
|
||||
The ESP-IDF build system adds the following C preprocessor definitions on the command line:
|
||||
|
||||
- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
|
||||
- ``IDF_VER`` — Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
|
||||
- ``ESP_PLATFORM`` ： Can be used to detect that build happens within ESP-IDF.
|
||||
- ``IDF_VER`` ： Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
|
||||
- ``PROJECT_VER``: The project version, see `Preset Component Variables`_ for more details.
|
||||
- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file.
|
||||
|
||||
@ -458,6 +458,7 @@ When creating a project
|
||||
|
||||
- By default, every component is included in the build.
|
||||
- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
|
||||
|
||||
- Components mentioned explicitly in ``COMPONENTS``.
|
||||
- Those components' requirements (evaluated recursively).
|
||||
- The "common" components that every component depends on.
|
||||
@ -600,9 +601,9 @@ depending on the options selected in the project configuration.
|
||||
|
||||
if(CONFIG_FOO_ENABLE_BAR)
|
||||
list(APPEND COMPONENT_SRCS "bar.c")
|
||||
endif(CONFIG_FOO_ENABLE_BAR)
|
||||
endif()
|
||||
|
||||
This example makes use of the CMake `if function <cmake if_>`_ and `list APPEND <cmake list_>`_ function.
|
||||
This example makes use of the CMake `if <cmake if_>`_ function and `list APPEND <cmake list_>`_ function.
|
||||
|
||||
This can also be used to select or stub out an implementation, as such:
|
||||
|
||||
@ -722,8 +723,8 @@ For an example of using this technique, see :example:`protocols/https_request` -
|
||||
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
|
||||
linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking
|
||||
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.
|
||||
|
||||
@ -767,7 +768,7 @@ the ESP-IDF build system entirely by using a CMake feature called ExternalProjec
|
||||
(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
|
||||
|
||||
- ``externalproject_add`` defines an external build system.
|
||||
|
||||
|
||||
- ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
|
||||
- Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
|
||||
- Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
|
||||
@ -875,7 +876,7 @@ Using Third-Party CMake Projects with Components
|
||||
================================================
|
||||
|
||||
CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system
|
||||
is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may
|
||||
is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may
|
||||
not yet be provided by a component, or use another library for the same functionality.
|
||||
|
||||
.. highlight:: cmake
|
||||
@ -888,7 +889,7 @@ Importing a library might look like this for a hypothetical library ``foo`` to b
|
||||
# Set values of hypothetical variables that control the build of `foo`
|
||||
set(FOO_BUILD_STATIC OFF)
|
||||
set(FOO_BUILD_TESTS OFF)
|
||||
|
||||
|
||||
# Create and import the library targets
|
||||
add_subdirectory(foo)
|
||||
|
||||
@ -904,7 +905,7 @@ For an actual example, take a look at :example:`build_system/cmake/import_lib`.
|
||||
the library may vary. It is recommended to read up on the library's documentation for instructions on how to
|
||||
import it from other projects. Studying the library's CMakeLists.txt and build structure can also be helpful.
|
||||
|
||||
It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for
|
||||
It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for
|
||||
Espressif's fork of `mbedtls <https://github.com/ARMmbed/mbedtls>`_. See its :component_file:`component CMakeLists.txt <mbedtls/CMakeLists.txt>`.
|
||||
|
||||
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.
|
||||
@ -915,7 +916,7 @@ Using ESP-IDF in Custom CMake Projects
|
||||
|
||||
ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already
|
||||
have an existing CMake project or may want to create one. In these cases it is desirable to be able to consume IDF components
|
||||
as libraries to be linked to the user's targets (libraries/ executables).
|
||||
as libraries to be linked to the user's targets (libraries/ executables).
|
||||
|
||||
.. highlight:: cmake
|
||||
|
||||
@ -957,7 +958,7 @@ parameters which can be set, the full list of which is as follows:
|
||||
- ``IDF_COMPONENT_REQUIRES_COMMON``: List of components that every component requires. Components in this list (and their dependencies) are imported regardless of the value of ``IDF_COMPONENTS``. By default, this variable is set to the minimal set of core "system" components.
|
||||
- ``IDF_SDKCONFIG_DEFAULTS``: Path to the configuration override file. If unset, components are built with default configurations.
|
||||
- ``IDF_BUILD_TESTS``: Include component tests in the build. By default, all component tests are included. The component tests are filtered using ``IDF_TEST_COMPONENTS`` and ``IDF_TEST_EXCLUDE_COMPONENTS``.
|
||||
- ``IDF_TEST_COMPONENTS``: If ``IDF_BUILD_TESTS`` is set, only component tests in this list will be included in the build. Ignored if ``IDF_BUILD_TESTS`` is not set.
|
||||
- ``IDF_TEST_COMPONENTS``: If ``IDF_BUILD_TESTS`` is set, only component tests in this list will be included in the build. Ignored if ``IDF_BUILD_TESTS`` is not set.
|
||||
- ``IDF_TEST_EXCLUDE_COMPONENTS``: If ``IDF_BUILD_TESTS`` is set, component tests in this list will not be included in the build. Ignored if ``IDF_BUILD_TESTS`` is not set. This variable takes precedence over ``IDF_TEST_COMPONENTS``. This means that a component test in this list will not be included in the build even if it is also present in ``IDF_TEST_COMPONENTS``.
|
||||
|
||||
The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application <get-started/hello_world>`
|
||||
@ -980,7 +981,7 @@ This preference reflects the `CMake best practice <https://gist.github.com/mbinn
|
||||
|
||||
set(COMPONENT_SRCDIRS library platform)
|
||||
|
||||
This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build.
|
||||
This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build.
|
||||
|
||||
The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
|
||||
|
||||
@ -1127,7 +1128,7 @@ Flashing from make
|
||||
.. _esptool.py: https://github.com/espressif/esptool/#readme
|
||||
.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html
|
||||
.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
|
||||
.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/project.html
|
||||
.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html
|
||||
.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html
|
||||
.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html
|
||||
.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html
|
||||
@ -1144,4 +1145,3 @@ Flashing from make
|
||||
.. _quirc: https://github.com/dlbeer/quirc
|
||||
.. _pyenv: https://github.com/pyenv/pyenv#README
|
||||
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,17 +1,17 @@
|
||||
编译系统
|
||||
构建系统
|
||||
========
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文将介绍乐鑫物联网开发框架中的``编译系统``和``组件``的相关概念。
|
||||
本文将介绍乐鑫物联网开发框架中的 ``构建系统`` 和 ``组件`` 的相关概念。
|
||||
|
||||
如果您想了解如何构建一个新的 ESP-IDF 项目，请阅读本文档。
|
||||
|
||||
我们建议您使用 `ESP-IDF 模板工程 <https://github.com/espressif/esp-idf-template>`_ 来开始您的新项目。
|
||||
|
||||
使用编译系统
|
||||
使用构建系统
|
||||
------------
|
||||
|
||||
ESP-IDF 的 :idf_file:`README.md` 文件对如何使用编译系统来构建项目作了简要的说明。
|
||||
ESP-IDF 的 :idf_file:`README.md` 文件对如何使用构建系统来构建项目作了简要的说明。
|
||||
|
||||
概述
|
||||
----
|
||||
@ -26,7 +26,7 @@ ESP-IDF 的 :idf_file:`README.md` 文件对如何使用编译系统来构建项
|
||||
- 湿度传感器的驱动
|
||||
- 将上述组件组织在一起的主代码
|
||||
|
||||
ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，编译系统会查找 ESP-IDF 目录、项目目录和用户自定义目录（可选）中所有的组件，然后使用基于文本的菜单系统让用户配置 ESP-IDF 项目中需要的每个组件。在配置结束后，编译系统开始编译整个项目。
|
||||
ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会查找 ESP-IDF 目录、项目目录和用户自定义目录（可选）中所有的组件，然后使用基于文本的菜单系统让用户配置 ESP-IDF 项目中需要的每个组件。在配置结束后，构建系统开始编译整个项目。
|
||||
|
||||
概念
|
||||
~~~~
|
||||
@ -65,12 +65,11 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
|
||||
- main/ - src1.c
|
||||
- src2.c
|
||||
- component.mk
|
||||
|
||||
- build/
|
||||
|
||||
该示例项目 ``myProject`` 包含以下组成部分：
|
||||
|
||||
- 项目顶层 Makefile，该 Makefile 设置了 ``PROJECT_NAME`` 变量，还可以定义作用于整个项目的其它 make 变量（可选）。顶层 Makefile 会导入核心 Makefile 文件 ``$(IDF_PATH)/make/project.mk`` ，由它负责实现 ESP-IDF 编译系统的剩余部分。
|
||||
- 项目顶层 Makefile，该 Makefile 设置了 ``PROJECT_NAME`` 变量，还可以定义作用于整个项目的其它 make 变量（可选）。顶层 Makefile 会导入核心 Makefile 文件 ``$(IDF_PATH)/make/project.mk`` ，由它负责实现 ESP-IDF 构建系统的剩余部分。
|
||||
|
||||
- 项目配置文件 sdkconfig，执行 ``make menuconfig`` 后会创建或更新此文件，该文件中保存了项目中所有组件的配置信息（包括 ESP-IDF 本身）。``sdkconfig`` 文件可能会也可能不会被添加到项目的源代码管理系统中。
|
||||
|
||||
@ -78,9 +77,9 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
|
||||
|
||||
- ``main`` 目录是一个特殊的 ``伪组件``，它包含项目本身的源代码。``main`` 是默认名称，Makefile 变量 ``COMPONENT_DIRS`` 默认会导入此组件，但您也可以修改此变量（或者设置 ``EXTRA_COMPONENT_DIRS`` ）以查找其他位置的组件。
|
||||
|
||||
- ``build`` 目录在项目编译的时候创建或者更新，里面包含有编译生成的临时目标文件和库以及最终输出的二进制文件。此目录通常不会被添加到项目的源代码管理系统中，也不会随着项目源代码被发布。
|
||||
- ``build`` 目录在项目构建的时候创建或者更新，里面包含有构建生成的临时目标文件和库以及最终输出的二进制文件。此目录通常不会被添加到项目的源代码管理系统中，也不会随着项目源代码被发布。
|
||||
|
||||
组件目录中会包含组件自己的 Makefile 文件 ``component.mk`` ，里面会定义一些变量来控制该组件的编译过程，以及它与整个项目的集成。更多详细信息请参考 `组件 Makefiles <#component-makefiles>`_。
|
||||
组件目录中会包含组件自己的 Makefile 文件 ``component.mk`` ，里面会定义一些变量来控制该组件的构建过程，以及它与整个项目的集成。更多详细信息请参考 `组件 Makefiles <#component-makefiles>`_。
|
||||
|
||||
每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的组件配置信息的选项规则。某些组件还可能还会包含 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 特殊文件，他们可以用来覆盖项目的部分配置。
|
||||
|
||||
@ -106,15 +105,15 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
|
||||
可选的项目变量
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
以下这些变量都有默认值，用户可以重写这些变量以自定义编译行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。
|
||||
以下这些变量都有默认值，用户可以重写这些变量以自定义构建行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。
|
||||
|
||||
- ``PROJECT_PATH``： 顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。
|
||||
- ``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``： 组件额外的搜索路径，可选。
|
||||
- ``COMPONENTS``： 要编译进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。
|
||||
- ``EXCLUDE_COMPONENTS``： 在编译的过程中需要剔除的组件列表，可选。请注意这只会减少编译的时间，并不会减少最终二进制文件的大小。
|
||||
- ``TEST_EXCLUDE_COMPONENTS``： 在单元测试的编译过程中需要剔除的组件列表，可选。
|
||||
- ``COMPONENTS``： 要构建进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。
|
||||
- ``EXCLUDE_COMPONENTS``： 在构建的过程中需要剔除的组件列表，可选。请注意这只会减少构建的时间，并不会减少最终二进制文件的大小。
|
||||
- ``TEST_EXCLUDE_COMPONENTS``： 在构建单元测试的过程中需要剔除的组件列表，可选。
|
||||
|
||||
以上这些 Makefile 变量中的任何路径都要使用绝对路径，您可以使用 ``$(PROJECT_PATH)/xxx``，``$(IDF_PATH)/xxx``，或者使用 Make 内置函数 ``$(abspath xxx)`` 将相对路径转换为绝对路径。
|
||||
|
||||
@ -136,8 +135,8 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
|
||||
|
||||
运行 ``make list-components`` 命令可以查询这些变量的值，这有助于调试组件的搜索路径是否正确。
|
||||
|
||||
具有相同名字的多个组件
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
同名组件
|
||||
^^^^^^^^
|
||||
|
||||
ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先是 ESP-IDF 组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改来覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。
|
||||
|
||||
@ -146,7 +145,7 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
|
||||
最小组件 Makefile
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
最简单的 ``component.mk`` 文件可以是一个空文件，如果文件为空，则组件的默认编译行为会被设置为：
|
||||
最简单的 ``component.mk`` 文件可以是一个空文件，如果文件为空，则组件的默认构建行为会被设置为：
|
||||
|
||||
- makefile 所在目录中的所有源文件（``*.c``，``*.cpp``，``*.cc``，``*.S``）将会被编译进组件库中。
|
||||
- 子目录 ``include`` 将被添加到其他组件的全局头文件搜索路径中。
|
||||
@ -154,7 +153,7 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
|
||||
|
||||
更完整的组件 makefile 可以查看 `组件 Makefile 示例 <#example-component-makefile>`_。
|
||||
|
||||
请注意，空的 ``component.mk`` 文件同没有 ``component.mk`` 文件之间存在本质差异，前者会调用默认的组件编译行为，后者不会发生默认的组件编译行为。一个组件中如果只包含影响项目配置或编译过程的文件，那么它可以没有 ``component.mk`` 文件。
|
||||
请注意，空的 ``component.mk`` 文件同没有 ``component.mk`` 文件之间存在本质差异，前者会调用默认的组件构建行为，后者不会发生默认的组件构建行为。一个组件中如果只包含影响项目配置或构建过程的文件，那么它可以没有 ``component.mk`` 文件。
|
||||
|
||||
.. _preset-component-variables:
|
||||
|
||||
@ -165,50 +164,50 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
|
||||
|
||||
- ``COMPONENT_PATH``： 组件的目录，即包含 ``component.mk`` 文件的绝对路径，路径中不能包含空格。
|
||||
- ``COMPONENT_NAME``： 组件的名字，默认为组件目录的名称。
|
||||
- ``COMPONENT_BUILD_DIR``： 组件的编译目录，即存放组件编译输出的绝对路径，它是 `$(BUILD_DIR_BASE)` 的子目录。该变量也是编译组件时的当前工作目录，所以 make 中的相对路径都以此目录为基础。
|
||||
- ``COMPONENT_LIBRARY``： 组件编译后的静态库文件（相对于组件的编译目录）的名字，默认为 ``$(COMPONENT_NAME).a``。
|
||||
- ``COMPONENT_BUILD_DIR``： 组件的构建目录，即存放组件构建输出的绝对路径，它是 `$(BUILD_DIR_BASE)` 的子目录。该变量也是构建组件时的当前工作目录，所以 make 中的相对路径都以此目录为基础。
|
||||
- ``COMPONENT_LIBRARY``： 组件构建后的静态库文件（相对于组件的构建目录）的名字，默认为 ``$(COMPONENT_NAME).a``。
|
||||
|
||||
以下变量在项目顶层中设置，并被导出到组件中编译时使用：
|
||||
以下变量在项目顶层中设置，并被导出到组件中构建时使用：
|
||||
|
||||
- ``PROJECT_NAME``： 项目名称，在项目的 Makefile 中设置。
|
||||
- ``PROJECT_PATH``： 包含项目 Makefile 的目录的绝对路径。
|
||||
- ``COMPONENTS``： 此次编译中包含的所有组件的名字。
|
||||
- ``COMPONENTS``： 此次构建中包含的所有组件的名字。
|
||||
- ``CONFIG_*``： 项目配置中的每个值在 make 中都对应一个以 ``CONFIG_`` 开头的变量。
|
||||
- ``CC``，``LD``，``AR``，``OBJCOPY``： gcc xtensa 交叉编译工具链中每个工具的完整路径。
|
||||
- ``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` 函数来使用该变量。
|
||||
|
||||
如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的编译，但可能会使您的组件变得难以编译或调试。
|
||||
如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。
|
||||
|
||||
.. _optional-project-wide-component-variables:
|
||||
|
||||
可选的项目通用组件变量
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
可以在 ``component.mk`` 中设置以下变量来控制整个项目的编译行为：
|
||||
可以在 ``component.mk`` 中设置以下变量来控制整个项目的构建行为：
|
||||
|
||||
- ``COMPONENT_ADD_INCLUDEDIRS``： 相对于组件目录的路径，将被添加到项目中所有组件的头文件搜索路径中。如果该变量未被覆盖，则默认为 ``include`` 目录。如果一个头文件路径仅仅为当前组件所用，那么应该将该路径添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。
|
||||
- ``COMPONENT_ADD_LDFLAGS``： 添加链接参数到全局 ``LDFLAGS`` 中用以指导链接最终的可执行文件，默认为 ``-l$(COMPONENT_NAME)``。如果将预编译好的库添加到此目录，请使用它们为绝对路径，即 ``$(COMPONENT_PATH)/libwhatever.a``。
|
||||
- ``COMPONENT_DEPENDS``： 需要在当前组件之前编译的组件列表，这对于处理链接时的依赖不是必需的，因为所有组件的头文件目录始终可用。如果一个组件会生成一个头文件，然后另外一个组件需要使用它，此时该变量就有必要进行设置。大多数的组件不需要设置此变量。
|
||||
- ``COMPONENT_DEPENDS``： 需要在当前组件之前构建的组件列表，这对于处理链接时的依赖不是必需的，因为所有组件的头文件目录始终可用。如果一个组件会生成一个头文件，然后另外一个组件需要使用它，此时该变量就有必要进行设置。大多数的组件不需要设置此变量。
|
||||
- ``COMPONENT_ADD_LINKER_DEPS``： 保存一些文件的路径，当这些文件发生改变时，会触发 ELF 文件重新链接。该变量通常用于链接脚本文件和二进制文件，大多数的组件不需要设置此变量。
|
||||
|
||||
以下变量仅适用于属于 ESP-IDF 的组件：
|
||||
|
||||
- ``COMPONENT_SUBMODULES``： 组件使用的 git 子模块的路径列表（相对于 ``COMPONENT_PATH``）。这些路径会在编译的过程中被检查（并在必要的时候初始化）。如果组件位于 ``IDF_PATH`` 目录之外，则忽略此变量。
|
||||
- ``COMPONENT_SUBMODULES``： 组件使用的 git 子模块的路径列表（相对于 ``COMPONENT_PATH``）。这些路径会在构建的过程中被检查（并在必要的时候初始化）。如果组件位于 ``IDF_PATH`` 目录之外，则忽略此变量。
|
||||
|
||||
|
||||
可选的组件特定变量
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
以下变量可以在 ``component.mk`` 中进行设置，用以控制该组件的编译行为：
|
||||
以下变量可以在 ``component.mk`` 中进行设置，用以控制该组件的构建行为：
|
||||
|
||||
- ``COMPONENT_PRIV_INCLUDEDIRS``： 相对于组件目录的目录路径，该目录仅会被添加到该组件源文件的头文件搜索路径中。
|
||||
- ``COMPONENT_EXTRA_INCLUDES``： 编译组件的源文件时需要指定的额外的头文件搜索路径，这些路径将以 ``-l`` 为前缀传递给编译器。这和 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的功能有些类似，但是这些路径不会相对于组件目录进行扩展。
|
||||
- ``COMPONENT_SRCDIRS``： 相对于组件目录的目录路径，这些路径用于搜索源文件（``*.cpp``，``*.c``，``*.S``），默认为 ``.``，即组件目录本身。重写该变量可以指定包含源文件的不同目录列表。
|
||||
- ``COMPONENT_OBJS``： 要编译生成的目标文件，默认是 ``COMPONENT_SRCDIRS`` 中每个源文件的 .o 文件。重写该变量将允许您剔除 ``COMPONENT_SRCDIRS`` 中的某些源文件，否则他们将会被编译。相关示例请参阅 `指定需要编译的组件源文件 <#specify-source-files>`_。
|
||||
- ``COMPONENT_EXTRA_CLEAN``： 相对于组件编译目录的路径，指向 ``component.mk`` 文件中自定义 make 规则生成的任何文件，它们也是 ``make clean`` 命令需要删除的文件。相关示例请参阅 `源代码生成 <#source-code-generation>`_。
|
||||
- ``COMPONENT_EXTRA_CLEAN``： 相对于组件构建目录的路径，指向 ``component.mk`` 文件中自定义 make 规则生成的任何文件，它们也是 ``make clean`` 命令需要删除的文件。相关示例请参阅 `源代码生成 <#source-code-generation>`_。
|
||||
- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``： 这些目标允许您完全覆盖组件的默认编译行为。有关详细信息，请参阅 `完全覆盖组件的 Makefile <#fully-overriding-component-makefile>`_。
|
||||
- ``COMPONENT_CONFIG_ONLY``： 如果设置了此标志，则表示组件根本不会产生编译输出（即不会编译得到 ``COMPONENT_LIBRARY``），并且会忽略大多数其它组件变量。此标志用于 IDF 内部组件，其中仅包含 ``KConfig.projbuild`` 和/或 ``Makefile.projbuild`` 文件来配置项目，但是没有源文件。
|
||||
- ``COMPONENT_CONFIG_ONLY``： 如果设置了此标志，则表示组件根本不会产生构建输出（即不会构建得到 ``COMPONENT_LIBRARY``），并且会忽略大多数其它组件变量。此标志用于 IDF 内部组件，其中仅包含 ``KConfig.projbuild`` 和/或 ``Makefile.projbuild`` 文件来配置项目，但是没有源文件。
|
||||
- ``CFLAGS``： 传递给 C 编译器的标志。根据项目设置已经定义一组默认的 ``CFLAGS``，可以通过 ``CFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
|
||||
- ``CPPFLAGS``： 传递给 C 预处理器的标志（用于 ``.c``，``.cpp`` 和 ``.S`` 文件）。根据项目设置已经定义一组默认的 ``CPPFLAGS`` ，可以通过 ``CPPFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
|
||||
- ``CXXFLAGS``： 传递给 C++ 编译器的标志。根据项目设置已经定义一组默认的 ``CXXFLAGS`` ，可以通过 ``CXXFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
|
||||
@ -217,7 +216,7 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
|
||||
|
||||
.. code:: makefile
|
||||
|
||||
apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
|
||||
apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
|
||||
|
||||
如果上游代码在编译的时候发出了警告，那这么做可能会很有效。
|
||||
|
||||
@ -235,12 +234,12 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
|
||||
预处理器定义
|
||||
~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 编译系统会在命令行中添加以下 C 预处理定义：
|
||||
ESP-IDF 构建系统会在命令行中添加以下 C 预处理定义：
|
||||
|
||||
- ``ESP_PLATFORM`` — 可以用来检测在 ESP-IDF 内发生的编译行为。
|
||||
- ``ESP_PLATFORM`` — 可以用来检测在 ESP-IDF 内发生的构建行为。
|
||||
- ``IDF_VER`` — ESP-IDF 的版本，请参阅 `预设的组件变量 <#preset-component-variables>`_。
|
||||
|
||||
编译的内部过程
|
||||
构建的内部过程
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
顶层：项目 Makefile
|
||||
@ -286,14 +285,14 @@ ESP-IDF 编译系统会在命令行中添加以下 C 预处理定义：
|
||||
构建目标的进阶用法
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``make app``，``make bootloader``，``make partition table`` 可以根据需要为项目单独编译生成应用程序文件、启动引导文件和分区表文件。
|
||||
- ``make app``，``make bootloader``，``make partition table`` 可以根据需要为项目单独构建生成应用程序文件、启动引导文件和分区表文件。
|
||||
- ``make erase_flash`` 和 ``make erase_ota`` 会调用 esptool.py 脚本分别擦除整块闪存芯片或者其中 OTA 分区的内容。
|
||||
- ``make size`` 会打印应用程序的大小信息。``make size-components`` 和 ``make size-files`` 两者功能相似，分别打印每个组件或者每个源文件大小的详细信息。
|
||||
|
||||
调试 Make 的过程
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
调试 ESP-IDF 编译系统的一些技巧：
|
||||
调试 ESP-IDF 构建系统的一些技巧：
|
||||
|
||||
- 将 ``V=1`` 添加到 make 的参数中（或将其设置为环境变量）将使 make 回显所有已经执行的命令，以及为子 make 输入的每个目录。
|
||||
- 运行 ``make -w`` 将导致 make 在为子 make 输入时回显每个目录——与 ``V=1`` 相同但不回显所有命令。
|
||||
@ -360,13 +359,13 @@ Makefile.componentbuild
|
||||
增加源文件目录
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
默认情况下，将忽略子目录。如果您的项目在子目录中而不是在组件的根目录中有源文件，那么您可以通过设置 ``COMPONENT_SRCDIRS`` 将其告知编译系统：
|
||||
默认情况下，将忽略子目录。如果您的项目在子目录中而不是在组件的根目录中有源文件，那么您可以通过设置 ``COMPONENT_SRCDIRS`` 将其告知构建系统：
|
||||
|
||||
.. code::
|
||||
|
||||
COMPONENT_SRCDIRS := src1 src2
|
||||
|
||||
编译系统将会编译 src1/ 和 src2/ 子目录中的所有源文件。
|
||||
构建系统将会编译 src1/ 和 src2/ 子目录中的所有源文件。
|
||||
|
||||
.. _specify-source-files:
|
||||
|
||||
@ -502,7 +501,7 @@ Makefile.componentbuild
|
||||
完全覆盖组件的 Makefile
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
显然，在某些情况下，所有这些配置都不足以满足某个组件，例如，当组件基本上是另一个第三方组件的包装器时，该第三方组件最初不打算在 ESP-IDF 编译系统下工作，在这种情况下，可以通过设置 ``COMPONENT_OWNBUILDTARGET`` 和可能的 ``COMPONENT_OWNCLEANTARGET``，并在 ``component.mk`` 中定义名为 ``build`` 和 ``clean`` 的目标。构建目标可以执行任何操作，只要它为项目生成了 ``$(COMPONENT_LIBRARY)`` ，并最终被链接到应用程序二进制文件中即可。
|
||||
显然，在某些情况下，所有这些配置都不足以满足某个组件，例如，当组件基本上是另一个第三方组件的包装器时，该第三方组件最初不打算在 ESP-IDF 构建系统下工作，在这种情况下，可以通过设置 ``COMPONENT_OWNBUILDTARGET`` 和可能的 ``COMPONENT_OWNCLEANTARGET``，并在 ``component.mk`` 中定义名为 ``build`` 和 ``clean`` 的目标。构建目标可以执行任何操作，只要它为项目生成了 ``$(COMPONENT_LIBRARY)`` ，并最终被链接到应用程序二进制文件中即可。
|
||||
|
||||
（实际上，这并不是必须的 - 如果 ``COMPONENT_ADD_LDFLAGS`` 变量被覆盖，那么组件可以指示链接器链接其他二进制文件。）
|
||||
|
||||
@ -530,10 +529,10 @@ Makefile.componentbuild
|
||||
|
||||
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
|
||||
构建 Bootloader
|
||||
---------------
|
||||
|
||||
引导程序默认作为 ``make all`` 的一部分被编译，或者也可以通过 ``make bootloader-clean`` 来独立构建，此外还可以通过 ``make bootloader-list-components`` 来查看构建引导程序时包含的组件。
|
||||
引导程序默认作为 ``make all`` 的一部分被构建，或者也可以通过 ``make bootloader-clean`` 来单独构建，此外还可以通过 ``make bootloader-list-components`` 来查看构建引导程序时包含的组件。
|
||||
|
||||
引导程序是一个特殊的组件，因为主项目中的二级引导程序拥有单独的 .EFL 和 .BIN 文件。但是它与主项目共享配置和构建目录。
|
||||
|
||||
|
||||
@ -6,8 +6,8 @@ API 指南
|
||||
:maxdepth: 1
|
||||
|
||||
一般注意事项 <general-notes>
|
||||
编译系统 <build-system>
|
||||
编译系统 (CMake) <build-system-cmake>
|
||||
构建系统 <build-system>
|
||||
构建系统 (CMake) <build-system-cmake>
|
||||
错误处理 <error-handling>
|
||||
Fatal Errors <fatal-errors>
|
||||
Deep Sleep Wake Stubs <deep-sleep-stub>
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
.. important::
|
||||
目前，CMake 编译系统尚不支持以下功能：
|
||||
目前，CMake 编译系统尚不支持以下功能：
|
||||
|
||||
- Eclipse IDE 文档
|
||||
- 安全启动
|
||||
- Flash 加密
|
||||
- Eclipse IDE 文档
|
||||
- 安全启动
|
||||
- Flash 加密
|
||||
|
||||
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后取代现有基于 GNU Make 的编译系统，成为默认编译系统。我们会在 ESP-IDF v4.0 发布前逐步完善上述功能。
|
||||
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后取代现有基于 GNU Make 的编译系统，成为默认编译系统。我们会在 ESP-IDF v4.0 发布前逐步完善上述功能。
|
||||
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. note::
|
||||
本文档介绍了 CMake 编译系统的使用。目前，CMake 编译系统仍处于预览发布阶段，如您在使用中遇到任何问题，请前往 ESP-IDF 提交 `Issues <https://github.com/espressif/esp-idf/issues>`_。
|
||||
本文档将介绍如何使用 CMake 编译系统。目前，CMake 编译系统仍处于预览发布阶段，如您在使用中遇到任何问题，请前往 ESP-IDF 提交 `Issues <https://github.com/espressif/esp-idf/issues>`_。
|
||||
|
||||
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后过渡为默认编译系统，现行基于 GNU Make 的编译系统将在 ESP-IDF v5.0 后弃用。
|
||||
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后过渡为默认编译系统，现行基于 GNU Make 的编译系统将在 ESP-IDF v5.0 后弃用。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user