198 lines
15 KiB
ReStructuredText
198 lines
15 KiB
ReStructuredText
.. _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:: cfg
|
|
|
|
VERSION_MAJOR =
|
|
VERSION_MINOR =
|
|
PATCHLEVEL =
|
|
VERSION_TWEAK =
|
|
EXTRAVERSION =
|
|
|
|
Each field and the values it supports is described below. Zephyr limits the value of each numeric
|
|
field to a single byte (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 (0-255) |
|
|
+---------------+----------------------------------------+
|
|
| VERSION_MINOR | Numerical (0-255) |
|
|
+---------------+----------------------------------------+
|
|
| PATCHLEVEL | Numerical (0-255) |
|
|
+---------------+----------------------------------------+
|
|
| VERSION_TWEAK | Numerical (0-255) |
|
|
+---------------+----------------------------------------+
|
|
| 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:: cfg
|
|
|
|
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_TWEAK | Numerical | ``VERSION_TWEAK`` | 4 |
|
|
+-----------------------------+-------------------+------------------------------------------------------+-------------------------+
|
|
| APP_VERSION_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3-unstable" |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``EXTRAVERSION`` |br| | |
|
|
+-----------------------------+-------------------+------------------------------------------------------+-------------------------+
|
|
| APP_VERSION_EXTENDED_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3-unstable+4" |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``EXTRAVERSION`` |br| | |
|
|
| | | ``VERSION_TWEAK`` |br| | |
|
|
+-----------------------------+-------------------+------------------------------------------------------+-------------------------+
|
|
| APP_VERSION_TWEAK_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3+4" |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``VERSION_TWEAK`` |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`` | |
|
|
+--------------------------------+-----------+--------------------------+------------------+
|
|
| $(APP_VERSION_EXTENDED_STRING) | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable+4 |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``EXTRAVERSION``, |br| | |
|
|
| | | ``VERSION_TWEAK`` | |
|
|
+--------------------------------+-----------+--------------------------+------------------+
|
|
| $(APP_VERSION_TWEAK_STRING) | String | ``VERSION_MAJOR``, |br| | 1.2.3+4 |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``VERSION_TWEAK`` | |
|
|
+--------------------------------+-----------+--------------------------+------------------+
|
|
|
|
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`` | |
|
|
+-----------------------------+-----------------+---------------------------------------------------+------------------+
|
|
| APP_VERSION_EXTENDED_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable+4 |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``EXTRAVERSION``, |br| | |
|
|
| | | ``VERSION_TWEAK`` | |
|
|
+-----------------------------+-----------------+---------------------------------------------------+------------------+
|
|
| APP_VERSION_TWEAK_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3+4 |
|
|
| | | ``VERSION_MINOR``, |br| | |
|
|
| | | ``PATCHLEVEL``, |br| | |
|
|
| | | ``VERSION_TWEAK`` | |
|
|
+-----------------------------+-----------------+---------------------------------------------------+------------------+
|
|
|
|
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.
|