mirror of
https://github.com/espressif/esp-idf
synced 2025-03-09 17:19:09 -04:00
docs(kconfiglib): Add Project and Component configuration guide
* Project Configuration Guide: how to configure the project, purpose of sdkconfig.defaults, where is the configuration stored... * Component configuration: how to write Kconfig files, how to ensure backward compatibility... Also, general information about Kconfig and its files was added. Other parts of the documentation (e.g. build-system) now point to these new guides in order to provide more info.
This commit is contained in:
Jan Beran
parent
cd21bdeb15
commit
1fcf006ec6
BIN
docs/_static/menuconfig-screen.png
vendored
Normal file
BIN
docs/_static/menuconfig-screen.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
@ -181,7 +181,7 @@ This example "myProject" contains the following elements:
|
||||
|
||||
- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which implements the rest of the build system. Finally, it sets the project name and defines the project.
|
||||
|
||||
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the 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.
|
||||
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the 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. More information about this file can be found in the :ref:`sdkconfig file <sdkconfig-file>` section in the Configuration Guide.
|
||||
|
||||
- "dependencies.lock" file contains the list of all managed components, and their versions, that are currently in used in the project. The ``dependencies.lock`` file is generated or updated automatically when IDF Component Manager is used to add or update project components. So this file should never be edited manually! If the project does not have ``idf_component.yml`` files in any of its components, ``dependencies.lock`` will not be created.
|
||||
|
||||
@ -362,7 +362,7 @@ The following component-specific variables are available for use inside componen
|
||||
|
||||
The following variables are set at the project level, but available for use in component CMakeLists:
|
||||
|
||||
- ``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>`.
|
||||
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. More information on how the project configuration works, please visit :ref:`Project Configuration Guide <project-configuration-guide>`.
|
||||
- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within the ESP-IDF build system.
|
||||
|
||||
|
||||
@ -428,7 +428,7 @@ These settings are found under the "Component Settings" menu when menuconfig is
|
||||
|
||||
To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF.
|
||||
|
||||
For an example, see `Adding conditional configuration`_.
|
||||
For an example, see `Adding conditional configuration`_. For a more detailed guide, see :ref:`Component Configuration Guide <component-configuration-guide>`.
|
||||
|
||||
|
||||
Preprocessor Definitions
|
||||
@ -461,7 +461,7 @@ When Writing a Component
|
||||
|
||||
- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* in this component, unless already listed in ``REQUIRES``. Also, any component which is required to be linked in order for this component to function correctly.
|
||||
|
||||
- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before the configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
|
||||
- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration options (``CONFIG_xxx`` macros). This is because requirements are expanded before the configuration is loaded. Other component variables (like include paths or source files) can depend on configuration options.
|
||||
|
||||
- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the `Common component requirements`_ needed for RTOS, libc, etc.
|
||||
|
||||
@ -724,13 +724,14 @@ Note that ``project_include.cmake`` isn't necessary for the most common componen
|
||||
Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included in the top-level project CMake pass, they can influence or break functionality across all components!
|
||||
|
||||
|
||||
KConfig.projbuild
|
||||
Kconfig.projbuild
|
||||
-----------------
|
||||
|
||||
This is an equivalent to ``project_include.cmake`` for :ref:`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 ``CMakeLists.txt`` file.
|
||||
This is an equivalent to ``project_include.cmake`` for :ref:`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 ``CMakeLists.txt`` 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 :ref:`component-configuration`.
|
||||
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 :ref:`component-configuration`.
|
||||
|
||||
For more information, see :ref:`Kconfig Files <kconfig-files>` section in the Configuration Guide.
|
||||
|
||||
Wrappers to Redefine or Extend Existing Functions
|
||||
-------------------------------------------------
|
||||
@ -787,7 +788,7 @@ See :example:`custom_bootloader/bootloader_override` for an example of overridin
|
||||
Configuration-Only Components
|
||||
=============================
|
||||
|
||||
Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any included paths.
|
||||
Special components which contain no source files, only ``Kconfig.projbuild`` and ``Kconfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any included paths.
|
||||
|
||||
|
||||
Debugging CMake
|
||||
@ -1065,6 +1066,10 @@ The best of these approaches for building an external project will depend on the
|
||||
Custom Sdkconfig Defaults
|
||||
=========================
|
||||
|
||||
.. note::
|
||||
|
||||
For more detailed information about ``sdkconfig.defaults`` file, please visit :ref:`sdkconfig.defaults file <sdkconfig-defaults-file>` in Project Configuration section.
|
||||
|
||||
For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
|
||||
|
||||
To override the name of this file or to specify multiple files, set the ``SDKCONFIG_DEFAULTS`` environment variable or set ``SDKCONFIG_DEFAULTS`` in top-level ``CMakeLists.txt``. File names that are not specified as full paths are resolved relative to current project's directory.
|
||||
@ -1083,6 +1088,7 @@ If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file/files, t
|
||||
|
||||
For example, if ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"``, and there is a file ``sdkconfig.defaults.esp32`` in the same folder, then the files will be applied in the following order: (1) sdkconfig.defaults (2) sdkconfig.defaults.esp32 (3) sdkconfig_devkit1.
|
||||
|
||||
You can find more detailed information on how the project configuration works in the :ref:`Project Configuration Guide <project-configuration-guide>`. In the :ref:`Configuration Files Structure and Relationships <configuration-structure>`, you can find lower-level information about the configuration files.
|
||||
|
||||
.. _flash_parameters:
|
||||
|
||||
@ -1670,7 +1676,7 @@ Application Examples
|
||||
|
||||
- :example:`build_system/wrappers` demonstrates how to use a linker feature to redefine or override any public function in both ESP-IDF and the bootloader, allowing modification or extension of a function's default behavior.
|
||||
|
||||
- :example:`custom_bootloader/bootloader_override` demonstrates how to override the second stage bootloader from a regular project, providing a custom bootloader that prints an extra message on startup, with the ability to conditionally override the bootloader based on certain conditions like target-dependency or KConfig options.
|
||||
- :example:`custom_bootloader/bootloader_override` demonstrates how to override the second-stage bootloader from a regular project, providing a custom bootloader that prints an extra message on startup, with the ability to conditionally override the bootloader based on certain conditions like target-dependency or Kconfig options.
|
||||
|
||||
- :example:`build_system/cmake/import_lib` demonstrates how to import and use third-party libraries using ExternalProject CMake module.
|
||||
|
||||
|
||||
@ -29,6 +29,7 @@ API Guides
|
||||
hardware-abstraction
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: hlinterrupts
|
||||
jtag-debugging/index
|
||||
kconfig/index
|
||||
linker-script-generation
|
||||
low-power-mode/index
|
||||
lwip
|
||||
|
||||
99
docs/en/api-guides/kconfig/component-configuration-guide.rst
Normal file
99
docs/en/api-guides/kconfig/component-configuration-guide.rst
Normal file
@ -0,0 +1,99 @@
|
||||
.. _component-configuration-guide:
|
||||
|
||||
Component Configuration Guide
|
||||
=============================
|
||||
|
||||
This guide is intended to describe how to define configuration options for components in ESP-IDF. Following topics will be covered:
|
||||
|
||||
- How to define new configuration options for components.
|
||||
- Basic syntax of Kconfig language.
|
||||
- How to ensure backward compatibility.
|
||||
|
||||
How Configuration Works in ESP-IDF
|
||||
----------------------------------
|
||||
|
||||
.. note::
|
||||
|
||||
More detailed information about the configuration system in ESP-IDF can be found in the :ref:`configuration-overview`.
|
||||
|
||||
|
||||
ESP-IDF uses unified way to configure the project, build system, ESP-IDF framework itself and external components. This configuration tool is called `Kconfig <https://docs.espressif.com/projects/esp-idf-kconfig/en/kconfiglib/language.html>`_.
|
||||
|
||||
Configuration options are **defined** in ``Kconfig`` files. ESP-IDF contains the top-level ``Kconfig`` file in the root of the framework. Each component can have its own ``Kconfig`` file defining configuration options specific to that component, as well as relations between the options. Relations between config options can spread across multiple Kconfig files from different sources. In other words, configuration option from ``Component_A`` can depend on a configuration option from ``Component_B``, even if ``Component_B`` is e.g. maintained by another developer.
|
||||
|
||||
When the configuration is saved (for more information about configuration editing, see e.g. :ref:`project-configuration-guide`), the **values** in the ``sdkconfig`` file are updated, as well as those in ``sdkconfig.h``, ``sdkconfig.cmake`` and ``sdkconfig.json``.
|
||||
|
||||
How to Define New Configuration Options for Your Component
|
||||
----------------------------------------------------------
|
||||
.. note::
|
||||
|
||||
If you plan to write ``Kconfig`` configuration files for your component, but you are not familiar with ``Kconfig language`` it is recommended to refer to the `esp-idf-kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/index.html>`_, where an in-depth guide is provided.
|
||||
|
||||
To define new configuration options for components, you need to:
|
||||
|
||||
1. Create the ``Kconfig`` and/or ``Kconfig.projbuild`` in the root folder of the component.
|
||||
2. Define the configuration options in the ``Kconfig`` and/or ``Kconfig.projbuild`` file. It is generally a good practice to wrap them in the ``menu-endmenu`` block. You can see a minimal example below. Complete documentation of the Kconfig language can be found in the `Kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/kconfiglib/language.html>`_.
|
||||
|
||||
When your component is used in a project, the ``Kconfig`` and/or ``Kconfig.projbuild`` will be automatically discovered and shown in the ``menuconfig`` tool.
|
||||
|
||||
.. note::
|
||||
|
||||
**Difference between Kconfig and Kconfig.projbuild files**:
|
||||
|
||||
- ``Kconfig``: configuration options in this file will be shown under ``Component configuration`` in the ``menuconfig`` tool.
|
||||
- ``Kconfig.projbuild``: configuration options in this file will be shown in the top menu of the ``menuconfig`` tool.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
menu "Motors configuration"
|
||||
|
||||
config SUBLIGHT_DRIVE_ENABLED
|
||||
bool "Enable sublight drive"
|
||||
default n
|
||||
depends on SPACE_SHIP
|
||||
help
|
||||
This option enables sublight on our spaceship.
|
||||
|
||||
endmenu
|
||||
|
||||
.. note::
|
||||
|
||||
**Visibility and dependencies**:
|
||||
|
||||
In the example above, the ``SUBLIGHT_DRIVE_ENABLED`` configuration option has a dependency on the ``SPACE_SHIP`` configuration option. This option can origin from a different component. If the ``SPACE_SHIP`` option is not set or is not defined in the current configuration (e.g. the component containing this option was not included in the project), the dependency will not be satisfied and the ``SUBLIGHT_DRIVE_ENABLED`` option will not be shown in the ``menuconfig`` tool.
|
||||
|
||||
For more information about the visibility and dependencies, please refer to the `Kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/kconfiglib/language.html>`_.
|
||||
|
||||
|
||||
.. _configuration-options-compatibility:
|
||||
|
||||
How to Ensure Backward Compatibility
|
||||
------------------------------------
|
||||
|
||||
In general, renaming a Kconfig option of a component is a breaking API change, just like renaming a function is. ESP-IDF contains a mechanism which makes it possible to maintain backward compatibility when renaming configuration options. This mechanism is based on ``sdkconfig.rename`` files which include pairs of configuration option names. File structure is described below.
|
||||
|
||||
When renaming configuration options of a component, create the ``sdkconfig.rename`` file in the root folder of the component. Every line in this file should contain one of the following pairs:
|
||||
|
||||
* ``CONFIG_OLD_NAME CONFIG_NEW_NAME`` if the new option is a direct replacement of the old option.
|
||||
* ``CONFIG_OLD_NAME !CONFIG_NEW_NAME`` if the new option is a Boolean inversion of the old option.
|
||||
|
||||
The project configuration tool (invoked by ``idf.py menuconfig``) will automatically find it and generate the compatibility statements in ``sdkconfig`` for the user.
|
||||
|
||||
For more information about the ``sdkconfig.rename`` file, please refer to the :ref:`sdkconfig.rename <sdkconfig-rename-file>` section of Configuration Structure.
|
||||
|
||||
Detailed explanation of the backward compatibility mechanism:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. note::
|
||||
|
||||
This part of the guide is intended to explain the behavior of the backward compatibility mechanism in ESP-IDF in greater detail. It is not necessary to understand this mechanism as it it done automatically, but it is described here for the sake of completeness.
|
||||
|
||||
If the user has set any value for the old config option (e.g. old config name is used in ``sdkconfig`` or ``sdkconfig.defaults``) without ``sdkconfig.rename`` file provided, this value would be **silently ignored**. This behavior is the default of the Kconfig system and is not a bug. In the original project (configuration of the linux kernel) this behavior was desired and is still desired in many projects.
|
||||
|
||||
This behavior is suppressed in ESP-IDF by the the configuration tool (invoked by ``idf.py menuconfig``). This tool generates compatibility statements for all the renamed options in the ``sdkconfig`` file. In more detail, the following approach is used to prevent the above mentioned situation:
|
||||
|
||||
1. Configuration tool searches the whole ESP-IDF folder for ``sdkconfig.rename`` files. If the project target (``<chip>``) matches the last suffix of any ``sdkconfig.rename.<chip>`` file, the file will be used in the next step as well.
|
||||
|
||||
2. After collecting all the relevant files, the ``sdkconfig`` file (and ``sdkconfig.h/json/cmake`` files if any) is post-processed. A block of compatibility statements for all the renamed options is added during the post-process to the end of the file(s). The block starts with ``# Deprecated options for backward compatibility`` and ends with ``# End of deprecated options``.
|
||||
151
docs/en/api-guides/kconfig/configuration_structure.rst
Normal file
151
docs/en/api-guides/kconfig/configuration_structure.rst
Normal file
@ -0,0 +1,151 @@
|
||||
.. _configuration-structure:
|
||||
|
||||
Configuration Files Structure and Relationships
|
||||
===============================================
|
||||
|
||||
.. note::
|
||||
|
||||
This article primarily focuses on the structure of the files. For more information about project configuration, please refer to the :ref:`Project Configuration Guide <project-configuration-guide>`. For the component configuration, please refer to the :ref:`Component Configuration Guide <component-configuration-guide>`.
|
||||
|
||||
ESP-IDF uses `Kconfig language <https://docs.espressif.com/projects/esp-idf-kconfig/en/kconfiglib/language.html>`_ for configuration of the project. Configuration consists of config options (e.g. ``CONFIG_IDF_TARGET``) and their values (e.g. ``esp32``). Every config option has a prefix ``CONFIG_`` to distinguish it from e.g. environment variables.
|
||||
|
||||
In context of ESP-IDF, configuration consists of several files, most importantly:
|
||||
|
||||
- ``Kconfig`` files, defining the configuration options and their relationships, together with their default values (if any).
|
||||
- ``sdkconfig`` file, containing the currently used values of configuration options.
|
||||
- ``sdkconfig.defaults`` file, containing user-defined default values for the configuration options.
|
||||
- ``sdkconfig.rename`` file, containing ``OLD_NAME NEW_NAME`` pairs of configuration names to ensure backward compatibility. This file is used primarily by component or ESP-IDF developers.
|
||||
|
||||
Configuration files can be divided into two groups: those primarily **defining** the configuration options and those containing the **values** of these options. First group includes ``Kconfig``, ``Kcofnig.projbuild`` and ``sdkconfig.rename`` files, second group includes ``sdkconfig``, ``sdkconfig.defaults``, ``sdkconfig.h`` and ``sdkconfig.cmake`` files. All the files will be described in the following sections.
|
||||
|
||||
For more information about the configuration system in ESP-IDF, please refer to the :ref:`Configuration Overview <configuration-overview>`.
|
||||
|
||||
.. _kconfig-files:
|
||||
|
||||
Kconfig and Kconfig.projbuild Files
|
||||
-----------------------------------
|
||||
|
||||
The ``Kconfig.*`` files store the configuration options, together with their properties and relationships. They also may contain default values for the configuration options. Every component has its own ``Kconfig`` file, which is used to define the configuration options for that component.
|
||||
|
||||
The only difference between ``Kconfig`` and ``Kconfig.projbuild`` files is where the their content will appear in the configuration interface (menuconfig):
|
||||
|
||||
- ``Kconfig``: The content of this file will appear in the ``Component config`` window of the configuration interface.
|
||||
- ``Kconfig.projbuild``: The content of this file will appear in the root window of the configuration interface.
|
||||
|
||||
Example of ``Kconfig`` file:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
mainmenu "Motors configuration"
|
||||
|
||||
config SUBLIGHT_DRIVE_ENABLED
|
||||
bool "Enable sublight drive"
|
||||
default y
|
||||
help
|
||||
This option enables sublight on our spaceship.
|
||||
|
||||
For more information about the Kconfig language, please refer to the `Kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/kconfiglib/language.html>`_.
|
||||
|
||||
.. _sdkconfig-file:
|
||||
|
||||
sdkconfig and sdkconfig.old
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In the ``sdkconfig`` file, **values currently assigned** to the configuration options are stored. It is generated automatically and is not to be edited, because configuration options can have relationships between one another (dependencies and reverse dependencies), that can be broken by manual editing.
|
||||
|
||||
Every line follows one of the following patterns:
|
||||
|
||||
- ``CONFIG_NAME=<value>``: Config name and its value.
|
||||
- ``# CONFIG_NAME is not set``: Boolean config ``CONFIG_NAME`` is visible, but it is set to n. For non-Boolean configs, ``CONFIG_NAME=""`` will be present instead.
|
||||
- Other #-style comments and empty lines.
|
||||
|
||||
The ``sdkconfig.old`` file is a backup of the previous configuration. It is generated every time the ``sdkconfig`` file is generated.
|
||||
|
||||
.. note::
|
||||
|
||||
There are other sdkconfig.* files in the project, namely ``sdkconfig.h``, ``sdkconfig.cmake``, ``sdkconfig.json``. These files are the same as the ``sdkconfig`` file mentioned above, but in different formats. These files are used with their respective tools (C/C++ code, CMake). You can check :ref:`configs-in-C-Cmake` for more information.
|
||||
|
||||
.. _sdkconfig-rename-file:
|
||||
|
||||
sdkconfig.rename and sdkconfig.rename.<chip>
|
||||
----------------------------------------------------
|
||||
|
||||
The ``sdkconfig.rename`` files are used by the build system to ensure backward compatibility. These files are created and maintained by component or ESP-IDF developers and application developer should have no need to edit them.
|
||||
|
||||
The structure of the ``sdkconfig.rename`` file is as follows:
|
||||
|
||||
* Lines starting with ``#`` and empty lines will be ignored.
|
||||
* All other lines should follow one of these formats:
|
||||
* ``CONFIG_DEPRECATED_NAME CONFIG_NEW_NAME``, where ``CONFIG_DEPRECATED_NAME`` is the old config name which was renamed in a newer ESP-IDF version to ``CONFIG_NEW_NAME``.
|
||||
* ``CONFIG_DEPRECATED_NAME !CONFIG_NEW_INVERTED_NAME`` where ``CONFIG_NEW_INVERTED_NAME`` was introduced in a newer ESP-IDF version by Boolean inversion of the logic value of ``CONFIG_DEPRECATED_NAME``.
|
||||
|
||||
Primary use case of this file is to ensure backward compatibility when the config name is changed in the newer ESP-IDF version.
|
||||
|
||||
Example:
|
||||
|
||||
``sdkconfig.rename``:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
# new name old name
|
||||
CONFIG_HYPEDRIVE CONFIG_WARP_DRIVE
|
||||
CONFIG_DISABLE_WAPRT_ !CONFIG_ENABLE_WARP_DRIVE
|
||||
|
||||
``sdkconfig``:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
(...)
|
||||
CONFIG_HYPEDRIVE=y
|
||||
CONFIG_DISABLE_HYPEDRIVE=n
|
||||
(...)
|
||||
# Deprecated options for backward compatibility
|
||||
CONFIG_WARP_DRIVE=y
|
||||
CONFIG_ENABLE_WARP_DRIVE=y
|
||||
# End of deprecated options
|
||||
|
||||
.. _sdkconfig-defaults-file:
|
||||
|
||||
sdkconfig.defaults and sdkconfig.defaults.<chip>
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Kconfig language provides a way to set default values for configs: ``default`` option. However, input Kconfig file may be in a different project, under version control or there is another reason why it would be inconvenient to directly edit it. In this case, ``sdkconfig.defaults`` file can be used. The file structure is the same as ``sdkconfig`` file; on every line, there is a full config name (including the ``CONFIG_`` prefix) and its value. This value has precedence over the default value in the Kconfig file by ``default`` option.
|
||||
|
||||
It is also possible to override the default values only for specific target. In this case, you can create ``sdkconfig.defaults.<chip>`` file, where ``<chip>`` is the target name (e.g. ``esp32s2``). In this case, it is mandatory to create the ``sdkconfig.defaults`` file as well, otherwise the ``sdkconfig.defaults.<chip>`` file will be ignored. However, the ``sdkconfig.defaults`` file can be empty.
|
||||
|
||||
.. note::
|
||||
|
||||
Values in ``sdkconfig.defaults`` are additional default values, not overrides! This means that those values will be ignored if ``sdkconfig`` file is present.
|
||||
|
||||
It is also possible to override the name of this file by setting an environment variable. For information on how to set the custom file name and in which order the files are processed if multiple files with default values are present, please visit :ref:`Custom Sdkconfig Defaults <custom-sdkconfig-defaults>` section of Build System documentation.
|
||||
|
||||
Example:
|
||||
|
||||
``Kconfig``:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
(...)
|
||||
config SUBLIGHT_SPEED
|
||||
int "Sublight speed"
|
||||
default 10
|
||||
(...)
|
||||
|
||||
``sdkconifg.defaults``:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
CONFIG_SUBLIGHT_SPEED=42
|
||||
|
||||
When running e.g. ``idf.py menuconfig``, the ``SUBLIGHT_SPEED`` will be set to 42. If the value will be changed in the GUI, the value from the GUI will be used and saved into ``sdkconfig`` file.
|
||||
|
||||
How to generate ``sdkconfig.defaults`` file:
|
||||
|
||||
1. ``cd`` into your project folder.
|
||||
2. Configure everything you need in ``idf.py menuconfig``.
|
||||
3. Run ``idf.py save-defconfig``. This will generate ``sdkconfig.defaults`` file with all the values different from the default ones.
|
||||
|
||||
sdkconfig.ci
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Some of the IDF examples include a ``sdkconfig.ci`` file. This is part of the continuous integration (CI) test framework and is ignored by the normal build process.
|
||||
29
docs/en/api-guides/kconfig/index.rst
Normal file
29
docs/en/api-guides/kconfig/index.rst
Normal file
@ -0,0 +1,29 @@
|
||||
.. _configuration-overview:
|
||||
|
||||
Project Configuration
|
||||
=====================
|
||||
|
||||
In smaller projects (e.g. command line utility like ``grep`` command), it is often enough to configure it e.g. via command line parameters. When the projects gets larger, dedicated configuration files (C/C++ header files, YAML, JSON etc.) are often used with parameters altering the code behavior. However, as the number of configuration options grows, it becomes more and more difficult to manage them. Furthermore, different parts of the project (think of e.g. IDE plugins) can have different ways of configuring.
|
||||
|
||||
ESP-IDF project unified the way to configure the project, build system, ESP-IDF framework itself and external components. This configuration tool is called Kconfig.
|
||||
|
||||
Kconfig tool uses distributed structure of configuration files of the same name (``Kconfig``). These files contain the **definition** of configuration options (e.g. name, type) and may contain their **default values**. Every component has its own ``Kconfig`` file. Their discovery is done automatically by the configuration tool.
|
||||
|
||||
**Values currently assigned** to the configuration options are then stored in one :ref:`sdkconfig file <sdkconfig-file>` in the project's root folder. This file is specific for the given project and is changed every time user makes a change in any of the configuration option's value. For the purpose of editing the configuration, the :ref:`menuconfig tool <project-configuration-menu>` is used. The values of the configuration options are also propagated to the CMake scripts and C code via ``sdkconfig.h`` and ``sdkconfig.cmake`` files.
|
||||
|
||||
For the purpose of setting **user-defined default values** for configuration options, the :ref:`sdkconfig.defaults file <sdkconfig-defaults-file>` can be used. This approach is also preferred in the situation when the project is under version control. This file is used to replace default values set by ``Kconfig`` files when the project is configured the first time and no ``sdkconfig`` is present, but those values can still be changed by the user via configuration tools (e.g. ``idf.py menuconfig``).
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ESP-IDF Project Configuration Guide <project-configuration-guide>
|
||||
Configuration Files and Structure <configuration_structure>
|
||||
Defining configuration options of components <component-configuration-guide>
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
For the detailed information about Kconfig language or ``esp-idf-kconfig``, which is the package of tools for the ESP-IDF configuration, please refer to the to the lower-level and more implementation-focused `esp-idf-kconfig documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/index.html>`_.
|
||||
|
||||
.. note::
|
||||
For the complete list of configuration options, please refer to the :ref:`Configuration Options Reference <configuration-options-reference>` and in the top left corner, choose your combination of a chip and ESP-IDF version.
|
||||
107
docs/en/api-guides/kconfig/project-configuration-guide.rst
Normal file
107
docs/en/api-guides/kconfig/project-configuration-guide.rst
Normal file
@ -0,0 +1,107 @@
|
||||
.. _project-configuration-guide:
|
||||
|
||||
Project Configuration Guide
|
||||
===========================
|
||||
|
||||
This guide is intended to describe three aspects of project configuration in ESP-IDF:
|
||||
|
||||
- How the configuration can be edited (``idf.py menuconfig`` and configuration via plugins)
|
||||
- How to use configuration values in C code and CMake
|
||||
- How to define new configuration options for the project
|
||||
|
||||
.. _project-configuration-menu:
|
||||
|
||||
Editing the Configuration
|
||||
-------------------------
|
||||
|
||||
As mentioned in the :ref:`configuration-overview`, **values currently assigned** to the configuration options are stored in the ``sdkconfig`` file. This file should not be edited manually, because there can be relationships between the configuration options that could be broken by manual editing. Instead, the ``idf.py menuconfig`` command (or its alternatives depending on the specific IDE used) should be used.
|
||||
|
||||
If the user wants to redefine the default values of the configuration options set in ``Kconfig`` files, the ``sdkconfig.defaults`` file can be used. The values set there overwrite those from ``Kconfig`` files, but user can still change those via ``idf.py menuconfig``. Those user-set values for the configuration options will be stored in the ``sdkconfig`` file, ``sdkconfig.defaults`` will remain unchanged.
|
||||
|
||||
There are several ways how to configure the project, depending on the IDE used. The most common way is to use the ``idf.py menuconfig`` command. This command opens a TUI (Text-based User Interface) where user can set the configuration options. The configuration is saved into the ``sdkconfig`` file. Alternatively, IDE plugins can be used as well.
|
||||
|
||||
Independently on the tool used, configuration values are loaded in the following order, values from later steps **may override** those from previous ones. These steps are done automatically and are described here only in order to explain the behavior:
|
||||
|
||||
1. Default configuration option values from ``Kconfig`` files are loaded, together with the relationships between them.
|
||||
2. If ``sdkconfig.defaults`` file is found, default values from this file are loaded.
|
||||
3. If present, ``sdkconfig`` file is loaded.
|
||||
|
||||
When the configuration is saved, the values in the ``sdkconfig`` file are updated, as well as those in ``sdkconfig.h``, ``sdkconfig.cmake`` and ``sdkconfig.json``.
|
||||
|
||||
Configuration with ``idf.py menuconfig``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Using the ``idf.py menuconfig`` command in terminal or command line is the most system and IDE agnostic way of configuration. This command opens a TUI (Text-based User Interface) where user can set the configuration options. Navigation is realized by arrow keys, other hotkeys are described in the lower part of the window.
|
||||
|
||||
.. image:: /../_static/menuconfig-screen.png
|
||||
|
||||
Configuration with ESP-IDF Plugin for Visual Studio Code
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After successful `installation <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ of the ESP-IDF plugin for Visual Studio Code, follow their `Basic Use document <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/basic_use.md>`_ and search for the **Configuration Editor** option.
|
||||
|
||||
Configuration with ESP-IDE
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
We also provide `plugin for Eclipse IDE <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md#Installation>`_. To edit the project configuration, follow `our documentation about SDK configuration <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md#sdk-configuration-editor>`_
|
||||
|
||||
.. note::
|
||||
|
||||
If you are using another IDE/plugin, please refer to the documentation of the IDE/plugin or use command line command ``idf.py menuconfig``.
|
||||
|
||||
.. _configs-in-C-Cmake:
|
||||
|
||||
How to Use Configuration Variables in C Code and CMake
|
||||
------------------------------------------------------
|
||||
|
||||
When the configuration is being saved to ``sdkconfig`` file, it is also saved in several different formats, including ``sdkconfig.h`` and ``sdkconfig.cmake``. The values in these files can be used in C code and CMake scripts.
|
||||
|
||||
Example of using configuration options in C code:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Contents of sdkconfig.h file (generated automatically, it should NOT be changed manually)
|
||||
//(...)
|
||||
#define CONFIG_USE_WARP 1
|
||||
#define CONFIG_WARP_SPEED 42
|
||||
//(...)
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Contents of C code file
|
||||
#include "sdkconfig.h"
|
||||
(...)
|
||||
#if CONFIG_USE_WARP
|
||||
set_warp_speed(CONFIG_WARP_SPEED);
|
||||
#else
|
||||
set_warp_speed(0);
|
||||
#endif
|
||||
|
||||
Example of using configuration options in CMake script:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# Contents of sdkconfig.cmake file (generated automatically, it should NOT be changed manually)
|
||||
#(...)
|
||||
set(CONFIG_USE_WARP 1)
|
||||
set(CONFIG_WARP_SPEED 42)
|
||||
#(...)
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# Contents of CMakeLists.txt file
|
||||
#(...)
|
||||
if(CONFIG_USE_WARP)
|
||||
set(WARP_SPEED ${CONFIG_WARP_SPEED})
|
||||
else()
|
||||
set(WARP_SPEED 0)
|
||||
endif()
|
||||
#(...)
|
||||
|
||||
.. _project-wide-config-options:
|
||||
|
||||
Defining New Configuration Options for the Project
|
||||
--------------------------------------------------
|
||||
|
||||
Some applications can get very complex and require a lot of configuration options. In such cases, it is useful to define new configuration options for the project. Similar to components, the application can have its own configuration options. These options are defined in the ``Kconfig`` or ``Kconfig.projbuild`` file in the ``main`` folder of the project. The process is the same as :ref:`defining new configuration options for components <component-configuration-guide>`, only with **different location** location of the ``Kconfig`` or ``Kconfig.projbuild`` file (``main`` instead of the root folder).
|
||||
|
||||
@ -10,7 +10,7 @@ ESP-IDF provides several kinds of programming interfaces:
|
||||
|
||||
* C functions, structures, enums, type definitions, and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures, and types.
|
||||
* Build system functions, predefined variables, and options. These are documented in the :ref:`ESP-IDF CMake Build System API <cmake_buildsystem_api>`.
|
||||
* :doc:`Kconfig <kconfig>` options can be used in code and in the build system (``CMakeLists.txt``) files.
|
||||
* :ref:`Kconfig options <configs-in-C-Cmake>` can be used in code and in the build system (``CMakeLists.txt``) files.
|
||||
* :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of the ESP-IDF interfaces.
|
||||
|
||||
ESP-IDF is made up of multiple components where these components either contain code specifically written for ESP chips, or contain a third-party library (i.e., a third-party component). In some cases, third-party components contain an "ESP-IDF specific" wrapper in order to provide an interface that is either simpler or better integrated with the rest of ESP-IDF's features. In other cases, third-party components present the original API of the underlying library directly.
|
||||
@ -145,7 +145,7 @@ While we try to make upgrading to a new ESP-IDF version easy, there are parts of
|
||||
* Changes made to mitigate security issues or to replace insecure default behaviors with secure ones.
|
||||
* Features that were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features that depend on non-functional chip hardware features.
|
||||
* Unexpected or undefined behavior that is not documented explicitly may be fixed/changed, such as due to missing validation of argument ranges.
|
||||
* Location of :doc:`Kconfig <kconfig>` options in menuconfig.
|
||||
* Location of :ref:`Kconfig <project-configuration-guide>` options in menuconfig.
|
||||
* Location and names of example projects.
|
||||
|
||||
.. _designated initializers: https://en.cppreference.com/w/c/language/struct_initialization
|
||||
|
||||
@ -13,7 +13,7 @@ API Reference
|
||||
error-codes
|
||||
network/index
|
||||
peripherals/index
|
||||
kconfig
|
||||
provisioning/index
|
||||
storage/index
|
||||
system/index
|
||||
kconfig-reference
|
||||
|
||||
11
docs/en/api-reference/kconfig-reference.rst
Normal file
11
docs/en/api-reference/kconfig-reference.rst
Normal file
@ -0,0 +1,11 @@
|
||||
Configuration Options Reference
|
||||
===============================
|
||||
|
||||
.. _configuration-options-reference:
|
||||
|
||||
Subsequent sections contain the list of available ESP-IDF options automatically generated from Kconfig files. Note that due to dependencies between options, some options listed here may not be visible by default in ``menuconfig``.
|
||||
|
||||
By convention, all option names are upper-case letters with underscores. When Kconfig generates ``sdkconfig`` and ``sdkconfig.h`` files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in ``menuconfig``, then the ``sdkconfig`` and ``sdkconfig.h`` files will have ``CONFIG_ENABLE_FOO`` defined. In the following sections, option names are also prefixed with ``CONFIG_``, same as in the source code.
|
||||
|
||||
|
||||
.. include-build-file:: inc/kconfig.inc
|
||||
@ -1,86 +0,0 @@
|
||||
Project Configuration
|
||||
*********************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The esp-idf-kconfig_ package that ESP-IDF uses is based on kconfiglib_, which is a Python extension to the Kconfig_ system. Kconfig provides a compile-time project configuration mechanism and offers configuration options of several types (e.g., integers, strings, and Booleans). Kconfig files specify dependencies between options, default values of options, the way options are grouped together, etc.
|
||||
|
||||
For the full list of available features, please see Kconfig_ and `kconfiglib extensions`_.
|
||||
|
||||
.. _project-configuration-menu:
|
||||
|
||||
Project Configuration Menu
|
||||
==========================
|
||||
|
||||
Application developers can open a terminal-based project configuration menu with the ``idf.py menuconfig`` build target.
|
||||
|
||||
After being updated, this configuration is saved in the ``sdkconfig`` file under the project root directory. Based on ``sdkconfig``, application build targets will generate the ``sdkconfig.h`` file under the build directory, and will make the ``sdkconfig`` options available to the project build system and source files.
|
||||
|
||||
Using ``sdkconfig.defaults``
|
||||
============================
|
||||
|
||||
In some cases, for example, when the ``sdkconfig`` file is under revision control, it may be inconvenient for the build system to change the ``sdkconfig`` file. The build system offers a solution to prevent it from happening, which is to create the ``sdkconfig.defaults`` file. This file is never touched by the build system, and can be created manually or automatically. It contains all the options which matter to the given application and are different from the default ones. The format is the same as that of the ``sdkconfig`` file. ``sdkconfig.defaults`` can be created manually when one remembers all the changed configuration, or it can be generated automatically by running the ``idf.py save-defconfig`` command.
|
||||
|
||||
Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted or added to the ignore list of the revision control system (e.g., the ``.gitignore`` file for ``git``). Project build targets will automatically create the ``sdkconfig`` file, populate it with the settings from the ``sdkconfig.defaults`` file, and configure the rest of the settings to their default values. Note that during the build process, settings from ``sdkconfig.defaults`` will not override those already in ``sdkconfig``. For more information, see :ref:`custom-sdkconfig-defaults`.
|
||||
|
||||
Kconfig Format Rules
|
||||
====================
|
||||
|
||||
Format rules for Kconfig files are as follows:
|
||||
|
||||
- Option names in any menus should have consistent prefixes. The prefix currently should have at least 3 characters.
|
||||
- The unit of indentation should be 4 spaces. All sub-items belonging to a parent item are indented by one level deeper. For example, ``menu`` is indented by 0 spaces, ``config`` ``menu`` by 4 spaces, ``help`` in ``config`` by 8 spaces, and the text under ``help`` by 12 spaces.
|
||||
- No trailing spaces are allowed at the end of the lines.
|
||||
- The maximum length of options is 50 characters.
|
||||
- The maximum length of lines is 120 characters.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``help`` section of each config in the menu is treated as reStructuredText to generate the reference documentation for each option.
|
||||
|
||||
Format Checker
|
||||
--------------
|
||||
|
||||
``kconfcheck`` tool in esp-idf-kconfig_ package is provided for checking Kconfig files against the above format rules. The checker checks all Kconfig and ``Kconfig.projbuild`` files given as arguments, and generates a new file with suffix ``.new`` with some suggestions about how to fix issues (if there are any). Please note that the checker cannot correct all format issues and the responsibility of the developer is to final check and make corrections in order to pass the tests. For example, indentations will be corrected if there is not any misleading formatting, but it cannot come up with a common prefix for options inside a menu.
|
||||
|
||||
The ``esp-idf-kconfig`` package is available in ESP-IDF environments, where the checker tool can be invoked by running command ``python -m kconfcheck <path_to_kconfig_file>``.
|
||||
|
||||
For more information, please refer to `esp-idf-kconfig package documentation <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`__.
|
||||
|
||||
.. _configuration-options-compatibility:
|
||||
|
||||
Backward Compatibility of Kconfig Options
|
||||
=========================================
|
||||
|
||||
The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases, then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
|
||||
|
||||
1. ``kconfgen`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else. For example, ``menuconfig`` would read them, so the settings for old options is kept and not ignored.
|
||||
2. ``kconfgen`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file. Renames that should only appear for a single target can be placed in a target-specific rename file ``sdkconfig.rename.TARGET``, where ``TARGET`` is the target name, e.g., ``sdkconfig.rename.esp32s2``.
|
||||
3. ``kconfgen`` post-processes ``sdkconfig`` files and generates all build outputs (``sdkconfig.h``, ``sdkconfig.cmake``, and ``auto.conf``) by adding a list of compatibility statements, i.e., the values of old options are set for new options after modification. If users still use old options in their code, this will prevent it from breaking.
|
||||
4. :ref:`configuration-deprecated-options` are automatically generated by ``kconfgen``.
|
||||
|
||||
The structure of the ``sdkconfig.rename`` file is as follows:
|
||||
|
||||
* Lines starting with ``#`` and empty lines will be ignored.
|
||||
* All other lines should follow one of these formats:
|
||||
* ``CONFIG_DEPRECATED_NAME CONFIG_NEW_NAME``, where ``CONFIG_DEPRECATED_NAME`` is the old config name which was renamed in a newer ESP-IDF version to ``CONFIG_NEW_NAME``.
|
||||
* ``CONFIG_DEPRECATED_NAME !CONFIG_NEW_INVERTED_NAME`` where ``CONFIG_NEW_INVERTED_NAME`` was introduced in a newer ESP-IDF version by Boolean inversion of the logic value of ``CONFIG_DEPRECATED_NAME``.
|
||||
|
||||
.. _configuration-options-reference:
|
||||
|
||||
Configuration Options Reference
|
||||
===============================
|
||||
|
||||
Subsequent sections contain the list of available ESP-IDF options automatically generated from Kconfig files. Note that due to dependencies between options, some options listed here may not be visible by default in ``menuconfig``.
|
||||
|
||||
By convention, all option names are upper-case letters with underscores. When Kconfig generates ``sdkconfig`` and ``sdkconfig.h`` files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in ``menuconfig``, then the ``sdkconfig`` and ``sdkconfig.h`` files will have ``CONFIG_ENABLE_FOO`` defined. In the following sections, option names are also prefixed with ``CONFIG_``, same as in the source code.
|
||||
|
||||
|
||||
.. include-build-file:: inc/kconfig.inc
|
||||
|
||||
.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
|
||||
.. _esp-idf-kconfig: https://pypi.org/project/esp-idf-kconfig/
|
||||
.. _kconfiglib: https://github.com/ulfalizer/Kconfiglib
|
||||
.. _kconfiglib extensions: https://pypi.org/project/kconfiglib/#kconfig-extensions
|
||||
@ -47,7 +47,7 @@ Vanilla FreeRTOS requires that ports and applications configure the kernel by ad
|
||||
|
||||
**However, for all FreeRTOS ports in ESP-IDF, the FreeRTOSConfig.h header file is considered private and must not be modified by users**. A large number of kernel configuration options in ``FreeRTOSConfig.h`` are hard-coded as they are either required/not supported by ESP-IDF. All kernel configuration options that are configurable by the user are exposed via menuconfig under ``Component Config/FreeRTOS/Kernel``.
|
||||
|
||||
For the full list of user configurable kernel options, see :doc:`/api-reference/kconfig`. The list below highlights some commonly used kernel configuration options:
|
||||
For the full list of user configurable kernel options, see :ref:`Kconfig Options Reference <configuration-options-reference>`. The list below highlights some commonly used kernel configuration options:
|
||||
|
||||
- :ref:`CONFIG_FREERTOS_UNICORE` runs FreeRTOS only on Core 0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Furthermore, this option may affect behavior of components other than :component:`freertos`. For more details regarding the effects of running FreeRTOS on a single core, refer to :ref:`freertos-idf-single-core` (if using ESP-IDF FreeRTOS) or the official Amazon SMP FreeRTOS documentation. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
|
||||
|
||||
|
||||
@ -105,3 +105,6 @@ get-started/macos-setup-scratch get-started/linux-macos-setup
|
||||
get-started/toolchain-setup-scratch get-started/index
|
||||
get-started/eclipse-setup get-started/index
|
||||
get-started/vscode-setup get-started/index
|
||||
|
||||
# Kconfig documentation got pretty serious file structure changes
|
||||
api-reference/kconfig api-reference/kconfig-reference
|
||||
|
||||
@ -362,7 +362,7 @@ ESP-IDF 在搜索所有待构建的组件时，会按照以下优先级搜索组
|
||||
|
||||
以下变量在项目级别中被设置，但可在组件 CMakeLists 中使用：
|
||||
|
||||
- ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :doc:`Kconfig </api-reference/kconfig>`。
|
||||
- ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :ref:`Project Configuration Guide <project-configuration-guide>`。
|
||||
- ``ESP_PLATFORM``：ESP-IDF 构建系统处理 CMake 文件时，其值设为 1。
|
||||
|
||||
|
||||
|
||||
@ -29,6 +29,7 @@ API 指南
|
||||
hardware-abstraction
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: hlinterrupts
|
||||
jtag-debugging/index
|
||||
kconfig/index
|
||||
linker-script-generation
|
||||
low-power-mode/index
|
||||
lwip
|
||||
|
||||
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-guides/kconfig/component-configuration-guide.rst
|
||||
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-guides/kconfig/configuration_structure.rst
|
||||
1
docs/zh_CN/api-guides/kconfig/index.rst
Normal file
1
docs/zh_CN/api-guides/kconfig/index.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-guides/kconfig/index.rst
|
||||
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-guides/kconfig/project-configuration-guide.rst
|
||||
@ -10,7 +10,7 @@ ESP-IDF 提供了几种编程接口：
|
||||
|
||||
* 在 ESP-IDF 组件的公共头文件中声明的 C 函数、结构体、枚举、类型定义和预处理器宏。编程指南的 API 参考部分描述了这些函数、结构体和类型。
|
||||
* 编译系统函数、预定义变量和选项，详情请参阅 :ref:`ESP-IDF CMake 构建系统 API <cmake_buildsystem_api>`。
|
||||
* :doc:`Kconfig <kconfig>` 选项，可用于代码及编译系统文件 (``CMakeLists.txt``)。
|
||||
* :ref:`Kconfig <configs-in-C-Cmake>` 选项，可用于代码及编译系统文件 (``CMakeLists.txt``)。
|
||||
* :doc:`主机工具 <../api-guides/tools/index>` 及其命令行参数。
|
||||
|
||||
ESP-IDF 由多个组件组成，组件中包含专门为 ESP 芯片编写的代码或第三方库（即第三方组件）。对于某些第三方库，ESP-IDF 提供专用的包装器和接口，以简化对第三方库的使用，或提高其与 ESP-IDF 其他功能的兼容性。某些情况下，第三方组件将直接呈现底层库的原始 API。
|
||||
@ -145,7 +145,7 @@ ESP-IDF 无法确保版本间的二进制兼容性。这意味着，如果使用
|
||||
* 为缓解安全问题做出的更改，或以更安全的行为取代不安全的默认行为的更改。
|
||||
* 从未运行成功的功能。例如，如果某个函数或枚举值从未成功使用，则可能会以修复的形式将其重命名或删除。这包括依赖于非功能芯片硬件功能的软件功能。
|
||||
* 未明确记录的意外或未定义行为可能会被修复或更改，如缺少参数范围验证。
|
||||
* 在菜单配置中 :doc:`Kconfig <kconfig>` 选项的位置。
|
||||
* 在菜单配置中 :ref:`Kconfig <project-configuration-guide>` 选项的位置。
|
||||
* 示例项目的位置和名称。
|
||||
|
||||
.. _指定初始化器: https://en.cppreference.com/w/c/language/struct_initialization
|
||||
|
||||
@ -13,7 +13,7 @@ API 参考
|
||||
error-codes
|
||||
network/index
|
||||
peripherals/index
|
||||
kconfig
|
||||
provisioning/index
|
||||
storage/index
|
||||
system/index
|
||||
kconfig-reference
|
||||
|
||||
1
docs/zh_CN/api-reference/kconfig-reference.rst
Normal file
1
docs/zh_CN/api-reference/kconfig-reference.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../en/api-reference/kconfig-reference.rst
|
||||
@ -1,86 +0,0 @@
|
||||
项目配置
|
||||
********
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
简介
|
||||
=====
|
||||
|
||||
ESP-IDF 使用基于 kconfiglib_ 的 esp-idf-kconfig_ 包，而 kconfiglib_ 是 Kconfig_ 系统的 Python 扩展。Kconfig 提供了编译时的项目配置机制，以及多种类型的配置选项（如整数、字符串和布尔值等）。Kconfig 文件指定了选项之间的依赖关系、默认值、组合方式等。
|
||||
|
||||
了解所有可用功能，请查看 Kconfig_ 和 `kconfiglib 扩展`_。
|
||||
|
||||
.. _project-configuration-menu:
|
||||
|
||||
项目配置菜单
|
||||
============
|
||||
|
||||
应用程序开发人员可以通过 ``idf.py menuconfig`` 构建目标，在终端中打开项目配置菜单。
|
||||
|
||||
更新后，此配置将保存在项目根目录的 ``sdkconfig`` 文件中。借助 ``sdkconfig``，应用程序构建目标将在构建目录中生成 ``sdkconfig.h`` 文件，并使得 ``sdkconfig`` 选项可用于项目构建系统和源文件。
|
||||
|
||||
使用 sdkconfig.defaults
|
||||
==============================
|
||||
|
||||
在某些情况下，例如 ``sdkconfig`` 文件处于版本控制状态时，构建系统可能会不便于更改 ``sdkconfig`` 文件。要避免上述情况，可以在构建系统中创建 ``sdkconfig.defaults`` 文件。该文件可以手动或自动创建，且构建系统永远不会对其进行更改。该文件包含所有不同于默认选项的重要选项，其格式与 ``sdkconfig`` 文件格式相同。如果用户记得所有已更改的配置，则可以手动创建 ``sdkconfig.defaults``，或运行 ``idf.py save-defconfig`` 命令来自动生成此文件。
|
||||
|
||||
``sdkconfig.defaults`` 创建后，用户可以删除 ``sdkconfig`` 或将其添加到版本控制系统的忽略列表中（例如 ``git`` 的 ``.gitignore`` 文件）。项目构建目标将自动创建 ``sdkconfig`` 文件，填充 ``sdkconfig.defaults`` 文件中的设置，并将其他设置配置为默认值。请注意，构建时 ``sdkconfig.defaults`` 中的设置不会覆盖 ``sdkconfig`` 的已有设置。了解更多信息，请查看 :ref:`custom-sdkconfig-defaults`。
|
||||
|
||||
Kconfig 格式规定
|
||||
====================
|
||||
|
||||
Kconfig 文件的格式规定如下：
|
||||
|
||||
- 在所有菜单中，选项名称的前缀需保持一致。目前，前缀长度应为至少 3 个字符。
|
||||
- 每级采用 4 个空格的缩进方式，子项需比父项多缩进一级。例如， ``menu`` 缩进 0 个空格，``menu`` 中的 ``config`` 则缩进 4 个空格， ``config`` 中的 ``help`` 缩进 8 个空格， ``help`` 下的文本缩进 12 个空格。
|
||||
- 行末不得出现尾随空格。
|
||||
- 选项最长为 50 个字符。
|
||||
- 每行最长为 120 个字符。
|
||||
|
||||
.. note::
|
||||
|
||||
菜单中不同配置的 ``help`` 小节默认视为 reStructuredText 格式，以便生成相应选项的参考文档。
|
||||
|
||||
格式检查器
|
||||
--------------
|
||||
|
||||
esp-idf-kconfig_ 软件包中的 ``kconfcheck`` 工具可以检查 Kconfig 文件是否符合上述格式规定。检查器会检查作为参数给出的所有 Kconfig 和 ``Kconfig.projbuild`` 文件，并生成一个后缀为 ``.new`` 的新文件，如有格式错误，便会在此文件中提供修改建议。注意，检查器不能解决所有格式问题，开发人员仍需终审并修改文件，使其通过测试。例如，在没有其他误导性格式的情况下，检查器能够更正缩进，但无法为菜单内选项提供常用的前缀。
|
||||
|
||||
``esp-idf-kconfig`` 软件包可以在 ESP-IDF 环境中使用。运行命令 ``python -m kconfcheck <path_to_kconfig_file>`` 即可调用检查工具。
|
||||
|
||||
如需了解更多内容，请参考 `esp-idf-kconfig 相关文档 <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`__。
|
||||
|
||||
.. _configuration-options-compatibility:
|
||||
|
||||
Kconfig 选项的向后兼容性
|
||||
================================
|
||||
|
||||
标准 Kconfig_ 工具会忽略 ``sdkconfig`` 中的未知选项。因此，如果开发人员对某些选项进行了自定义设置，但这些选项在 ESP-IDF 新版本中重新命名，标准 Kconfig_ 工具将忽略原有设置。以下功能可以避免上述情况：
|
||||
|
||||
1. 工具链使用 ``kconfgen`` 预处理 ``sdkconfig`` 文件。例如， ``menuconfig`` 会读取这些文件，从而保留旧选项设置。
|
||||
2. ``kconfgen`` 递归查找 ESP-IDF 目录中所有包含新旧 Kconfig 选项名称的 ``sdkconfig.rename`` 文件。在 ``sdkconfig`` 文件中，新选项将替换旧选项。针对单个目标的重命名可以放在特定目标的重命名文件 ``sdkconfig.rename.TARGET`` 中，其中 ``TARGET`` 是目标名称，例如 ``sdkconfig.rename.esp32s2``。
|
||||
3. ``kconfgen`` 通过添加兼容性语句列表（即经过修改后，将旧选项的值设置为新选项的值），后处理 ``sdkconfig`` 文件，并生成所有构建结果（ ``sdkconfig.h``、 ``sdkconfig.cmake`` 以及 ``auto.conf``）。如果用户在其代码中仍然使用旧选项，此举可以防止用户代码出现问题。
|
||||
4. ``kconfgen`` 会自动生成 :ref:`configuration-deprecated-options`。
|
||||
|
||||
``sdkconfig.rename`` 文件的结构如下：
|
||||
|
||||
* 以 ``#`` 开头的行和空行将被忽略。
|
||||
* 其他所有行应遵循以下格式之一：
|
||||
* ``CONFIG_DEPRECATED_NAME CONFIG_NEW_NAME``，其中 ``CONFIG_DEPRECATED_NAME`` 是旧配置名称，在较新的 ESP-IDF 版本中已更名为 ``CONFIG_NEW_NAME``。
|
||||
* ``CONFIG_DEPRECATED_NAME !CONFIG_NEW_INVERTED_NAME``，其中 ``CONFIG_NEW_INVERTED_NAME`` 是在较新的 ESP-IDF 版本中通过布尔反转 ``CONFIG_DEPRECATED_NAME`` 的逻辑值而引入的新配置名称。
|
||||
|
||||
.. _configuration-options-reference:
|
||||
|
||||
配置选项参考
|
||||
==================
|
||||
|
||||
以下小节包含由 Kconfig 文件自动生成的 ESP-IDF 可用选项列表。请注意，由于所选选项不同，下列某些选项可能在 ``menuconfig`` 界面中默认不可见。
|
||||
|
||||
按照惯例，所有选项名称均为大写字母加下划线。当 Kconfig 生成 ``sdkconfig`` 和 ``sdkconfig.h`` 文件时，选项名称会以 ``CONFIG_`` 为前缀。因此，如果 Kconfig 文件定义了 ``ENABLE_FOO`` 选项且 ``menuconfig`` 中选择了该选项，则 ``sdkconfig`` 和 ``sdkconfig.h`` 文件也将定义 ``CONFIG_ENABLE_FOO``。在以下小节中，选项名称也以 ``CONFIG_`` 为前缀，与源代码相同。
|
||||
|
||||
|
||||
.. include-build-file:: inc/kconfig.inc
|
||||
|
||||
.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
|
||||
.. _esp-idf-kconfig: https://pypi.org/project/esp-idf-kconfig/
|
||||
.. _kconfiglib: https://github.com/ulfalizer/Kconfiglib
|
||||
.. _kconfiglib 扩展: https://pypi.org/project/kconfiglib/#kconfig-extensions
|
||||
@ -47,7 +47,7 @@ ESP-IDF FreeRTOS
|
||||
|
||||
**然而，对于 ESP-IDF 中的所有 FreeRTOS 移植，FreeRTOSConfig.h 头文件被视为私有文件，用户不得修改。** 由于该选项在 ESP-IDF 中是必选项或不被支持，``FreeRTOSConfig.h`` 中的大量内核配置选项均为硬编码。所有用户可配置的内核配置选项都在 ``Component Config/FreeRTOS/Kernel`` 下的 menuconfig 中。
|
||||
|
||||
关于用户可配置内核选项的完整列表，参见 :doc:`/api-reference/kconfig`。下列为常用的内核配置选项：
|
||||
关于用户可配置内核选项的完整列表，参见 :ref:`Kconfig <project-configuration-guide>`。下列为常用的内核配置选项：
|
||||
|
||||
- :ref:`CONFIG_FREERTOS_UNICORE`：仅在核 0 上运行 FreeRTOS。注意，这 **不等同于运行原生 FreeRTOS。** 另外，此选项还可能影响除 :component:`freertos` 外其他组件的行为。关于在单核上运行 FreeRTOS 的更多内容，请参考 :ref:`freertos-idf-single-core` （使用 ESP-IDF FreeRTOS 时）或参考 Amazon SMP FreeRTOS 的官方文档，还可以在 ESP-IDF 组件中搜索 ``CONFIG_FREERTOS_UNICORE``。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user