espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-15 15:00:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(kconfiglib): Add Project and Component configuration guide

Browse Source 
* 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
2024-10-21 14:04:41 +02:00
parent cd21bdeb15
commit 1fcf006ec6
24 changed files with 431 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/en/api-guides/build-system.rst
View File

@@ -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.

1
docs/en/api-guides/index.rst
View File

@@ -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
View 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
View 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
View 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
View 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).