From e243ee972da3befa20e0a153487896ef3128a179 Mon Sep 17 00:00:00 2001 From: krzychb Date: Sat, 2 Mar 2019 21:41:46 +0100 Subject: [PATCH 1/2] Updated documentation concerning 'PROJECT_VER' and 'PROJECT_NAME'. Closes https://github.com/espressif/esp-idf/issues/3115. --- docs/en/api-guides/build-system-cmake.rst | 10 ++++------ docs/en/api-guides/build-system.rst | 10 ++++------ docs/en/api-reference/system/system.rst | 4 ++-- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst index bda55800b..813857b61 100644 --- a/docs/en/api-guides/build-system-cmake.rst +++ b/docs/en/api-guides/build-system-cmake.rst @@ -344,8 +344,8 @@ The following variables are set at the project level, but available for use in c - ``IDF_TARGET``: Name of the target for which the project is being built. - ``PROJECT_VER``: Project version. - * If ``PROJECT_VER`` variable set in project CMakeLists.txt file, its value will be used. - * Else, if the ``${PROJECT_PATH}/version.txt`` exists, its contents will be used as ``PROJECT_VER``. + * If ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used. + * Else, if the ``$(PROJECT_PATH}/version.txt`` exists, its contents will be used as ``PROJECT_VER``. * Else, if the project is located inside a Git repository, the output of git describe will be used. * Otherwise, ``PROJECT_VER`` will be "1". @@ -426,10 +426,8 @@ Preprocessor Definitions The ESP-IDF build system adds the following C preprocessor definitions on the command line: -- ``ESP_PLATFORM`` ： Can be used to detect that build happens within ESP-IDF. -- ``IDF_VER`` ： Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. -- ``PROJECT_VER``: The project version, see `Preset Component Variables`_ for more details. -- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file. +- ``ESP_PLATFORM`` : Can be used to detect that build happens within ESP-IDF. +- ``IDF_VER`` : Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. Component Requirements ====================== diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 70eac2755..8c85c65d3 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -190,10 +190,10 @@ The following variables are set at the project level, but exported for use in th - ``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`. - ``PROJECT_VER``: Project version. -* If ``PROJECT_VER`` variable set in project Makefile file, its value will be used. -* Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. -* Else, if the project is located inside a Git repository, the output of git describe will be used. -* Otherwise, ``PROJECT_VER`` will be "1". + * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. + * Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. + * Else, if the project is located inside a Git repository, the output of git describe will be used. + * Otherwise, ``PROJECT_VER`` will be "1". If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug. @@ -309,8 +309,6 @@ ESP-IDF build systems adds the following C preprocessor definitions on the comma - ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF. - ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details. -- ``PROJECT_VER``: The project version, see `Preset Component Variables`_ for more details. -- ``PROJECT_NAME``: Name of the project, as set in project Makefile. Build Process Internals ----------------------- diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index 1a2f9c480..33fddc3bd 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -114,12 +114,12 @@ 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. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars. -To set version in your project manually you need set ``PROJECT_VER`` varible in your project Makefile/CMakeLists.txt: +To set version in your project manually you need to set ``PROJECT_VER`` variable in your project Makefile/CMakeLists.txt: * For Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including project.mk * For Cmake build system: in application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including project.cmake. -If ``PROJECT_VER`` variable did not set in project Makefile/CMakeLists.txt then it can retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. +If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to “1”. Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. API Reference ------------- From 88b153fcf7142fb596aafdfb51a63d3c8b7dd0c8 Mon Sep 17 00:00:00 2001 From: krzychb Date: Mon, 4 Mar 2019 20:26:19 +0100 Subject: [PATCH 2/2] Fixed fancy quotes --- docs/en/api-reference/system/system.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index 33fddc3bd..a15860e8a 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -119,7 +119,7 @@ To set version in your project manually you need to set ``PROJECT_VER`` variable * For Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including project.mk * For Cmake build system: in application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including project.cmake. -If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to “1”. Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. +If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. API Reference -------------