[cadcdev-svn-commits] [SCM] branch master updated. v2.0.0-1449-gd74badde

[falcovorbis <fal...@us...>]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "A pseudo Operating System for the Dreamcast.".

The branch, master has been updated
       via  d74baddec77b6b00535e065982bf2a80b0ed0ec0 (commit)
      from  ac4210b0617eecf8e808fe2da217b5ee5f389fb4 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit d74baddec77b6b00535e065982bf2a80b0ed0ec0
Author: Falco Girgis <gyr...@gm...>
Date:   Mon Jul 1 00:00:19 2024 -0500

    Added Versioning to KOS (#565)
    
    * Added versioning to KOS.

-----------------------------------------------------------------------

Summary of changes:
 doc/CHANGELOG                               |   1 +
 doc/Doxyfile                                |   2 +-
 environ_base.sh                             |   5 +
 include/kos.h                               |   1 +
 include/kos/version.h                       | 550 ++++++++++++++++++++++++++++
 kernel/Makefile                             |   7 +-
 kernel/arch/dreamcast/kernel/make_banner.sh |  11 +-
 kernel/version.c                            |  39 ++
 utils/version/version.sh                    |  20 +-
 9 files changed, 622 insertions(+), 14 deletions(-)
 create mode 100644 include/kos/version.h
 create mode 100644 kernel/version.c

diff --git a/doc/CHANGELOG b/doc/CHANGELOG
index 0755a8e5..251ed0bf 100644
--- a/doc/CHANGELOG
+++ b/doc/CHANGELOG
@@ -232,6 +232,7 @@ KallistiOS version 2.1.0 -----------------------------------------------
 - *** Fixes mutexes not working properly [PC]
 - DC  fs_dcload: Set errno on error in dcload_stat() [PC]
 - *** Create romdisks with bin2c instead of bin2o [PC]
+- *** Implemented versioning scheme for KOS API [FG && DH && LB]
 
 KallistiOS version 2.0.0 -----------------------------------------------
 - DC  Broadband Adapter driver fixes [Megan Potter == MP]
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 08b4359e..74abf0bf 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -199,7 +199,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line
 # such as
diff --git a/environ_base.sh b/environ_base.sh
index 017446da..bf754d4b 100644
--- a/environ_base.sh
+++ b/environ_base.sh
@@ -1,6 +1,11 @@
 # KallistiOS environment variable settings. These are the shared pieces
 # that are generated from the user config. Configure if you like.
 
+export KOS_VERSION_MAJOR=`awk '$2 == "KOS_VERSION_MAJOR"{print $3; exit}' ${KOS_BASE}/include/kos/version.h`
+export KOS_VERSION_MINOR=`awk '$2 == "KOS_VERSION_MINOR"{print $3; exit}' ${KOS_BASE}/include/kos/version.h`
+export KOS_VERSION_PATCH=`awk '$2 == "KOS_VERSION_PATCH"{print $3; exit}' ${KOS_BASE}/include/kos/version.h`
+export KOS_VERSION="${KOS_VERSION_MAJOR}.${KOS_VERSION_MINOR}.${KOS_VERSION_PATCH}"
+
 # Default the kos-ports path if it isn't already set.
 if [ -z "${KOS_PORTS}" ] ; then
     export KOS_PORTS="${KOS_BASE}/../kos-ports"
diff --git a/include/kos.h b/include/kos.h
index 32d905c7..4731e25f 100644
--- a/include/kos.h
+++ b/include/kos.h
@@ -32,6 +32,7 @@ __BEGIN_DECLS
 #include <string.h>
 #include <unistd.h>
 
+#include <kos/version.h>
 #include <kos/fs.h>
 #include <kos/fs_romdisk.h>
 #include <kos/fs_ramdisk.h>
diff --git a/include/kos/version.h b/include/kos/version.h
new file mode 100644
index 00000000..286f342a
--- /dev/null
+++ b/include/kos/version.h
@@ -0,0 +1,550 @@
+
+/* KallistiOS ##version##
+
+   include/kos/version.h
+   Copyright (C) 2024 Falco Girgis
+   Copyright (C) 2024 Donald Haase
+   Copyright (C) 2024 Luke Benstead
+
+*/
+
+/** \file
+    \brief API versioning and requirements checks.
+    \ingroup version
+
+    This file contains the current KOS version information as well as utilities
+    for enforcing and checking for certain version ranges.
+
+    \author Falco Girgis
+    \author Donald Haase
+    \author Luke Benstead
+*/
+
+#ifndef __KOS_VERSION_H
+#define __KOS_VERSION_H
+
+/** \defgroup version Versioning
+    \brief            KOS version information and utility API
+
+    This API provides both access to the current KOS version as well as
+    utilities that can be used to check for or require a particular version.
+
+    ## Format
+    KOS's versioning scheme follows the following format: `major.minor.patch`
+    where a change in the revision number of any component typically suggests:
+
+    |Component|Description
+    |---------|-----------
+    |Major    |Massive, sweeping changes to major APIs and subsystems.
+    |Minor    |Small, incremental updates and new features.
+    |Patch    |Usually simply bugfixes.
+
+    ## Version Types
+    The versioning information is split into two different groups:
+        
+    |Version Type|Description
+    |------------|-----------
+    |\ref version_comptime|The version of KOS your code is being compiled against.
+    |\ref version_runtime |The version of KOS your code has been linked against.
+
+    Ideally, these two versions would be the same; however, it is possible for
+    them to differ in certain circumstances:
+
+    - You pulled down a new version of KOS, rebuilt your code, but did not
+        rebuild the KOS library.
+    - You use dynamically loaded libraries which may have been built
+        against different versions of KOS than what you are currently
+        linking against.
+
+    ## Version Checking
+    Version checks are handled differently depending on whether you want to use
+    the version at compile-time or run-time.
+
+    |Version Type|Mechanism
+    |------------|-----------
+    |\ref version_comptime_check "Compile-Time"|Preprocessor directives, conditional compilation.
+    |\ref version_runtime_check "Run-Time"|if statements, conditional branches
+
+    \warning
+    It is very important that you use the provided version-check mechanisms when
+    comparing two different versions together, as no assurance is made that
+    versions can be correctly compared as integers.
+
+    ## App Versioning
+    The same \ref version_utils used to implement the KOS versioning
+    API are available as part of the public API so that they may be used to 
+    implement your own similar versioning scheme at the app-level.
+
+    @{
+*/
+
+/** \defgroup version_comptime  Compile-Time 
+    \brief    API providing compile-time KOS version and utilties.
+
+    This API is is specifically for the compile-time versioning. As such,
+    its API is implemented via C macros, which can easily be used with the
+    preprocessor for conditional compilation.
+
+    @{
+*/
+
+/** \defgroup version_comptime_current Current
+    \brief    Current compile-time version of KOS
+
+    These macros provide information about the current version of KOS at
+    compile-time. 
+
+    @{
+*/
+
+#define KOS_VERSION_MAJOR   2   /**< KOS's current major revision number. */
+#define KOS_VERSION_MINOR   0   /**< KOS's current minor revision number. */
+#define KOS_VERSION_PATCH   0   /**< KOS's current patch revision number. */
+
+/** KOS's current version as an integer ID. */
+#define KOS_VERSION \
+    KOS_VERSION_MAKE(KOS_VERSION_MAJOR, KOS_VERSION_MINOR, KOS_VERSION_PATCH)
+
+/** KOS's current version as a string literal. */
+#define KOS_VERSION_STRING \
+    KOS_VERSION_MAKE_STRING(KOS_VERSION_MAJOR, \
+                            KOS_VERSION_MINOR, \
+                            KOS_VERSION_PATCH)
+/** @} */
+
+/** \defgroup version_comptime_check Checks
+    \brief    Compile-time checks against KOS's current version.
+
+    This API provides several utility macros to check for a particular
+    exact, min, or max compile-time version for KOS. 
+    
+    They are meant to be used with the preprocessor like so:
+
+    \code{.c}
+        #if KOS_VERSION_MIN(2, 0, 0)
+            // Do something requiring at least KOS 2.0.0 to compile.
+        #elif KOS_VERSION_BELOW(2, 5, 1)
+            // Do something that was deprecated in KOS 2.5.1.
+        #elif KOS_VERSION_IS(3, 1, 2)
+            // Do something for an exact version match.
+        #endif
+    \endcode
+
+    @{
+*/
+
+/** Compile-time check for being above a given KOS version.
+
+    Checks to see whether the current KOS version is higher than the given
+    version.
+
+    \param  major    Major version component.
+    \param  minor    Minor version component.
+    \param  patch    Patch version component.
+
+    \retval true     KOS's version is higher.
+    \retval false    KOS's version is the same or lower.
+
+*/
+#define KOS_VERSION_ABOVE(major, minor, patch) \
+    KOS_VERSION_MAKE_ABOVE(major, minor, patch, KOS_VERSION)
+
+/** Compile-time check for a minimum KOS version.
+    
+    Checks to see whether the current KOS version is the same or higher than
+    the given version.
+
+    \param  major    Major version component.
+    \param  minor    Minor version component.
+    \param  patch    Patch version component.
+
+    \retval true     KOS's version is the same or higher.
+    \retval false    KOS's version is lower.
+
+*/
+#define KOS_VERSION_MIN(major, minor, patch) \
+    KOS_VERSION_MAKE_MIN(major, minor, patch, KOS_VERSION)
+
+/** Compile-time check for an exact KOS version.
+
+    Checks to see whether the current KOS version matches the given version.
+
+    \param  major    Major version component.
+    \param  minor    Minor version component.
+    \param  patch    Patch version component.
+
+    \retval true     KOS's version is the same.
+    \retval false    KOS's version is different.
+*/
+#define KOS_VERSION_IS(major, minor, patch) \
+    KOS_VERSION_MAKE_IS(major, minor, patch, KOS_VERSION)
+
+/** Compile-time check for a maximum KOS version.
+
+    Checks to see whether the current KOS version is the same or lower than the
+    given version.
+
+    \param  major    Major version component.
+    \param  minor    Minor version component.
+    \param  patch    Patch version component.
+
+    \retval true     KOS's version is the the same or lower.
+    \retval false    KOS's version is higher.
+*/
+#define KOS_VERSION_MAX(major, minor, patch) \
+    KOS_VERSION_MAKE_MAX(major, minor, patch, KOS_VERSION)
+
+/** Compile-time check for being below a given KOS version.
+
+    Checks to see whether the current KOS version is lower than the given
+    version.
+
+    \param  major    Major version component.
+    \param  minor    Minor version component.
+    \param  patch    Patch version component.
+
+    \retval true     KOS's version is lower.
+    \retval false    KOS's version is the same or higher.
+
+*/
+#define KOS_VERSION_BELOW(major, minor, patch) \
+    KOS_VERSION_MAKE_BELOW(major, minor, patch, KOS_VERSION)
+
+/** @} */
+
+/** @} */
+
+/** \defgroup version_utils Utilities
+    \brief    Utilities for creating version info and checks.
+
+    These are generalized utilities for construction of version info at
+    compile-time. They are what KOS uses internally, but they can also
+    be used externally to generate version info and version check utilities
+    for your application.
+
+    \note
+    The ranges for the components of a version ID are as follows:
+
+    |Component|Bits|Range
+    |---------|----|------
+    |Major    |8   |0-255
+    |Minor    |8   |0-255
+    |Patch    |8   |0-255
+
+    @{
+*/
+
+/** \name  Version Encoding
+    \brief Utilities for encoding a version from its components.
+    @{
+*/
+/** Creates a version identifier from its constituents. 
+
+    Used to create a version identifier at compile-time from its components.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+
+    \returns        Packed version identifier.
+*/
+#define KOS_VERSION_MAKE(major, minor, patch) \
+    ((kos_version_t)((major) << 16) | ((minor) << 8) | (patch))
+
+/** Creates a version string from its constituents. 
+
+    Used to create a compile-time string literal from version components.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    patch versoin component.
+
+    \returns        `NULL`-terminated C string literal in the format
+                    `major.minor.patch`
+*/
+#define KOS_VERSION_MAKE_STRING(major, minor, patch) \
+    KOS_STRINGIFY(major) "." \
+    KOS_STRINGIFY(minor) "." \
+    KOS_STRINGIFY(patch)
+/** @} */
+
+/** \name  Version Checking
+    \brief Utilities for creating version checks.
+    @{
+*/
+/** Creates a generic check against a given version.
+
+    Bottom-level macro used to create all compile-time comparison checks against
+    other versions.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param op       Integer comparison operator (`<=`, `>=`, `!=`, `==`, etc)/
+    \param version  Encoded version to compare against.
+
+    \returns        Boolean value for the given version compared against
+                    \p version using \p op.
+*/
+#define KOS_VERSION_MAKE_COMPARISON(major, minor, patch, op, version) \
+    (KOS_VERSION_MAKE(major, minor, patch) op (version & 0xffffff))
+
+/** Creates a check for being above a given version.
+
+    Used to create a compile-time greater-than check against another version.
+
+    \note
+    Simply wrap this in a function to implement a runtime check.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param version  The reference version ID.
+
+    \retval true    The given version is above \p version.
+    \retval false   The given version is at or below \p version.
+*/
+#define KOS_VERSION_MAKE_ABOVE(major, minor, patch, version) \
+    (KOS_VERSION_MAKE_COMPARISON(major, minor, patch, >, version))
+
+/** Creates a minimum version check. 
+
+    Used to create a compile-time minimum version check.
+
+    \note
+    Simply wrap this in a function to implement a runtime check.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param version  The minimum version ID.
+
+    \retval true    The given version is at or above \p version.
+    \retval false   The given version is below \p version.
+*/
+#define KOS_VERSION_MAKE_MIN(major, minor, patch, version) \
+    (KOS_VERSION_MAKE_COMPARISON(major, minor, patch, >=, version))
+
+/** Creates an exact version check. 
+
+    Used to create a compile-time exact version check.
+
+    \note
+    Simply wrap this in a function to implement a runtime check.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param version  The exact version ID to match.
+
+    \retval true    The given version matches \p version exactly.
+    \retval false   The given version does not match \p version.
+*/
+#define KOS_VERSION_MAKE_IS(major, minor, patch, version) \
+    (KOS_VERSION_MAKE_COMPARISON(major, minor, patch, ==, version))
+
+/** Creates a maximum version check. 
+
+    Used to create a compile-time maximum version check.
+
+    \note
+    Simply wrap this in a function to implement a runtime check.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param version  The maximum version ID.
+
+    \retval true    The given version is at or below \p version.
+    \retval false   The given version is above \p version.
+
+*/
+#define KOS_VERSION_MAKE_MAX(major, minor, patch, version) \
+    (KOS_VERSION_MAKE_COMPARISON(major, minor, patch, <=, version))
+
+/** Creates a check for being below a given version.
+
+    Used to create a compile-time less-than check against another version.
+
+    \note
+    Simply wrap this in a function to implement a runtime check.
+
+    \param major    Major version component.
+    \param minor    Minor version component.
+    \param patch    Patch version component.
+    \param version  The reference version ID.
+
+    \retval true    The given version is below \p version.
+    \retval false   The given version is at or above \p version.
+*/
+#define KOS_VERSION_MAKE_BELOW(major, minor, patch, version) \
+    (KOS_VERSION_MAKE_COMPARISON(major, minor, patch, <, version))
+/** @} */
+
+/** \cond INTERNAL */
+#define KOS_STRINGIFY(str) #str
+/** \endcond */
+
+/** @} */
+
+#include <kos/cdefs.h>
+__BEGIN_DECLS
+
+#include <stdint.h>
+#include <stdbool.h>
+
+/** \defgroup version_runtime  Run-Time 
+    \brief    API providing run-time KOS version and utilties.
+
+    This API is is specifically for the run-time versioning. As such this
+    API operates on the KOS version that was linked against and is not suited
+    for use at the preprocessor level.
+
+    @{
+*/
+
+/** Type of a KOS version identifier. 
+
+    This identifier packs the 3 version components into a single opaque ID.
+
+    \warning
+    It is not safe to compare two different versions together as if they were
+    regular integral types. You must use the Run-time
+    \ref version_runtime_check API.
+*/
+typedef uint32_t kos_version_t;
+
+/** \defgroup version_runtime_current Current
+    \brief    Current run-time version of KOS
+
+    These functions provide information about the current version of KOS at
+    run-time (ie the version you have linked against).
+
+    @{
+*/
+
+/** Returns the current KOS version ID at run-time.
+
+    This function is used to fetch the current KOS version ID at run-time,
+    meaning it will return the version of KOS you have \e linked to, rather
+    than the one you were necessarily compiling against.
+
+    \returns     KOS's current version identifier
+*/
+kos_version_t kos_version(void);
+
+/** Returns the string representation of the current KOS version at run-time
+
+    This function fetches the current run-time version of KOS as a string.
+
+    \note
...<truncated>...


hooks/post-receive
-- 
A pseudo Operating System for the Dreamcast.