diff --git a/dist/scripts/lib-version.sh b/dist/scripts/lib-version.sh index dc7a07b93..a6b1c242e 100755 --- a/dist/scripts/lib-version.sh +++ b/dist/scripts/lib-version.sh @@ -5,31 +5,68 @@ # shellcheck source=./lib.sh . "$(dirname "$(realpath "$0")")/lib.sh" -## Autogenerated version pattern: -# -. - -# KERNEL_MAJVER's format: .. -# It's the standdard upstream linux kernel release version, -# eg. 3.10.0; 5.4.119; 5.16.0 +## Standardized kernel package version and uname are composed as follows: # -# KERNEL_RELVER's format: [.]. -# If is 0, indicates it's a snapshot, unofficial release. -# If is >=1, indicates it the n'th release of that kernel version. +# A valid tag: [PREFIX-]-[.] +# uname -r: -[.][+] +# RPM NVR: kepnel[-][-]-- +# -- # -# KERNEL_DIST: /tks/tlinux4/... -# Indicates this is a special build kernel. - -# NOTE: This versioning script fully respects the git tag if tag's -# major kernel version matches the version numbers in kernel Makefile - -# This naming style is compatible with Tencent Kernel public naming style. -# Take TK4 for example: +# Some NOTES about why we compose these string in above way: +# - Notice KERNEL_DIST is moved to N part of the RPM NVR, this is how TK3/TK4 release have been doing +# and that is correct because we need to distingush between kernel release streams. And there are +# things will break if we move it out of this part (mostly due to package name change). +# - RPM split the whole package name by '-', then recognize the right most part as R, second right +# most part is V, so KERNEL_MAJVER and KERNEL_RELVER can't contain '-'. +# - LOCALVER is commonly used to present variants of kernel, that is, using same kernel repo commit/version/tag, +# just built with a different config. +# A example is RPM pkg kernel-5.4.119-1 (uname 5.4.119-1) and kernel-debug-5.4.119-1 (uname 5.4.119-1+debug), +# the later one is same kernel built with more debug configs enabled. When kernel-5.4.119-1 run into unkown +# issues, kernel-debug-5.4.119-1 could be installed to do more diagnosis. +# - Notice LOCALVER is moved to "N" part of the RPM NVR, because adding to "V" or "R" part breaks kernel +# package versioning. A suffix, prefix or in-fix of "V" or "R" could cause the package or repo manager +# to make variants override each other, and fails the system unexpectly. For example, an debug kernel +# could be wrongly installed with a normal system wide package update, since the suffix made it had a +# high version number and it shares same Name with vanilla kernel. +# - Some old TK4 tag will have KERNEL_DIST as part of KERNEL_RELVER, we cover that too. # -# Merge base: git describe --tag make install version Generate version: -# 5.4.119 (master) 5.4.119-1-tlinux4-0007 5.4.119-1 5.4.119-1-tlinux4-0007 -# 5.4.119 (master) 5.4.119-1-tlinux4-0007-2-g884a77bf0ba6 5.4.119-1 5.4.119-0.20211115git1135ec008ef3.1-tlinux4-0007 -# 5.4.119 (master) 5.4.119-1-tlinux4-0007.subrelease 5.4.119-1 5.4.119-1-tlinux4-0007.subrelease -# 5.4.119 (master) 5.4.119-1-tlinux4-0007~rc1 5.4.119-1 5.4.119-1-tlinux4-0007~rc1 (*) +## More explanations of each field: +# +### PREFIX: /release/x86/aarch64/oc/.... +# - Could be some well-known string like "release", "x86", ..., could be used to make tags more distinguishable. +# +### KERNEL_MAJVER: .. +# - It's the standdard upstream linux kernel release version, presents in kernel's root Makefile, eg: +# VERSION = 5 +# PATCHLEVEL = 4 +# SUBLEVEL = 203 +# Which stands for kernel 5.4.203 +# +### KERNEL_RELVER: [0..][.] +# - If starts with 0, indicates it's a snapshot, unofficial release. Else it must be a tagged release. +# The string is automatically generated using git commit as versioning base for untagged +# test builds. +# - If EXTRAVERSION is non-empty, it must present here. +# - REL is a custom release string, should be alphanums be splitted by '.'. +# eg. 0011, 0009.12, 0011.prerelease1, ... +# eg. 2207.1.1, 2207.1.2, ... +# +# NOTE: due to historical reason, in KERNEL_RELVER, it could contain '-', but the final generated string that will be used in +# spec file and uname will always be converted to contain '.' only, to comply the RPM NVR naming style, also make things cleaner. +# +### KERNEL_DIST: /tks/tlinux4/stable/stream/... +# Indicates this is a special build kernel, will show up in RPM package name to distinguish different kernel release stream. +# Is configurable through the KDIST variable in dist/Makefile. +# +# NOTE: Due to historical reason, if KDIST is added as first part of KERNEL_RELVER's string, it will be move to tail. +# To make the KERNEL_RELVER part consistent between RPM name, tag and uname. +# +# Example: +# git describe --tag RPM uname -r +# 5.4.119-1-tlinux4-0007 kernel-tlinux4-5.4.119-1.0007 5.4.119-1.0007.tlinux4 +# 5.4.119-1-tlinux4-0007-2-g884a77bf0ba6 kernel-tlinux4-5.4.119-0.20211115git1135ec008ef3.1.0007 5.4.119-0.20211115git1135ec008ef3.1.0007.tlinux4 +# 5.4.119-1-tlinux4-0007.subrelease kernel-tlinux4-5.4.119-1.0007.subrelease 5.4.119-1.0007.subrelease.tlinux4 +# 5.4.119-1-tlinux4-0007~rc1 kernel-tlinux4-5.4.119-1.0007~rc1 5.4.119-1.0007~rc1.tlinux4 (*) # # NOTE: Sometime TK4's release version may go backwards, it's a known issue we have to live with. # TK4 used tag like 5.4.119-1-tlinux4-0007.prerelease to indicate a release candidate. @@ -40,7 +77,7 @@ # try use tilde symbol to indicate it's a RC. ## Macros and values: -# Standard four-part linux kernel version from kernel's Makefile +# Alias of four-part linux kernel version from kernel's Makefile KVERSION= KPATCHLEVEL= KSUBLEVEL= @@ -73,16 +110,15 @@ KGIT_RELEASE_NUM= KGIT_SUB_RELEASE_NUM= ### The formal kernel version and release - # Simulate `uname -r` output, which is always "$KVERSION.$KPATCHLEVEL.$KSUBLEVEL$KEXTRAVERSION" export KERNEL_UNAMER= # Basically: $KVERSION.$KPATCHLEVEL.$KSUBLEVEL (eg. 5.17.0, 5.16.3) export KERNEL_MAJVER= -# Release version, may contain $KEXTRAVERSION (eg. 1, 0.rc0, 0.20220329gita11bf64a6e8f) +# Release version (eg. 1, 0.rc0, 0.20220329gita11bf64a6e8f), see comments at the beginning of this file export KERNEL_RELVER= -# Kernel distro variable (eg. tks, tlinux4, ), with any leading "." or "-" removed +# Kernel distro variable (eg. tks, tlinux4, ), with any leading "." or "-" removed, see comments at the beginning of this file export KERNEL_DIST= -# Only used for make-release +# Only used for make-release sub command, get latest release tag of current commit export KERNEL_PREV_RELREASE_TAG= # Set if it's a tagged release @@ -105,6 +141,7 @@ _get_last_git_tag_of() { local last_tag tag local tagged + # If multiple tags presents, used the one specified by user for tag in $(git "$@" tag --points-at "$gitref"); do tagged=1 last_tag="$tag" @@ -129,6 +166,7 @@ _get_last_git_tag_of() { # $1: git tag or git commit, defaults to HEAD # $2: kernel source tree, should be a git repo +# Parse fondunmental kernel versioning info from Makefiles. get_kernel_code_version() { local gitref=${1:-HEAD} local repo=${2:-$TOPDIR} @@ -290,14 +328,14 @@ _search_for_release_tag() { # Get release info from git tag # -# We try to store the RPM NVR (Name, Version, Release) info's VR part in git tag +# We try to parse and verify RPM NVR (Name, Version, Release) info's 'VR' part using git tag or commit info # N: is always kernel # V: is kernel's major release version (eg. 5.18, 5.18.0, 5.17.2) # R: is a tokens seperated with '.' (eg 1[.KDIST], 2[.KDIST], 2.1[.KDIST], 0.rc1[.KDIST]) # could also be 0.YYYYMMDDgit for snapshot release. # But ideally all git tag are for formal release so snapshot tag shouldn't appear in repo. # -# A tag that contains VR is considered a release tag. +# With a tag that contains valid VR info it's considered a tag release, else it's a snapshot release. # # $1: git tag or git commit, defaults to HEAD # $2: kernel source tree, should be a git repo