From 00c0c8f1825555fd201dfcc58915817e065b7c96 Mon Sep 17 00:00:00 2001 From: AnnsAnn Date: Tue, 5 Aug 2025 11:47:26 +0200 Subject: [PATCH] doc/starlight: generate governance & code_of_conduct, move c++ guide --- doc/.gitignore | 1 + doc/doxygen/src/using-cpp.md | 55 ++----------------- doc/guides/c_tutorials/using_cpp.md | 51 +++++++++++++++++ doc/starlight/Makefile | 17 +++++- doc/starlight/astro.config.mjs | 3 + .../templates/CODE_OF_CONDUCT.template.md | 5 ++ .../templates/GOVERNANCE.template.md | 5 ++ 7 files changed, 85 insertions(+), 52 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/guides/c_tutorials/using_cpp.md create mode 100644 doc/starlight/templates/CODE_OF_CONDUCT.template.md create mode 100644 doc/starlight/templates/GOVERNANCE.template.md diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000..a998d9b2e9 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +guides/generated diff --git a/doc/doxygen/src/using-cpp.md b/doc/doxygen/src/using-cpp.md index bdecd024bd..74d84ff020 100644 --- a/doc/doxygen/src/using-cpp.md +++ b/doc/doxygen/src/using-cpp.md @@ -1,52 +1,5 @@ -Using C++ in RIOT {#using-cpp} -================= +Using C++ in RIOT {#using-cpp} +================== -[TOC] - -Levels of Support {#levels-of-support} -================= - -A CPU in RIOT can have three levels of support for C++ code: - -1. No support for C++ at all -2. C++ is supported, but no libstdc++ implementation is available -3. C++ is supported and a libstdc++ implementation is available - -The reason for missing or only partial C++ support can be one (or more) of -the following: - -- No libstdc++ implementation for the target platform is available to RIOT, or - the official RIOT docker image is missing it -- Missing toolchain support for a given target platform -- The C++ toolchain requires library code (such as constructor guards for the - thread safe initialization of statically allocated instances) or hooks in - the startup process to perform initialization - -Using C++ -========= - -In order for C++ code to compile with RIOT, the following needs to be done: - -- All C++ files must have the file extension `.cpp`, all C++ headers `.hpp` - - For external code, overwriting the make variable `SRCXXEXT` e.g. to - `cxx` can be used to compile C++ files with other extensions, e.g. `.cxx` -- `FEATURES_REQUIRED += cpp` must be added to the applications `Makefile` - - If additionally the libstdc++ is used, `FEATURES_REQUIRED += libstdcpp` - must be used additionally - -RIOT Modules in C++ {#cpp-in-riot} -=================== - -RIOT modules should be written in C, so that boards/platforms without or partial -C++ support can still use these modules. However, external modules, packages, -and modules that require C++ support anyway (e.g. the Arduino compatibility -features) can be written in C++. Also, some modules might be designed as -compatibility layer for C++ or provide convenient access to RIOT-OS' features -using C++ APIs. These modules/packages have to depend on the -`cpp` feature (`FEATURES_REQUIRED += cpp`) and possibly the `libstdcpp` -feature using their `Makefile.dep`. - -See Also {#see-also} -======== - -Reference @ref cpp for a list of C++ modules. +@deprecated Guides have moved to the [Guide Site](https://guide.riot-os.org/c_tutorials/using_cpp/). +This page will be removed after release 2026.04. diff --git a/doc/guides/c_tutorials/using_cpp.md b/doc/guides/c_tutorials/using_cpp.md new file mode 100644 index 0000000000..6e6a71d4ec --- /dev/null +++ b/doc/guides/c_tutorials/using_cpp.md @@ -0,0 +1,51 @@ +--- +title: Using C++ in RIOT +description: This document explains how to use C++ in RIOT, including levels of support and requirements for C++ code. +--- + +# Levels of Support + +A CPU in RIOT can have three levels of support for C++ code: + +1. No support for C++ at all +2. C++ is supported, but no libstdc++ implementation is available +3. C++ is supported and a libstdc++ implementation is available + +The reason for missing or only partial C++ support +can be one (or more) of the following: + +- No libstdc++ implementation for the target platform is available to RIOT, + or the official RIOT docker image is missing it +- Missing toolchain support for a given target platform +- The C++ toolchain requires library code + (such as constructor guards for the thread safe initialization of statically + allocated instances) or hooks in the startup process to perform initialization + +# Using C++ + +In order for C++ code to compile with RIOT, the following needs to be done: + +- All C++ files must have the file extension `.cpp`, all C++ headers `.hpp` + - For external code, overwriting the make variable `SRCXXEXT` + e.g. to `cxx` can be used to compile C++ files with other extensions, + e.g. `.cxx` +- `FEATURES_REQUIRED += cpp` must be added to the applications `Makefile` + - If additionally the libstdc++ is used, + `FEATURES_REQUIRED += libstdcpp` must be set. + +## RIOT Modules in C++ + +RIOT modules should be written in C, so that boards/platforms without +or partial C++ support can still use these modules. +However, external modules, packages and modules that require C++ support anyway +(e.g. the Arduino compatibility features) can be written in C++. +Also, some modules might be designed as compatibility layer for C++ +or provide convenient access to RIOT-OS' features using C++ APIs. +These modules/packages have to depend on the `cpp` feature +(`FEATURES_REQUIRED += cpp`) and possibly the `libstdcpp` feature +using their `Makefile.dep`. + +## See Also + +Reference [C++ modules](https://doc.riot-os.org/group__cpp.html) +for a list of C++ modules. diff --git a/doc/starlight/Makefile b/doc/starlight/Makefile index 170b61b860..265a97fb55 100644 --- a/doc/starlight/Makefile +++ b/doc/starlight/Makefile @@ -3,7 +3,7 @@ RIOTMAKE ?= $(RIOTBASE)/makefiles RIOTTOOLS ?= $(RIOTBASE)/dist/tools .PHONY: install -install: +install: integrate_outside_files @echo "Installing starlight..." @npm install --prefix $(CURDIR) --prefer-offline @echo "Starlight installed successfully." @@ -18,5 +18,20 @@ dev: install @echo "Starting starlight live server..." @npm run dev --prefix $(CURDIR) +.PHONY: clean clean: -@rm -rf node_modules .astro dist + +.PHONY: integrate_outside_files +integrate_outside_files: code_of_conduct governance + +.PHONY: code_of_conduct +code_of_conduct: ../../CODE_OF_CONDUCT.md + -@mkdir -p ../guides/generated + -@echo "Generating Code of Conduct documentation..." + -@sed '1,2d' $< | cat ./templates/CODE_OF_CONDUCT.template.md - > ../guides/generated/CODE_OF_CONDUCT.md + +.PHONY: governance +governance: ../../GOVERNANCE.md + -@echo "Generating Governance documentation..." + -@sed '1,2d' $< | sed '//,//d' | cat ./templates/GOVERNANCE.template.md - > ../guides/generated/GOVERNANCE.md diff --git a/doc/starlight/astro.config.mjs b/doc/starlight/astro.config.mjs index 914a5f4d6b..2fa18aaace 100644 --- a/doc/starlight/astro.config.mjs +++ b/doc/starlight/astro.config.mjs @@ -47,6 +47,8 @@ export default defineConfig({ { label: "Introduction", slug: "index" }, "general/structure", "general/vision", + "general/governance", + "general/code_of_conduct", ], }, { @@ -71,6 +73,7 @@ export default defineConfig({ "c_tutorials/threads", "c_tutorials/gpio", "c_tutorials/saul", + "c_tutorials/using_cpp", ], }, { diff --git a/doc/starlight/templates/CODE_OF_CONDUCT.template.md b/doc/starlight/templates/CODE_OF_CONDUCT.template.md new file mode 100644 index 0000000000..ab74c6ec0b --- /dev/null +++ b/doc/starlight/templates/CODE_OF_CONDUCT.template.md @@ -0,0 +1,5 @@ +--- +title: Code of Conduct +description: This document outlines the code of conduct for contributors of RIOT. +slug: general/code_of_conduct +--- diff --git a/doc/starlight/templates/GOVERNANCE.template.md b/doc/starlight/templates/GOVERNANCE.template.md new file mode 100644 index 0000000000..70e8e6babd --- /dev/null +++ b/doc/starlight/templates/GOVERNANCE.template.md @@ -0,0 +1,5 @@ +--- +title: Governance +description: This document outlines the governance structure of RIOT. +slug: general/governance +---