build system: document riotbuid.h

This adds a `riotbuild-prefix.h` that is added to the `riotbuild.h`
and processed by Doxygen. It solves two problems:

1. The pre-defined macros where previously fully undocumented, but
   may be useful to real world applications
2. It provides a place where backward compatibility aliases can be
   added with a deprecation notice

dist/tools/genconfigheader/genconfigheader.sh

@@ -17,6 +17,7 @@ set -e
 
 echo "/* DO NOT edit this file, your changes will be overwritten and won't take any effect! */"
 echo "/* Generated from CFLAGS: $@ */"
+cat "$(dirname "$0")/riotbuild-prefix.h"
 
 [ -n "${LTOFLAGS}" ] && echo "/* LTOFLAGS=${LTOFLAGS} */"
 

dist/tools/genconfigheader/riotbuild-prefix.h

@@ -0,0 +1,65 @@
+/*
+ * Copyright (C) 2024 Otto-von-Guericke-Universität Magdeburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser General
+ * Public License v2.1. See the file LICENSE in the top level directory for more
+ * details.
+ */
+
+/**
+ * @defgroup    config_riotbuild    riotbuild.h: Preprocessor Constants to Query the Build System Configuration
+ * @ingroup     config
+ *
+ * The RIOT build system generates a header file `riotbuild.h` that is included
+ * in every C compilation unit by passing the `-include` flag to the C compiler.
+ * Hence, it provides a set of macros that are unconditionally available and
+ * can be used by C code to query the build system configuration.
+ * @{
+ */
+
+#ifdef DOXYGEN
+/**
+ * @brief   The used RIOT version as human readable string literal, e.g. for
+ *          printing to stdio or writing to a log.
+ */
+#define RIOT_VERSION "<YEAR_OF_RELEASE>.<MONTH_OF_RELEASE>-<POSTFIX>"
+
+/**
+ * @brief   The used RIOT version as machine readable number, e.g. for testing
+ *          whether new APIs are available.
+ *
+ * @see     RIOT_VERSION_NUM
+ */
+#define RIOT_VERSION_CODE   RIOT_VERSION_NUM(<YEAR>,<MONTH>,<PATCH>,<EXTRA>)
+
+/**
+ * @brief   Name of the RIOT application as string literal
+ *
+ * The string is defined in the applications `Makefile` using the `APPLICATION`
+ * variable.
+ */
+#define RIOT_APPLICATION    "<RIOT_APP_NAME>"
+
+/**
+ * @brief   Name of the board the app is compiled for as string literal
+ */
+#define RIOT_BOARD          "<BOARD_NAME>"
+
+/**
+ * @brief   Name of the MCU the app is compiled for as string literal
+ *
+ * This is the name of the MCU family in terms of RIOT's peripheral drivers,
+ * or in other words, the folder name in the `cpu` folder in RIOT's repo root
+ * used.
+ */
+#define RIOT_CPU            "<CPU_FOLDER_NAME>"
+
+/**
+ * @brief   Size of the RAM in Bytes
+ *
+ * @warning Not every CPU family provides this, it will be undefined if
+ *          not provided
+ */
+#define CPU_RAM_SIZE        /* RAM Size in Bytes */
+#endif /* DOXYGEN */
+/** @} */

doc/doxygen/riot.doxyfile

@@ -785,7 +785,8 @@ INPUT                  = ../../doc.txt \
                          ../../LOSTANDFOUND.md \
                          ../../makefiles/pseudomodules.inc.mk \
                          ../../makefiles/blob.inc.mk \
-                         ../../sys/net/gnrc/routing/ipv6_auto_subnets/gnrc_ipv6_auto_subnets.c
+                         ../../sys/net/gnrc/routing/ipv6_auto_subnets/gnrc_ipv6_auto_subnets.c \
+                         ../../dist/tools/genconfigheader/riotbuild-prefix.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses