runtime: Add version.hpp

This is generated from src/runtime/version.hpp.in
See the file for the documentation.

Author: cassava

runtime/CMakeLists.txt

@@ -2,6 +2,11 @@ cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
 
 project(cloe-runtime LANGUAGES CXX)
 
+# NOTE: The variable CLOE_VERSION is used throughout this CMakeLists file
+# and is supplied from Conan or by hand on the command line.
+set(CLOE_VERSION "0.0.0-undefined" CACHE STRING "Cloe version as MAJOR.MINOR.PATCH string")
+set(CLOE_VERSION_U32 0 CACHE STRING "Cloe version as (MAJOR<<16)|(MINOR<<8)|PATCH integer")
+
 include(GNUInstallDirs)
 include(cmake/TargetLinting.cmake)
 
@@ -48,12 +53,14 @@ add_library(${alias} ALIAS ${target})
 set_target_properties(${target} PROPERTIES
     CXX_STANDARD 17
     CXX_STANDARD_REQUIRED ON
-    VERSION ${CLOE_PROJECT_VERSION}
+    VERSION ${CLOE_VERSION}
 )
 set_target_linting(${target})
+configure_file(src/cloe/version.hpp.in include/cloe/version.hpp @ONLY)
 target_include_directories(${target}
   PUBLIC
     "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>"
     "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
 )
 target_link_libraries(${target}
@@ -83,6 +90,7 @@ if(BUILD_TESTING)
 
     add_executable(test-cloe
         # find src -type f -name "*_test.cpp"
+        src/cloe/version_test.cpp
         src/cloe/utility/statistics_test.cpp
         src/cloe/utility/uid_tracker_test.cpp
     )
@@ -115,3 +123,6 @@ install(
     DIRECTORY include/
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+)

runtime/conanfile.py

@@ -3,6 +3,7 @@
 
 import os
 from pathlib import Path
+from semver import SemVer
 
 from conan import ConanFile
 from conan.tools import cmake, files, scm
@@ -54,11 +55,22 @@ def build_requirements(self):
 
     def layout(self):
         cmake.cmake_layout(self)
+        self.cpp.source.includedirs.append(os.path.join(self.folders.build, "include"))
 
     def generate(self):
+        # The version as a single 32-bit number takes the format:
+        #
+        #   (EPOCH << 24) | (MAJOR_VERSION << 16) | (MINOR_VERSION << 8) | PATCH_VERSION
+        #
+        # Each version consists of at most 8 bits, so 256 potential values, including 0.
+        # The epoch starts with 0, and is bumped after each version naming scheme.
+        semver = SemVer(self.version, True)
+        version_u32 = (0<<24) | (semver.major << 16) | (semver.minor << 8) | semver.patch
+
         tc = cmake.CMakeToolchain(self)
         tc.cache_variables["CMAKE_EXPORT_COMPILE_COMMANDS"] = True
-        tc.cache_variables["CLOE_PROJECT_VERSION"] = self.version
+        tc.cache_variables["CLOE_VERSION"] = self.version
+        tc.cache_variables["CLOE_VERSION_U32"] = version_u32
         tc.cache_variables["TargetLintingExtended"] = self.options.pedantic
         tc.generate()
 
@@ -90,6 +102,7 @@ def package_info(self):
         # mode and in the normal package mode:
         if not self.in_local_cache:
             self.cpp_info.builddirs.append(os.path.join(self.source_folder, "cmake"))
+            self.cpp_info.includedirs.append(os.path.join(self.build_folder, "include"))
             self.cpp_info.libs = ["cloe-runtime"]
         else:
             self.cpp_info.builddirs.append(os.path.join("lib", "cmake", "cloe"))

runtime/src/cloe/version.hpp.in

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2023 Robert Bosch GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * \file version.hpp
+ *
+ * This file just provides version information.
+ *
+ * We expect the CMakeLists.txt to define a constant CLOE_VERSION_U32,
+ * which takes the following format:
+ *
+ *   (EPOCH << 24) | (MAJOR_VERSION << 16) | (MINOR_VERSION << 8) | PATCH_VERSION
+ *
+ * Each version consists of at most 8 bits, so 256 potential values, including 0.
+ * The epoch starts with 0, and is bumped after each version naming scheme.
+ *
+ * The following macros are defined from CLOE_VERSION_U32:
+ *
+ * - CLOE_VERSION_EPOCH
+ * - CLOE_VERSION_MAJOR
+ * - CLOE_VERSION_MINOR
+ * - CLOE_VERSION_PATCH
+ *
+ * It's unlikely that EPOCH will ever be changed, but better safe than sorry.
+ *
+ * You can check for some Cloe version like so:
+ *
+ *     #if CLOE_VERSION_U32 < VERSION_U32(0, 1, 0, 0)
+ */
+
+#pragma once
+
+/**
+ * VERSION_U32 is a helper macro to create 32-bit unsigned
+ * Epoch-Major-Minor-Patch version integers.
+ *
+ * These can be then conveniently used to compare versions with the normal
+ * integer comparison operators.
+ *
+ * For example:
+ *
+ *     #if CLOE_VERSION_U32 >= VERSION_U32(1, 0, 0, 0)
+ *     #error "cloe epoch > 0 not supported"
+ *     #else if (CLOE_VERSION_U32 >= VERSION_U32(0, 1, 0, 0)) && (CLOE_VERSION_U32 < VERSION_U32(0, 1, 2, 0))
+ *       // Code for cloe versions between 1.0 and 1.1.*
+ *     #endif
+ *
+ * Note: This macro is defined with the same name and in the same way as
+ * fable/version.hpp and is not redefined here if already defined.
+ * As long as these macros exist it is unlikely that they will change
+ * in mechanism or form, as this would break all code that depends on
+ * version comparison.
+ */
+#ifndef VERSION_U32
+#define VERSION_U32(epoch, major, minor, patch) \
+    (((epoch) << 24) | ((major) << 16) | ((minor) << 8) | (patch))
+#endif
+
+#ifndef CLOE_VERSION
+#define CLOE_VERSION "@CLOE_VERSION@"
+#endif
+
+#ifndef CLOE_VERSION_U32
+#define CLOE_VERSION_U32 @CLOE_VERSION_U32@
+#endif
+
+#define CLOE_VERSION_EPOCH ((CLOE_VERSION_U32 >> 24) && 0xff)
+#define CLOE_VERSION_MAJOR ((CLOE_VERSION_U32 >> 16) && 0xff)
+#define CLOE_VERSION_MINOR ((CLOE_VERSION_U32 >> 8) && 0xff)
+#define CLOE_VERSION_PATCH ((CLOE_VERSION_U32 >> 0) && 0xff)

runtime/src/cloe/version_test.cpp

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2023 Robert Bosch GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <gtest/gtest.h>
+
+#include <fable/version.hpp>
+#include <cloe/version.hpp>
+
+TEST(fable_version, check_valid) {
+  // Ensure we can access the fable version information.
+  ASSERT_NE(FABLE_VERSION_U32, 0);
+  ASSERT_NE(FABLE_VERSION, "0.0.0-undefined");
+}
+
+TEST(cloe_version, check_valid) {
+  // Ensure we can access the cloe version, and it isn't undefined
+  ASSERT_NE(CLOE_VERSION_U32, 0);
+  ASSERT_NE(CLOE_VERSION, "0.0.0-undefined");
+}
+
+TEST(cloe_version, check_identical_to_fable_version) {
+  ASSERT_EQ(FABLE_VERSION_U32, CLOE_VERSION_U32);
+  ASSERT_EQ(FABLE_VERSION, CLOE_VERSION);
+}