-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
build system: document riotbuild.h
and deprecated RIOT_MCU
#20566
build system: document riotbuild.h
and deprecated RIOT_MCU
#20566
Conversation
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. |
|
||
/** | ||
* @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 */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
/** | |
* @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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
89790a3
to
ae847ec
Compare
LGTM |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@maribu little reminder ;) |
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`.
f1f1681
to
29e963b
Compare
@mguetschow Adding the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, looks good indeed.
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 inriotbuild.h
. Hence, the is inMakefile
s all over the code base and Doxygen really sucks at extracting info fromMakefile
s.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 toRIOT_CPU
and marked as deprecated.Testing procedure
Apply
and compile the hello world example with
WERROR=0
. It should build fine, but issue a warning about a deprecated macro:Issues/PRs references
#20397