Part 1
요약·해설
5개 field, 31개 변수·define 행과 bit packing·문자열 형식을 표로 보존했습니다.
Source
VERSION
Scopes
C · Kconfig · CMake
Fields
5
Boot
MCUboot 자동 반영
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
원문 SHA-256
0AB199789A10DCC8FDB8C3EA39642F3926B6052590142B4C040CEE46D7333DDE
.. _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.
Part 3
한국어 전문 번역
Application version 관리
Zephyr application은 kernel version system을 바탕으로 한 version 관리 기능을 제공합니다. Application이나 module code가 자동 생성 header를 include해 version을 읽을 수 있고 C/C++, Kconfig, CMake 세 scope에서 사용합니다. MCUboot 지원 target은 이 정보를 signed image version에 자동 반영하므로 수동 signing 단계가 필요 없습니다.
VERSION file
Application별 version은 application base, 즉 CMakeLists.txt가 있는 directory의 VERSION file에 둡니다.
VERSION_MAJOR =
VERSION_MINOR =
PATCHLEVEL =
VERSION_TWEAK =
EXTRAVERSION =숫자 field는 각각 한 byte로 제한되며 bootloader 등 사용처가 더 작은 범위를 요구할 수도 있습니다.
| Field | Data type |
|---|---|
VERSION_MAJOR | 숫자 0-255 |
VERSION_MINOR | 숫자 0-255 |
PATCHLEVEL | 숫자 0-255 |
VERSION_TWEAK | 숫자 0-255 |
EXTRAVERSION | 소문자 a-z와 숫자 0-9 |
CMake configuration 시 자동 처리되고 VERSION이 바뀔 때마다 확인되므로 CMake를 수동 재실행할 필요가 없습니다. 아래 설명은 다음 version을 사용합니다.
VERSION_MAJOR = 1
VERSION_MINOR = 2
PATCHLEVEL = 3
VERSION_TWEAK = 4
EXTRAVERSION = unstableCode에서 사용
Path 없이 app_version.h를 include하면 다음 define을 사용할 수 있습니다.
| Define | Type | Field 구성 | 예제 |
|---|---|---|---|
APPVERSION | 숫자 | major<<24 | minor<<16 | patch<<8 | tweak | 0x1020304 |
APP_VERSION_NUMBER | 숫자 | major<<16 | minor<<8 | patch | 0x10203 |
APP_VERSION_MAJOR | 숫자 | VERSION_MAJOR | 1 |
APP_VERSION_MINOR | 숫자 | VERSION_MINOR | 2 |
APP_PATCHLEVEL | 숫자 | PATCHLEVEL | 3 |
APP_TWEAK | 숫자 | VERSION_TWEAK | 4 |
APP_VERSION_STRING | Quoted string | major.minor.patch-extraversion | "1.2.3-unstable" |
APP_VERSION_EXTENDED_STRING | Quoted string | major.minor.patch-extraversion+tweak | "1.2.3-unstable+4" |
APP_VERSION_TWEAK_STRING | Quoted string | major.minor.patch+tweak | "1.2.3+4" |
APP_BUILD_VERSION | Unquoted string | Application repository의 git describe | v3.3.0-18-g2c85d9224fca |
Kconfig에서 사용
| Variable | Type | Field 구성 | 예제 |
|---|---|---|---|
$(VERSION_MAJOR) | 숫자 | VERSION_MAJOR | 1 |
$(VERSION_MINOR) | 숫자 | VERSION_MINOR | 2 |
$(PATCHLEVEL) | 숫자 | PATCHLEVEL | 3 |
$(VERSION_TWEAK) | 숫자 | VERSION_TWEAK | 4 |
$(APPVERSION) | 문자열 | major.minor.patch-extraversion | 1.2.3-unstable |
$(APP_VERSION_EXTENDED_STRING) | 문자열 | major.minor.patch-extraversion+tweak | 1.2.3-unstable+4 |
$(APP_VERSION_TWEAK_STRING) | 문자열 | major.minor.patch+tweak | 1.2.3+4 |
CMake에서 사용
| Variable | Type | Field 구성 | 예제 |
|---|---|---|---|
APPVERSION | Hex 숫자 | major<<24 | minor<<16 | patch<<8 | tweak | 0x1020304 |
APP_VERSION_NUMBER | Hex 숫자 | major<<16 | minor<<8 | patch | 0x10203 |
APP_VERSION_MAJOR | 숫자 | VERSION_MAJOR | 1 |
APP_VERSION_MINOR | 숫자 | VERSION_MINOR | 2 |
APP_PATCHLEVEL | 숫자 | PATCHLEVEL | 3 |
APP_VERSION_TWEAK | 숫자 | VERSION_TWEAK | 4 |
APP_VERSION_STRING | 문자열 | major.minor.patch-extraversion | 1.2.3-unstable |
APP_VERSION_EXTENDED_STRING | 문자열 | major.minor.patch-extraversion+tweak | 1.2.3-unstable+4 |
APP_VERSION_TWEAK_STRING | 문자열 | major.minor.patch+tweak | 1.2.3+4 |
MCUboot 지원 application
Target application이 MCUboot를 지원하도록 구성되고 signed image를 생성한다면 추가 설정 없이 application version이 image data에 자동 포함됩니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.