core/include/kernel_defines.h: add RIOT_VERSION_NUM macro

Makefile.include

@@ -476,6 +476,8 @@ endif
 # set some settings useful for continuous integration builds
 ifeq ($(RIOT_CI_BUILD),1)
     RIOT_VERSION ?= buildtest
+    # set a dummy version number
+    RIOT_VERSION_CODE ?= RIOT_VERSION_NUM\(2042,5,23,0\)
     ifneq ($(filter $(BOARD_INSUFFICIENT_MEMORY), $(BOARD)),)
         $(info CI-build: skipping link step)
         RIOTNOLINK:=1
@@ -504,9 +506,11 @@ include $(RIOTMAKE)/cflags.inc.mk
 
 # Include VERSION for releases
 -include $(RIOTBASE)/VERSION
+-include $(RIOTBASE)/EXTRAVERSION
 
 include $(RIOTMAKE)/git_version.inc.mk
 RIOT_VERSION ?= $(or $(GIT_VERSION),'UNKNOWN (builddir: $(RIOTBASE))')
+RIOT_EXTRAVERSION ?= 0
 
 # Deprecate using RIOT_VERSION_OVERRIDE but currently keep the behavior
 ifneq (,$(RIOT_VERSION_OVERRIDE))
@@ -514,6 +518,10 @@ ifneq (,$(RIOT_VERSION_OVERRIDE))
   RIOT_VERSION = $(RIOT_VERSION_OVERRIDE)
 endif
 
+# Generate machine readable RIOT VERSION macro
+RIOT_VERSION_CODE ?= $(shell echo ${RIOT_VERSION} | \
+                      sed -E 's/([0-9]+).([0-9]+).?([0-9]+)?.*/RIOT_VERSION_NUM\\\(\1,\2,0\3,${RIOT_EXTRAVERSION}\\\)/')
+
 # Set module by prepending APPLICATION name with 'application_'.
 # It prevents conflict with application and modules with the same name.
 APPLICATION_MODULE ?= application_$(APPLICATION)
@@ -978,6 +986,7 @@ $(RIOTBUILD_CONFIG_HEADER_C).in: FORCE | $(CLEAN)
 
 CFLAGS_WITH_MACROS += $(CFLAGS)
 CFLAGS_WITH_MACROS += -DRIOT_VERSION=\"$(RIOT_VERSION)\"
+CFLAGS_WITH_MACROS += -DRIOT_VERSION_CODE=$(RIOT_VERSION_CODE)
 # MODULE_NAME defines. Declared in 'makefiles/modules.inc.mk'
 CFLAGS_WITH_MACROS += $(EXTDEFINES)
 

core/include/kernel_defines.h

@@ -187,6 +187,34 @@ extern "C" {
  */
 #define IS_USED(module) IS_ACTIVE(module)
 
+/**
+ * @def         RIOT_VERSION_NUM(major, minor, patch, extra)
+ * @brief       Generates a 64 bit variable of a release version.
+ *              Comparisons to this only apply to released branches
+ *
+ *              To define @p extra add a file `EXTRAVERSION` to the RIOT root
+ *              with the content
+ *
+ *                  RIOT_EXTRAVERSION = <extra>
+ *
+ *              with `<extra>` being the number of your local version.
+ *              This can be useful if you are maintaining a downstream
+ *              release to base further work on.
+ *
+ * @warning     This is only intended to be used with external boards or
+ *              modules.
+ *              In-tree code must not make use of this macro.
+ *
+ * @param[in]   major   Mayor version of the release
+ * @param[in]   minor   Minor version of the release
+ * @param[in]   patch   Patch level of the release
+ * @param[in]   extra   Extra version, user defined
+ *
+ * @returns     A machine readable version variable
+ */
+#define RIOT_VERSION_NUM(major, minor, patch, extra)   \
+    (((0ULL + major) << 48) + ((0ULL + minor) << 32) + \
+     ((0ULL + patch) << 16) + (extra))
 /**
  * @cond INTERNAL
  */

makefiles/docker.inc.mk

@@ -59,6 +59,7 @@ export DOCKER_ENV_VARS += \
   PROGRAMMER \
   RIOT_CI_BUILD \
   RIOT_VERSION \
+  RIOT_VERSION_CODE \
   SCANBUILD_ARGS \
   SCANBUILD_OUTPUTDIR \
   SIZE \