From 945b91ca2dde1a727b08fcb4fd23e3d196bdbbb2 Mon Sep 17 00:00:00 2001 From: Jamie McCrae Date: Wed, 2 Aug 2023 11:10:09 +0100 Subject: [PATCH] doc: build: Add details on application version system Adds details on how to use Zephyr's VERSION file for setting the version of an application. Signed-off-by: Jamie McCrae --- doc/build/index.rst | 1 + doc/build/version/index.rst | 164 ++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 doc/build/version/index.rst diff --git a/doc/build/index.rst b/doc/build/index.rst index 75be277c721..4a3e76be307 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -14,3 +14,4 @@ Build and Configuration Systems snippets/index.rst zephyr_cmake_package.rst sysbuild/index.rst + version/index.rst diff --git a/doc/build/version/index.rst b/doc/build/version/index.rst new file mode 100644 index 00000000000..de4e713c6b6 --- /dev/null +++ b/doc/build/version/index.rst @@ -0,0 +1,164 @@ +.. _app-version-details: + +Application version management +****************************** + +Zephyr supports an application version management system for applications which is built around the +system that Zephyr uses for its own version system management. This allows applications to define a +version file and have application (or module) code include the auto-generated file and be able to +access it, just as they can with the kernel version. This version information is available from +multiple scopes, including: + +* Code (C/C++) +* Kconfig +* CMake + +which makes it a very versatile system for lifecycle management of applications. In addition, it +can be used when building applications which target supported bootloaders (e.g. MCUboot) allowing +images to be signed with correct version of the application automatically - no manual signing +steps are required. + +VERSION file +============ + +Application version information is set on a per-application basis in a file named :file:`VERSION`, +which must be placed at the base directory of the application, where the CMakeLists.txt file is +located. This is a simple text file which contains the various version information fields, each on +a newline. The basic ``VERSION`` file has the following structure: + +.. code-block:: none + + VERSION_MAJOR = + VERSION_MINOR = + PATCHLEVEL = + VERSION_TWEAK = + EXTRAVERSION = + +Each field and the values it supports is described below (note that there may be further +restrictions depending upon what the version is used for, e.g. bootloaders might only support some +of these fields or might place limits on the maximum values of fields): + ++---------------+----------------------------------------+ +| Field | Data type | ++---------------+----------------------------------------+ +| VERSION_MAJOR | Numerical | ++---------------+----------------------------------------+ +| VERSION_MINOR | Numerical | ++---------------+----------------------------------------+ +| PATCHLEVEL | Numerical | ++---------------+----------------------------------------+ +| VERSION_TWEAK | Numerical | ++---------------+----------------------------------------+ +| EXTRAVERSION | Alphanumerical (Lowercase a-z and 0-9) | ++---------------+----------------------------------------+ + +When an application is configured using CMake, the version file will be automatically processed, +and will be checked automatically each time the version is changed, so CMake does not need to be +manually re-ran for changes to this file. + +For the sections below, examples are provided for the following :file:`VERSION` file: + +.. code-block:: none + + VERSION_MAJOR = 1 + VERSION_MINOR = 2 + PATCHLEVEL = 3 + VERSION_TWEAK = 4 + EXTRAVERSION = unstable + +Use in code +=========== + +To use the version information in application code, the version file must be included, then the +fields can be freely used. The include file name is :file:`app_version.h` (no path is needed), the +following defines are available: + ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| Define | Type | Field(s) | Example | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APPVERSION | Numerical | ``VERSION_MAJOR`` (left shifted by 24 bits), |br| | 0x1020304 | +| | | ``VERSION_MINOR`` (left shifted by 16 bits), |br| | | +| | | ``PATCHLEVEL`` (left shifted by 8 bits), |br| | | +| | | ``VERSION_TWEAK`` | | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_VERSION_NUMBER | Numerical | ``VERSION_MAJOR`` (left shifted by 16 bits), |br| | 0x10203 | +| | | ``VERSION_MINOR`` (left shifted by 8 bits), |br| | | +| | | ``PATCHLEVEL`` | | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_VERSION_MAJOR | Numerical | ``VERSION_MAJOR`` | 1 | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_VERSION_MINOR | Numerical | ``VERSION_MINOR`` | 2 | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_PATCHLEVEL | Numerical | ``PATCHLEVEL`` | 3 | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_VERSION_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3-unstable" | +| | | ``VERSION_MINOR``, |br| | | +| | | ``PATCHLEVEL``, |br| | | +| | | ``EXTRAVERSION`` |br| | | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ +| APP_BUILD_VERSION | String (unquoted) | None (value of ``git describe --abbrev=12 --always`` | v3.3.0-18-g2c85d9224fca | +| | | from application repository) | | ++--------------------+-------------------+------------------------------------------------------+-------------------------+ + +Use in Kconfig +============== + +The following variables are available for usage in Kconfig files: + ++------------------+-----------+-------------------------+----------------+ +| Variable | Type | Field(s) | Example | ++------------------+-----------+-------------------------+----------------+ +| $(VERSION_MAJOR) | Numerical | ``VERSION_MAJOR`` | 1 | ++------------------+-----------+-------------------------+----------------+ +| $(VERSION_MINOR) | Numerical | ``VERSION_MINOR`` | 2 | ++------------------+-----------+-------------------------+----------------+ +| $(PATCHLEVEL) | Numerical | ``PATCHLEVEL`` | 3 | ++------------------+-----------+-------------------------+----------------+ +| $(VERSION_TWEAK) | Numerical | ``VERSION_TWEAK`` | 4 | ++------------------+-----------+-------------------------+----------------+ +| $(APPVERSION) | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable | +| | | ``VERSION_MINOR``, |br| | | +| | | ``PATCHLEVEL``, |br| | | +| | | ``EXTRAVERSION`` | | ++------------------+-----------+-------------------------+----------------+ + +Use in CMake +============ + +The following variable are available for usage in CMake files: + ++--------------------+-----------------+---------------------------------------------------+----------------+ +| Variable | Type | Field(s) | Example | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APPVERSION | Numerical (hex) | ``VERSION_MAJOR`` (left shifted by 24 bits), |br| | 0x1020304 | +| | | ``VERSION_MINOR`` (left shifted by 16 bits), |br| | | +| | | ``PATCHLEVEL`` (left shifted by 8 bits), |br| | | +| | | ``VERSION_TWEAK`` | | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_VERSION_NUMBER | Numerical (hex) | ``VERSION_MAJOR`` (left shifted by 16 bits), |br| | 0x10203 | +| | | ``VERSION_MINOR`` (left shifted by 8 bits), |br| | | +| | | ``PATCHLEVEL`` | | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_VERSION_MAJOR | Numerical | ``VERSION_MAJOR`` | 1 | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_VERSION_MINOR | Numerical | ``VERSION_MINOR`` | 2 | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_PATCHLEVEL | Numerical | ``PATCHLEVEL`` | 3 | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_VERSION_TWEAK | Numerical | ``VERSION_TWEAK`` | 4 | ++--------------------+-----------------+---------------------------------------------------+----------------+ +| APP_VERSION_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable | +| | | ``VERSION_MINOR``, |br| | | +| | | ``PATCHLEVEL``, |br| | | +| | | ``EXTRAVERSION`` | | ++--------------------+-----------------+---------------------------------------------------+----------------+ + +Use in MCUboot-supported applications +===================================== + +No additional configuration needs to be done to the target application so long as it is configured +to support MCUboot and a signed image is generated, the version information will be automatically +included in the image data. + +The format used for signing is ``VERSION_MAJOR`` . ``VERSION_MINOR`` . ``PATCHLEVEL``, the tweak +version field is not currently used.