Skip to content
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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Oct 1, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
906e2c3
build system: document riotbuid.h
maribu Apr 11, 2024
cadbbb6
build system: Add MACRO_DEPRECATED macro
maribu Apr 11, 2024
29e963b
build system: deprecate RIOT_MCU predefined macro
maribu Apr 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions dist/tools/genconfigheader/genconfigheader.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@
set -e

echo "/* DO NOT edit this file, your changes will be overwritten and won't take any effect! */"
echo "/* Generated from CFLAGS: $@ */"

Check failure on line 19 in dist/tools/genconfigheader/genconfigheader.sh

View workflow job for this annotation

GitHub Actions / static-tests 

Argument mixes string and array. Use * or separate argument. [SC2145]
cat "$(dirname "$0")/riotbuild-prefix.h.in"

[ -n "${LTOFLAGS}" ] && echo "/* LTOFLAGS=${LTOFLAGS} */"

Expand Down
96 changes: 96 additions & 0 deletions dist/tools/genconfigheader/riotbuild-prefix.h.in
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
/*
* 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 */

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

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

/** @} */
6 changes: 4 additions & 2 deletions doc/doxygen/riot.doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading