From 90ca881dab56fd7aac27f1890d8a7111ed968a09 Mon Sep 17 00:00:00 2001 From: Frantisek Hrbata Date: Mon, 6 Jan 2025 11:12:17 +0100 Subject: [PATCH 1/2] docs: improve minimal build documentation Follow-up improvements to the minimal build documentation. Signed-off-by: Frantisek Hrbata --- docs/en/api-guides/build-system.rst | 8 +++----- docs/en/api-guides/core_dump.rst | 2 +- docs/en/api-guides/external-ram.rst | 2 +- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index a2469d325d..433d18f7b5 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -615,15 +615,13 @@ Including Components in the Build - Components mentioned explicitly in ``COMPONENTS``. - Those components' requirements (evaluated recursively). - - The "common" components that every component depends on. + - The :ref:`common components ` that every component depends on. - Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times. -- The ``MINIMAL_BUILD`` :ref:`build property ` can be set to ``ON``, which acts as a shortcut to configure the ``COMPONENTS`` variable to include only the ``main`` component. If the ``COMPONENTS`` variable is defined while the ``MINIMAL_BUILD`` property is enabled, ``COMPONENTS`` will take precedence. +- The ``MINIMAL_BUILD`` :ref:`build property ` can be set to ``ON``, which acts as a shortcut to configure the ``COMPONENTS`` variable to include only the ``main`` component. This means that the build will include only the :ref:`common components `, the ``main`` component, and all dependencies associated with it, both direct and indirect. If the ``COMPONENTS`` variable is defined while the ``MINIMAL_BUILD`` property is enabled, ``COMPONENTS`` will take precedence. .. note:: - - When using the ``COMPONENTS`` variable or the ``MINIMAL_BUILD`` build property to specify components, certain features and configurations, such as those provided by esp_psram or espcoredump components, may not be included by default. To include these features, you must add the relevant components to the ``COMPONENTS`` variable or list them in the ``REQUIRES`` or ``PRIV_REQUIRES`` argument during component registration. - + Certain features and configurations, such as those provided by esp_psram or espcoredump components, may not be available to your project by default if the minimal list of components is used. When using the ``COMPONENTS`` variable, ensure that all necessary components are included. Similarly, when using the ``MINIMAL_BUILD`` build property, ensure that all required components are specified in the ``REQUIRES`` or ``PRIV_REQUIRES`` argument during component registration. .. _component-circular-dependencies: diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 3ecd93c046..7f8e6819f1 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -17,7 +17,7 @@ Configurations -------------- .. note:: - The ``Core dump`` configuration options are available only if the ``espcoredump`` component is included in the build. + The ``Core dump`` configuration options are available only if the ``espcoredump`` component is included in the build. To include ``Core dump`` into your project, add the ``espcoredump`` component as a dependency in either REQUIRES or PRIV_REQUIRES when registering your component with ``idf_component_register``. Destination ^^^^^^^^^^^ diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 9ecd2ad8da..55c52d502d 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -47,7 +47,7 @@ Configuring External RAM ======================== .. note:: - The ``SPI RAM`` configuration options are available only if the ``esp_psram`` component is included in the build. + The ``SPI RAM`` configuration options are available only if the ``esp_psram`` component is included in the build. To include ``SPI RAM`` into your project, add the ``esp_psram`` component as a dependency in either REQUIRES or PRIV_REQUIRES when registering your component with ``idf_component_register``. ESP-IDF fully supports the use of external RAM in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to integrate the external RAM in several ways: From a6fdc2677e76af233c5c2708c86784c22e901d0d Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Thu, 9 Jan 2025 11:54:52 +0800 Subject: [PATCH 2/2] docs: Update CN translation for minimal build documentation --- docs/en/api-guides/build-system.rst | 22 +++++++++++----------- docs/en/api-guides/core_dump.rst | 3 ++- docs/en/api-guides/external-ram.rst | 3 ++- docs/zh_CN/api-guides/build-system.rst | 26 ++++++++++++-------------- docs/zh_CN/api-guides/core_dump.rst | 3 ++- docs/zh_CN/api-guides/external-ram.rst | 5 +++-- 6 files changed, 32 insertions(+), 30 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 433d18f7b5..7a78291add 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -25,19 +25,19 @@ ESP-IDF makes these components explicit and configurable. To do that, when a pro Concepts -------- -- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader. +- A ``project`` is a directory that contains all the files and configuration to build a single ``app`` (executable), as well as additional supporting elements such as a partition table, data partitions or filesystem partitions, and a bootloader. -- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customize the configuration of the project. A single project contains exactly one project configuration. +- ``Project configuration`` is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customize the configuration of the project. A single project contains exactly one project configuration. -- An "app" is an executable that is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). +- An ``app`` is an executable that is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). -- "components" are modular pieces of standalone code that are compiled into static libraries (.a files) and linked to an app. Some are provided by ESP-IDF itself, others may be sourced from other places. +- ``Components`` are modular pieces of standalone code that are compiled into static libraries (.a files) and linked to an app. Some are provided by ESP-IDF itself, others may be sourced from other places. -- "Target" is the hardware for which an application is built. A full list of supported targets in your version of ESP-IDF can be seen by running `idf.py --list-targets`. +- ``Target`` is the hardware for which an application is built. A full list of supported targets in your version of ESP-IDF can be seen by running `idf.py --list-targets`. Some things are not part of the project: -- "ESP-IDF" is not part of the project. Instead, it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the ESP-IDF framework to be decoupled from your project. +- ``ESP-IDF`` is not part of the project. Instead, it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the ESP-IDF framework to be decoupled from your project. - The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH. @@ -47,8 +47,8 @@ Using the Build System .. _idf.py: -``idf.py`` ----------- +idf.py +------ The ``idf.py`` command-line tool provides a front-end for easily managing your project builds. It manages the following tools: @@ -56,13 +56,13 @@ The ``idf.py`` command-line tool provides a front-end for easily managing your p - Ninja_ which builds the project - `esptool.py`_ for flashing the target. -You can read more about configuring the build system using ``idf.py`` :doc:`here `. +For more details about configuring the build system using ``idf.py``, please refer to :doc:`IDF Frontend `. Using CMake Directly -------------------- -:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. +:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly. .. highlight:: bash @@ -125,7 +125,6 @@ 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 up the Python Interpreter @@ -621,6 +620,7 @@ Including Components in the Build - The ``MINIMAL_BUILD`` :ref:`build property ` can be set to ``ON``, which acts as a shortcut to configure the ``COMPONENTS`` variable to include only the ``main`` component. This means that the build will include only the :ref:`common components `, the ``main`` component, and all dependencies associated with it, both direct and indirect. If the ``COMPONENTS`` variable is defined while the ``MINIMAL_BUILD`` property is enabled, ``COMPONENTS`` will take precedence. .. note:: + Certain features and configurations, such as those provided by esp_psram or espcoredump components, may not be available to your project by default if the minimal list of components is used. When using the ``COMPONENTS`` variable, ensure that all necessary components are included. Similarly, when using the ``MINIMAL_BUILD`` build property, ensure that all required components are specified in the ``REQUIRES`` or ``PRIV_REQUIRES`` argument during component registration. .. _component-circular-dependencies: diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 7f8e6819f1..c5c78d46bb 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -17,7 +17,8 @@ Configurations -------------- .. note:: - The ``Core dump`` configuration options are available only if the ``espcoredump`` component is included in the build. To include ``Core dump`` into your project, add the ``espcoredump`` component as a dependency in either REQUIRES or PRIV_REQUIRES when registering your component with ``idf_component_register``. + + The ``Core dump`` configuration options are available only if the ``espcoredump`` component is included in the build. To include ``Core dump`` into your project, add the ``espcoredump`` component as a dependency in either ``REQUIRES`` or ``PRIV_REQUIRES`` when registering your component with ``idf_component_register``. Destination ^^^^^^^^^^^ diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 55c52d502d..81f1452ddc 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -47,7 +47,8 @@ Configuring External RAM ======================== .. note:: - The ``SPI RAM`` configuration options are available only if the ``esp_psram`` component is included in the build. To include ``SPI RAM`` into your project, add the ``esp_psram`` component as a dependency in either REQUIRES or PRIV_REQUIRES when registering your component with ``idf_component_register``. + + The ``SPI RAM`` configuration options are available only if the ``esp_psram`` component is included in the build. To include ``SPI RAM`` into your project, add the ``esp_psram`` component as a dependency in either ``REQUIRES`` or ``PRIV_REQUIRES`` when registering your component with ``idf_component_register``. ESP-IDF fully supports the use of external RAM in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to integrate the external RAM in several ways: diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 0e21ecd165..97ac467ab1 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -25,7 +25,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候， 概念 ---- -- ``项目`` 特指一个目录，其中包含了构建可执行应用程序所需的全部文件和配置，以及其他支持型文件，例如分区表、数据/文件系统分区和引导加载程序。 +- ``项目`` 特指一个目录，其中包含了构建 ``应用程序`` （即可执行文件）所需的全部文件和配置，还包含了其他支持型文件，例如分区表、数据分区或文件系统分区，以及引导加载程序。 - ``项目配置`` 保存在项目根目录下名为 ``sdkconfig`` 的文件中，可以通过 ``idf.py menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 @@ -48,7 +48,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候， .. _idf.py: idf.py --------- +------ ``idf.py`` 命令行工具提供了一个前端，可以帮助你轻松管理项目的构建过程，它管理了以下工具： @@ -56,17 +56,17 @@ idf.py - Ninja_，用于构建项目 - `esptool.py`_，烧录目标硬件设备 -可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`相关文档 `。 +可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`IDF 前端工具 `。 直接使用 CMake -------------- -为了方便，:ref:`idf.py` 已经封装了 CMake_ 命令，但是你愿意，也可以直接调用 CMake。 +为了方便，:ref:`idf.py` 已经封装了 CMake_ 命令。你也可以直接调用 CMake。 .. highlight:: bash -当 ``idf.py`` 在执行某些操作时，它会打印出其运行的每条命令以便参考。例如运行 ``idf.py build`` 命令与在 bash shell（或者 Windows Command Prompt）中运行以下命令是相同的:: +当 ``idf.py`` 在执行某些操作时，它会打印运行的每条命令以便参考。例如，运行 ``idf.py build`` 命令等同于在 bash shell 中运行以下命令（或在 Windows 命令提示符中运行类似的命令）:: mkdir -p build cd build @@ -79,7 +79,7 @@ idf.py 若在 CMake 中使用 ``ninja`` 或 ``make``，则多数 ``idf.py`` 子命令也会有其对应的目标，例如在构建目录下运行 ``make menuconfig`` 或 ``ninja menuconfig`` 与运行 ``idf.py menuconfig`` 是相同的。 -.. Note:: +.. note:: 如果你已经熟悉了 CMake_，那么可能会发现 ESP-IDF 的 CMake 构建系统不同寻常，为了减少样板文件，该系统封装了 CMake 的许多功能。请参考 :ref:`write-pure-component` 以编写更多 “CMake 风格”的组件。 @@ -103,7 +103,7 @@ idf.py ESPPORT=/dev/ttyUSB0 ninja flash -.. Note:: +.. note:: 在命令的开头为环境变量赋值属于 Bash shell 的语法，可在 Linux 、macOS 和 Windows 的类 Bash shell 中运行，但在 Windows Command Prompt 中无法运行。 @@ -111,7 +111,7 @@ idf.py make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 -.. Note:: +.. note:: 在命令末尾为变量赋值属于 ``make`` 的语法，适用于所有平台的 ``make``。 @@ -127,7 +127,6 @@ idf.py .. _setting-python-interpreter: - 设置 Python 解释器 ------------------ @@ -602,7 +601,7 @@ Spark Plug 组件 通用组件依赖项 -------------- -为避免重复性工作，各组件都用自动依赖一些“通用”IDF 组件，即使它们没有被明确提及。这些组件的头文件会一直包含在构建系统中。 +为避免重复性工作，各组件都用自动依赖一些“通用” IDF 组件，即使它们没有被明确提及。这些组件的头文件会一直包含在构建系统中。 通用组件包括：cxx、newlib、freertos、esp_hw_support、heap、log、soc、hal、esp_rom、esp_common、esp_system。 @@ -615,15 +614,14 @@ Spark Plug 组件 * ``COMPONENTS`` 中明确提及的组件。 * 这些组件的依赖项（以及递归运算后的组件）。 - * 每个组件都依赖的通用组件。 + * 每个组件都依赖的 :ref:`通用组件 `。 - 将 ``COMPONENTS`` 设置为所需组件的最小列表，可以显著减少项目的构建时间。 -- 可以将 ``MINIMAL_BUILD`` :ref:`构建属性 ` 设为 ``ON``，从而快捷配置 ``COMPONENTS`` 变量，使其仅包含 ``main`` 组件。如果在启用 ``MINIMAL_BUILD`` 属性的同时定义了 ``COMPONENTS`` 变量，则 ``COMPONENTS`` 会优先生效。 +- 可以将 ``MINIMAL_BUILD`` :ref:`构建属性 ` 设为 ``ON``，从而快捷配置 ``COMPONENTS`` 变量，使其仅包含 ``main`` 组件。构建过程将仅包括 :ref:`通用组件 `、``main`` 组件和所有相关依赖项（包括直接和间接依赖）。如果在启用 ``MINIMAL_BUILD`` 属性的同时定义了 ``COMPONENTS`` 变量，则 ``COMPONENTS`` 会优先生效。 .. note:: - 使用 ``COMPONENTS`` 变量或 ``MINIMAL_BUILD`` 构建属性指定组件时，一些功能和配置（如 esp_psram 或 espcoredump 组件提供的功能和配置）可能不会被默认包含。如需使用这些功能，须将相关组件添加到 ``COMPONENTS`` 变量中，或在组件注册时将其列入 ``REQUIRES`` 或 ``PRIV_REQUIRES`` 参数。 - + 如果使用最小组件列表，某些功能和配置（如 esp_psram 或 espcoredump 组件提供的功能和配置）可能默认无法在项目中使用。使用 ``COMPONENTS`` 变量时，请确保包含所有必要的组件。同样地，使用 ``MINIMAL_BUILD`` 构建属性时，请确保在组件注册时通过 ``REQUIRES`` 或 ``PRIV_REQUIRES`` 参数指定所有所需组件。 .. _component-circular-dependencies: diff --git a/docs/zh_CN/api-guides/core_dump.rst b/docs/zh_CN/api-guides/core_dump.rst index 4a4ed94bf2..656b3ffa27 100644 --- a/docs/zh_CN/api-guides/core_dump.rst +++ b/docs/zh_CN/api-guides/core_dump.rst @@ -17,7 +17,8 @@ -------------- .. note:: - 只有在构建中包含 ``espcoredump`` 组件时，``Core dump`` 配置选项才可用。 + + 只有在构建中包含 ``espcoredump`` 组件时，``Core dump`` 配置选项才可用。要在项目中包含 ``Core dump`` 功能，在使用 ``idf_component_register`` 注册组件时，将 ``espcoredump`` 组件添加为 ``REQUIRES`` 或 ``PRIV_REQUIRES`` 的依赖项。 目标 ^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 4dd921ddef..d6a5b24f96 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -47,7 +47,8 @@ ======================== .. note:: - 只有在构建中包含 ``esp_psram`` 组件时，``SPI RAM`` 配置选项才可用。 + + 只有在构建中包含 ``esp_psram`` 组件时，``SPI RAM`` 配置选项才可用。要在项目中包含 ``SPI RAM`` 功能，使用 ``idf_component_register`` 注册组件时，将 ``esp_psram`` 组件添加为 ``REQUIRES`` 或 ``PRIV_REQUIRES`` 的依赖项。 ESP-IDF 完全支持将片外 RAM 集成到你的应用程序中。在启动并完成片外 RAM 初始化后，可以将 ESP-IDF 配置为用多种方式处理片外 RAM： @@ -55,7 +56,7 @@ ESP-IDF 完全支持将片外 RAM 集成到你的应用程序中。在启动并 * :ref:`external_ram_config_memory_map` * :ref:`external_ram_config_capability_allocator` - * :ref:`external_ram_config_malloc` (default) + * :ref:`external_ram_config_malloc` （默认方式） * :ref:`external_ram_config_bss` * :ref:`external_ram_config_noinit` :SOC_SPIRAM_XIP_SUPPORTED: * :ref:`external_ram_config_xip`