1.. _app-version-details: 2 3Application version management 4****************************** 5 6Zephyr supports an application version management system for applications which is built around the 7system that Zephyr uses for its own version system management. This allows applications to define a 8version file and have application (or module) code include the auto-generated file and be able to 9access it, just as they can with the kernel version. This version information is available from 10multiple scopes, including: 11 12* Code (C/C++) 13* Kconfig 14* CMake 15* Shell 16 17which makes it a very versatile system for lifecycle management of applications. In addition, it 18can be used when building applications which target supported bootloaders (e.g. MCUboot) allowing 19images to be signed with correct version of the application automatically - no manual signing 20steps are required. 21 22VERSION file 23============ 24 25Application version information is set on a per-application basis in a file named :file:`VERSION`, 26which must be placed at the base directory of the application, where the CMakeLists.txt file is 27located. This is a simple text file which contains the various version information fields, each on 28a newline. The basic ``VERSION`` file has the following structure: 29 30.. code-block:: cfg 31 32 VERSION_MAJOR = 33 VERSION_MINOR = 34 PATCHLEVEL = 35 VERSION_TWEAK = 36 EXTRAVERSION = 37 38Each field and the values it supports is described below. Zephyr limits the value of each numeric 39field to a single byte (note that there may be further restrictions depending upon what the version 40is used for, e.g. bootloaders might only support some of these fields or might place limits on the 41maximum values of fields): 42 43+---------------+-------------------------------------------------------+ 44| Field | Data type | 45+---------------+-------------------------------------------------------+ 46| VERSION_MAJOR | Numerical (0-255) | 47+---------------+-------------------------------------------------------+ 48| VERSION_MINOR | Numerical (0-255) | 49+---------------+-------------------------------------------------------+ 50| PATCHLEVEL | Numerical (0-255) | 51+---------------+-------------------------------------------------------+ 52| VERSION_TWEAK | Numerical (0-255) | 53+---------------+-------------------------------------------------------+ 54| EXTRAVERSION | Alphanumerical (Lowercase a-z and 0-9) and "." or "-" | 55+---------------+-------------------------------------------------------+ 56 57When an application is configured using CMake, the version file will be automatically processed, 58and will be checked automatically each time the version is changed, so CMake does not need to be 59manually re-ran for changes to this file. 60 61For the sections below, examples are provided for the following :file:`VERSION` file: 62 63.. code-block:: cfg 64 65 VERSION_MAJOR = 1 66 VERSION_MINOR = 2 67 PATCHLEVEL = 3 68 VERSION_TWEAK = 4 69 EXTRAVERSION = unstable.5 70 71Use in code 72=========== 73 74To use the version information in application code, the version file must be included, then the 75fields can be freely used. The include file name is :file:`app_version.h` (no path is needed), the 76following defines are available: 77 78+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 79| Define | Type | Field(s) | Example | 80+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 81| APPVERSION | Numerical | ``VERSION_MAJOR`` (left shifted by 24 bits), |br| | 0x1020304 | 82| | | ``VERSION_MINOR`` (left shifted by 16 bits), |br| | | 83| | | ``PATCHLEVEL`` (left shifted by 8 bits), |br| | | 84| | | ``VERSION_TWEAK`` | | 85+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 86| APP_VERSION_NUMBER | Numerical | ``VERSION_MAJOR`` (left shifted by 16 bits), |br| | 0x10203 | 87| | | ``VERSION_MINOR`` (left shifted by 8 bits), |br| | | 88| | | ``PATCHLEVEL`` | | 89+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 90| APP_VERSION_MAJOR | Numerical | ``VERSION_MAJOR`` | 1 | 91+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 92| APP_VERSION_MINOR | Numerical | ``VERSION_MINOR`` | 2 | 93+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 94| APP_PATCHLEVEL | Numerical | ``PATCHLEVEL`` | 3 | 95+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 96| APP_TWEAK | Numerical | ``VERSION_TWEAK`` | 4 | 97+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 98| APP_VERSION_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3-unstable.5" | 99| | | ``VERSION_MINOR``, |br| | | 100| | | ``PATCHLEVEL``, |br| | | 101| | | ``EXTRAVERSION`` |br| | | 102+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 103| APP_VERSION_EXTENDED_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3-unstable.5+4" | 104| | | ``VERSION_MINOR``, |br| | | 105| | | ``PATCHLEVEL``, |br| | | 106| | | ``EXTRAVERSION`` |br| | | 107| | | ``VERSION_TWEAK`` |br| | | 108+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 109| APP_VERSION_TWEAK_STRING | String (quoted) | ``VERSION_MAJOR``, |br| | "1.2.3+4" | 110| | | ``VERSION_MINOR``, |br| | | 111| | | ``PATCHLEVEL``, |br| | | 112| | | ``VERSION_TWEAK`` |br| | | 113+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 114| APP_BUILD_VERSION | String (unquoted) | None (value of ``git describe --abbrev=12 --always`` | v3.3.0-18-g2c85d9224fca | 115| | | from application repository) | | 116+-----------------------------+-------------------+------------------------------------------------------+---------------------------+ 117 118Use in Kconfig 119============== 120 121The following variables are available for usage in Kconfig files: 122 123+--------------------------------+-----------+--------------------------+--------------------+ 124| Variable | Type | Field(s) | Example | 125+--------------------------------+-----------+--------------------------+--------------------+ 126| $(VERSION_MAJOR) | Numerical | ``VERSION_MAJOR`` | 1 | 127+--------------------------------+-----------+--------------------------+--------------------+ 128| $(VERSION_MINOR) | Numerical | ``VERSION_MINOR`` | 2 | 129+--------------------------------+-----------+--------------------------+--------------------+ 130| $(PATCHLEVEL) | Numerical | ``PATCHLEVEL`` | 3 | 131+--------------------------------+-----------+--------------------------+--------------------+ 132| $(VERSION_TWEAK) | Numerical | ``VERSION_TWEAK`` | 4 | 133+--------------------------------+-----------+--------------------------+--------------------+ 134| $(APPVERSION) | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable.5 | 135| | | ``VERSION_MINOR``, |br| | | 136| | | ``PATCHLEVEL``, |br| | | 137| | | ``EXTRAVERSION`` | | 138+--------------------------------+-----------+--------------------------+--------------------+ 139| $(APP_VERSION_EXTENDED_STRING) | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable.5+4 | 140| | | ``VERSION_MINOR``, |br| | | 141| | | ``PATCHLEVEL``, |br| | | 142| | | ``EXTRAVERSION``, |br| | | 143| | | ``VERSION_TWEAK`` | | 144+--------------------------------+-----------+--------------------------+--------------------+ 145| $(APP_VERSION_TWEAK_STRING) | String | ``VERSION_MAJOR``, |br| | 1.2.3+4 | 146| | | ``VERSION_MINOR``, |br| | | 147| | | ``PATCHLEVEL``, |br| | | 148| | | ``VERSION_TWEAK`` | | 149+--------------------------------+-----------+--------------------------+--------------------+ 150 151Use in CMake 152============ 153 154The following variable are available for usage in CMake files: 155 156+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 157| Variable | Type | Field(s) | Example | 158+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 159| APPVERSION | Numerical (hex) | ``VERSION_MAJOR`` (left shifted by 24 bits), |br| | 0x1020304 | 160| | | ``VERSION_MINOR`` (left shifted by 16 bits), |br| | | 161| | | ``PATCHLEVEL`` (left shifted by 8 bits), |br| | | 162| | | ``VERSION_TWEAK`` | | 163+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 164| APP_VERSION_NUMBER | Numerical (hex) | ``VERSION_MAJOR`` (left shifted by 16 bits), |br| | 0x10203 | 165| | | ``VERSION_MINOR`` (left shifted by 8 bits), |br| | | 166| | | ``PATCHLEVEL`` | | 167+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 168| APP_VERSION_MAJOR | Numerical | ``VERSION_MAJOR`` | 1 | 169+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 170| APP_VERSION_MINOR | Numerical | ``VERSION_MINOR`` | 2 | 171+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 172| APP_PATCHLEVEL | Numerical | ``PATCHLEVEL`` | 3 | 173+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 174| APP_VERSION_TWEAK | Numerical | ``VERSION_TWEAK`` | 4 | 175+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 176| APP_VERSION_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable.5 | 177| | | ``VERSION_MINOR``, |br| | | 178| | | ``PATCHLEVEL``, |br| | | 179| | | ``EXTRAVERSION`` | | 180+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 181| APP_VERSION_EXTENDED_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3-unstable.5+4 | 182| | | ``VERSION_MINOR``, |br| | | 183| | | ``PATCHLEVEL``, |br| | | 184| | | ``EXTRAVERSION``, |br| | | 185| | | ``VERSION_TWEAK`` | | 186+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 187| APP_VERSION_TWEAK_STRING | String | ``VERSION_MAJOR``, |br| | 1.2.3+4 | 188| | | ``VERSION_MINOR``, |br| | | 189| | | ``PATCHLEVEL``, |br| | | 190| | | ``VERSION_TWEAK`` | | 191+-----------------------------+-----------------+---------------------------------------------------+--------------------+ 192 193Use in MCUboot-supported applications 194===================================== 195 196No additional configuration needs to be done to the target application so long as it is configured 197to support MCUboot and a signed image is generated, the version information will be automatically 198included in the image data. 199 200Use in Shell 201============ 202 203When a shell interface is configured, the following commands are available to retrieve application version information: 204 205+----------------------+-----------------------------+-------------------------+ 206| Command | Variable | Example | 207+----------------------+-----------------------------+-------------------------+ 208| app version | APP_VERSION_STRING | 1.2.3-unstable.5 | 209+----------------------+-----------------------------+-------------------------+ 210| app version-extended | APP_VERSION_EXTENDED_STRING | 1.2.3-unstable.5+4 | 211+----------------------+-----------------------------+-------------------------+ 212| app build-version | APP_BUILD_VERSION | v3.3.0-18-g2c85d9224fca | 213+----------------------+-----------------------------+-------------------------+ 214