build system: document `riotbuild.h` and deprecated `RIOT_MCU` #20566

maribu · 2024-04-11T12:40:30Z

Contribution description

This adds a place where the macros provided via riotbuild.h can be documented and where old macros can be deprecated.

This place was previously missing, as riotbuild.h is generated by converting -DFOO=BAR paramters from $(CFLAGS) to #define FOO BAR definitions in riotbuild.h. Hence, the is in Makefiles all over the code base and Doxygen really sucks at extracting info from Makefiles.

It also adds the MACRO_DEPRECATED macro, which can be used in the definition of deprecated macros to trigger a warning if (and only if) the defined macro is actually used.

Finally, the macro RIOT_MCU is readded as an alias to RIOT_CPU and marked as deprecated.

Testing procedure

Apply

diff --git a/examples/hello-world/main.c b/examples/hello-world/main.c
index 213128ac64..b3e8165130 100644
--- a/examples/hello-world/main.c
+++ b/examples/hello-world/main.c
@@ -26,7 +26,7 @@ int main(void)
     puts("Hello World!");
 
     printf("You are running RIOT on a(n) %s board.\n", RIOT_BOARD);
-    printf("This board features a(n) %s CPU.\n", RIOT_CPU);
+    printf("This board features a(n) %s CPU.\n", RIOT_MCU);
 
     return 0;
 }

and compile the hello world example with WERROR=0. It should build fine, but issue a warning about a deprecated macro:

$ make BOARD=nucleo-f767zi -C examples/hello-world WERROR=0
make: Entering directory '/home/maribu/Repos/software/RIOT/master/examples/hello-world'
Building application "hello-world" for "nucleo-f767zi" with CPU "stm32".

"make" -C /home/maribu/Repos/software/RIOT/master/pkg/cmsis/ 
/home/maribu/Repos/software/RIOT/master/examples/hello-world/main.c: In function 'main':
/home/maribu/Repos/software/RIOT/master/examples/hello-world/main.c:29:13: warning: Code is using a deprecated macro
   29 |     printf("This board features a(n) %s CPU.\n", RIOT_MCU);
      |             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"make" -C /home/maribu/Repos/software/RIOT/master/boards/common/init
"make" -C /home/maribu/Repos/software/RIOT/master/boards/nucleo-f767zi
"make" -C /home/maribu/Repos/software/RIOT/master/boards/common/nucleo
"make" -C /home/maribu/Repos/software/RIOT/master/core
"make" -C /home/maribu/Repos/software/RIOT/master/core/lib
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/stm32
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/cortexm_common
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/cortexm_common/periph
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/stm32/periph
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/stm32/stmclk
"make" -C /home/maribu/Repos/software/RIOT/master/cpu/stm32/vectors
"make" -C /home/maribu/Repos/software/RIOT/master/drivers
"make" -C /home/maribu/Repos/software/RIOT/master/drivers/periph_common
"make" -C /home/maribu/Repos/software/RIOT/master/sys
"make" -C /home/maribu/Repos/software/RIOT/master/sys/auto_init
"make" -C /home/maribu/Repos/software/RIOT/master/sys/div
"make" -C /home/maribu/Repos/software/RIOT/master/sys/libc
"make" -C /home/maribu/Repos/software/RIOT/master/sys/malloc_thread_safe
"make" -C /home/maribu/Repos/software/RIOT/master/sys/newlib_syscalls_default
"make" -C /home/maribu/Repos/software/RIOT/master/sys/pm_layered
"make" -C /home/maribu/Repos/software/RIOT/master/sys/preprocessor
"make" -C /home/maribu/Repos/software/RIOT/master/sys/stdio
"make" -C /home/maribu/Repos/software/RIOT/master/sys/stdio_uart
   text	  data	   bss	   dec	   hex	filename
   9440	   108	  2632	 12180	  2f94	/home/maribu/Repos/software/RIOT/master/examples/hello-world/bin/nucleo-f767zi/hello-world.elf
make: Leaving directory '/home/maribu/Repos/software/RIOT/master/examples/hello-world'

Issues/PRs references

#20397

riot-ci · 2024-04-11T14:21:06Z

Murdock results

✔️ PASSED

ae847ec build system: deprecate RIOT_MCU predefined macro

Success	Failures	Total	Runtime
1	0	1	01m:11s

Artifacts

Documentation preview

chrysn · 2024-04-11T14:21:12Z

Marked as ready-to-build because I'd like to see the generated config output. If this doesn't go through Doxygen, then the Doxygen commands in the header are just going-through-the-motions.

chrysn · 2024-04-11T14:25:24Z

dist/tools/genconfigheader/riotbuild-prefix.h

+
+/**
+ * @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
+ * ```
+ */
+#define MACRO_DEPRECATED    /* implementation */
+
+/**
+ * @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            RIOT_CPU
+
+#else /* DOXYGEN */
+
+#if defined(__GNUC__) || defined(__clang__)
+#  define MACRO_DEPRECATED _Pragma("GCC warning \"Code is using a deprecated macro\"")
+#else
+#  define MACRO_DEPRECATED
+#endif
+
+#define RIOT_MCU            MACRO_DEPRECATED RIOT_CPU
+
+#endif /* DOXYGEN */


