From 906e2c3234493f0b9c14259be6112afa7ffe4ffb Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Thu, 11 Apr 2024 11:27:55 +0200 Subject: [PATCH 1/3] 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 | 1 + .../genconfigheader/riotbuild-prefix.h.in | 65 +++++++++++++++++++ doc/doxygen/riot.doxyfile | 6 +- 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 dist/tools/genconfigheader/riotbuild-prefix.h.in diff --git a/dist/tools/genconfigheader/genconfigheader.sh b/dist/tools/genconfigheader/genconfigheader.sh index 581ceb55e0..1cdcc7e9e8 100755 --- a/dist/tools/genconfigheader/genconfigheader.sh +++ b/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.in" [ -n "${LTOFLAGS}" ] && echo "/* LTOFLAGS=${LTOFLAGS} */" diff --git a/dist/tools/genconfigheader/riotbuild-prefix.h.in b/dist/tools/genconfigheader/riotbuild-prefix.h.in new file mode 100644 index 0000000000..fdfab0ea9f --- /dev/null +++ b/dist/tools/genconfigheader/riotbuild-prefix.h.in @@ -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 ".-" + +/** + * @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(,,,) + +/** + * @brief Name of the RIOT application as string literal + * + * The string is defined in the applications `Makefile` using the `APPLICATION` + * variable. + */ +#define RIOT_APPLICATION "" + +/** + * @brief Name of the board the app is compiled for as string literal + */ +#define RIOT_BOARD "" + +/** + * @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 "" + +/** + * @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 */ +/** @} */ diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index aa2e1eba00..71f6b8428f 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -277,7 +277,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # Python is close enough that we can have Makefile comments starting with `##` # that are both recognized by Doxygen and comments to Make -EXTENSION_MAPPING = mk=Python +EXTENSION_MAPPING = mk=Python in=C # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -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.in # 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 @@ -807,6 +808,7 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.txt \ *.h \ + *.h.in \ *.hpp # The RECURSIVE tag can be used to specify whether or not subdirectories should From cadbbb6e9595782c0a4da39e858437f4359bfb87 Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Thu, 11 Apr 2024 14:06:27 +0200 Subject: [PATCH 2/3] build system: Add MACRO_DEPRECATED macro Adding this macro in the definition of a macro causes a warning about the deprecation to be emitted when used (and a build failure with `WERROR=1`). This is useful as no other means to deprecate preprocessor macros are provided. The macro will be defined empty for compilers that are not GCC or clang. --- .../genconfigheader/riotbuild-prefix.h.in | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/dist/tools/genconfigheader/riotbuild-prefix.h.in b/dist/tools/genconfigheader/riotbuild-prefix.h.in index fdfab0ea9f..71023a5bb2 100644 --- a/dist/tools/genconfigheader/riotbuild-prefix.h.in +++ b/dist/tools/genconfigheader/riotbuild-prefix.h.in @@ -62,4 +62,23 @@ */ #define CPU_RAM_SIZE /* RAM Size in Bytes */ #endif /* DOXYGEN */ + +/** + * @brief Mark a preprocessor macro as deprecated by including this + * macro in the definition + * + * Usage: + * ``` C + * /// @deprecated, use @ref BAR instead of FOO + * #define FOO MACRO_DEPRECATED BAR + * ``` + */ +#if defined(DOXYGEN) +# define MACRO_DEPRECATED /* implementation */ +#elif defined(__GNUC__) || defined(__clang__) +# define MACRO_DEPRECATED _Pragma("GCC warning \"Code is using a deprecated macro\"") +#else +# define MACRO_DEPRECATED +#endif + /** @} */ From 29e963bd952a0344d5ee58f4f88e03b33b620145 Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Thu, 11 Apr 2024 13:36:02 +0200 Subject: [PATCH 3/3] build system: deprecate RIOT_MCU predefined macro This re-adds `RIOT_MCU` as alias for `RIOT_CPU` and marks it as deprecated. That should make life easier for downstream apps that may still use `RIOT_CPU`. --- dist/tools/genconfigheader/riotbuild-prefix.h.in | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/dist/tools/genconfigheader/riotbuild-prefix.h.in b/dist/tools/genconfigheader/riotbuild-prefix.h.in index 71023a5bb2..d3562b06c5 100644 --- a/dist/tools/genconfigheader/riotbuild-prefix.h.in +++ b/dist/tools/genconfigheader/riotbuild-prefix.h.in @@ -81,4 +81,16 @@ # define MACRO_DEPRECATED #endif +/** + * @brief Name of the MCU the app is compiled for as string literal + * + * @deprecated Use @ref RIOT_CPU instead. This will be removed soonest in + * release 2025.04 + * + * This has been renamed to `RIOT_CPU` for consistency. Even though MCU would + * technically be the better name, CPU is used every else in the source code + * and folder structure. + */ +#define RIOT_MCU MACRO_DEPRECATED RIOT_CPU + /** @} */