Merge branch 'feature/idf_version_header' into 'master'

esp_common: add esp_idf_version.h header to define IDF version

Closes IDF-253

See merge request idf/esp-idf!4596

docs/Doxyfile

@@ -183,6 +183,8 @@ INPUT = \
     ## Base MAC address
     ## NOTE: for line below header_file.inc is not used
     ../../components/esp_common/include/esp_system.h \
+    ## IDF version
+    ../../components/esp_common/include/esp_idf_version.h \
     ##
     ## ULP Coprocessor - API Guides
     ##

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

@@ -350,6 +350,7 @@ from the component CMakeLists.txt:
 - ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable.
 - ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
 - ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
+- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``IDF_VERSION_*`` variables, but different ``IDF_VER`` values.
 - ``IDF_TARGET``: Name of the target for which the project is being built.
 - ``PROJECT_VER``: Project version.
 

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

@@ -188,6 +188,7 @@ The following variables are set at the project level, but exported for use in th
 - ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
 - ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
 - ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
+- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values.
 - ``PROJECT_VER``: Project version. 
 
   * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used.

docs/en/api-reference/system/system.rst

@@ -109,6 +109,21 @@ SDK version
 
 :cpp:func:`esp_get_idf_version` returns a string describing the IDF version which was used to compile the application. This is the same value as the one available through ``IDF_VER`` variable of the build system. The version string generally has the format of ``git describe`` output.
 
+To get the version at build time, additional version macros are provided. They can be used to enable or disable parts of the program depending on IDF version.
+
+* :c:macro:`ESP_IDF_VERSION_MAJOR`, :c:macro:`ESP_IDF_VERSION_MINOR`, :c:macro:`ESP_IDF_VERSION_PATCH` are defined to integers representing major, minor, and patch version.
+
+* :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks:
+  
+  .. code-block:: c
+
+      #include "esp_idf_version.h"
+
+      #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
+          // enable functionality present in IDF v4.0
+      #endif
+
+
 App version
 -----------
 Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. 
@@ -125,5 +140,6 @@ API Reference
 -------------
 
 .. include:: /_build/inc/esp_system.inc
+.. include:: /_build/inc/esp_idf_version.inc
 
 

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

@@ -315,6 +315,7 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指
 - ``COMPONENTS``：此次构建中包含的所有组件的名称，具体格式为用分号隔开的 CMake 列表。
 - ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :doc:`Kconfig </api-reference/kconfig>`。
 - ``IDF_VER``：ESP-IDF 的 git 版本号，由 ``git describe`` 命令生成。
+- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。
 - ``IDF_TARGET``：项目的硬件目标名称。
 - ``PROJECT_VER``：项目版本号。
 

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

@@ -176,6 +176,7 @@ ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进
 -  ``CC``，``LD``，``AR``，``OBJCOPY``： gcc xtensa 交叉编译工具链中每个工具的完整路径。
 -  ``HOSTCC``，``HOSTLD``，``HOSTAR``： 主机本地工具链中每个工具的全名。
 -  ``IDF_VER``： ESP-IDF 的版本号，可以通过检索 ``$(IDF_PATH)/version.txt`` 文件（假如存在的话）或者使用 git 命令 ``git describe`` 来获取。这里推荐的格式是在一行中指定主 IDF 的发布版本号，例如标记为 ``v2.0`` 的发布版本或者是标记任意一次提交记录的 ``v2.0-275-g0efaa4f``。应用程序可以通过调用 :cpp:func:`esp_get_idf_version` 函数来使用该变量。
+-  ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。
 
 如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。