While the top entries don't have corresponding actual implementations, I suggest grouping those that do with the implemenmtations. (Didn't check what the MACRO_DEPRECATED looks like in Doxygen, whether GNUC / clang is set there, but either way I think would be fine)

Suggested change

/**

* @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

* ```

*/

#define MACRO_DEPRECATED /* implementation */

/**

* @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 RIOT_CPU

#else /* DOXYGEN */

#if defined(__GNUC__) || defined(__clang__)

# define MACRO_DEPRECATED _Pragma("GCC warning \"Code is using a deprecated macro\"")

#else

# define MACRO_DEPRECATED

#endif

#define RIOT_MCU MACRO_DEPRECATED RIOT_CPU

#endif /* DOXYGEN */

#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(__GNUC__) || defined(__clang__)

# define MACRO_DEPRECATED _Pragma("GCC warning \"Code is using a deprecated macro\"")

#else

# 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

At least for the MACRO_DEPRECATED I'd rather not have the implementation shown in the Doxygen output, but rather an opaque implementation detail.

Doxygen doesn't understand the semantics of the #if defined(__GNUC__) || defined(__clang__) and would render a misleading simplification by picking one of the two definitions. If it would render some /* implementation */ instead, it would at least be obvious that anyone interested in the implementation details would have to look at the code instead.

I did move the doc now closer to the implementation, though.

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

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.

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`.

Teufelchen1 · 2024-04-30T16:35:18Z

LGTM

mguetschow

LGTM, nice addition!

I've looked at the generated docs and found that doxygen apparently automatically cuts after the first sentence. Changing e.g. to e.g., may or may not avoid this.

mguetschow · 2024-05-03T13:40:34Z

dist/tools/genconfigheader/riotbuild-prefix.h.in

+#define RIOT_VERSION "<YEAR_OF_RELEASE>.<MONTH_OF_RELEASE>-<POSTFIX>"
+
+/**
+ * @brief   The used RIOT version as machine readable number, e.g. for testing


Suggested change

* @brief The used RIOT version as machine readable number, e.g. for testing

* @brief The used RIOT version as machine readable number, e.g., for testing

IIRC, @brief may also only be one line.

mguetschow · 2024-05-03T13:40:55Z

dist/tools/genconfigheader/riotbuild-prefix.h.in

+
+#ifdef DOXYGEN
+/**
+ * @brief   The used RIOT version as human readable string literal, e.g. for


Suggested change

* @brief The used RIOT version as human readable string literal, e.g. for

* @brief The used RIOT version as human readable string literal, e.g., for

maribu requested review from miri64 and Teufelchen1 April 11, 2024 12:40

maribu requested review from aabadie and jia200x as code owners April 11, 2024 12:40

github-actions bot added Area: doc Area: Documentation Area: tools Area: Supplementary tools labels Apr 11, 2024

chrysn added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Apr 11, 2024

chrysn reviewed Apr 11, 2024

View reviewed changes

maribu added 3 commits April 11, 2024 17:11

build system: deprecate RIOT_MCU predefined macro

ae847ec

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`.

maribu force-pushed the buildsystem/document-riotbuild.h branch from 89790a3 to ae847ec Compare April 11, 2024 15:11

mguetschow added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR and removed CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels May 3, 2024

mguetschow requested changes May 3, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build system: document `riotbuild.h` and deprecated `RIOT_MCU` #20566

build system: document `riotbuild.h` and deprecated `RIOT_MCU` #20566

maribu commented Apr 11, 2024

riot-ci commented Apr 11, 2024 •

edited

chrysn commented Apr 11, 2024

chrysn Apr 11, 2024

maribu Apr 11, 2024

Teufelchen1 commented Apr 30, 2024

mguetschow left a comment

mguetschow May 3, 2024

miri64 May 3, 2024

mguetschow May 3, 2024

	* @brief The used RIOT version as machine readable number, e.g. for testing
	* @brief The used RIOT version as machine readable number, e.g., for testing

	* @brief The used RIOT version as human readable string literal, e.g. for
	* @brief The used RIOT version as human readable string literal, e.g., for

build system: document riotbuild.h and deprecated RIOT_MCU #20566

Are you sure you want to change the base?

build system: document riotbuild.h and deprecated RIOT_MCU #20566

Conversation

maribu commented Apr 11, 2024

Contribution description

Testing procedure

Issues/PRs references

riot-ci commented Apr 11, 2024 • edited

Murdock results

Artifacts

chrysn commented Apr 11, 2024

chrysn Apr 11, 2024

Choose a reason for hiding this comment

maribu Apr 11, 2024

Choose a reason for hiding this comment

Teufelchen1 commented Apr 30, 2024

mguetschow left a comment

Choose a reason for hiding this comment

mguetschow May 3, 2024

Choose a reason for hiding this comment

miri64 May 3, 2024

Choose a reason for hiding this comment

mguetschow May 3, 2024

Choose a reason for hiding this comment

build system: document `riotbuild.h` and deprecated `RIOT_MCU` #20566

build system: document `riotbuild.h` and deprecated `RIOT_MCU` #20566

riot-ci commented Apr 11, 2024 •

edited