Merge pull request #14503 from maribu/cpp-feature

build system: Add libstdcpp feature and doc

Makefile.dep

@@ -620,6 +620,7 @@ ifneq (,$(filter cpp11-compat,$(USEMODULE)))
   USEMODULE += xtimer
   USEMODULE += timex
   FEATURES_REQUIRED += cpp
+  FEATURES_REQUIRED += libstdcpp
 endif
 
 ifneq (,$(filter gnrc,$(USEMODULE)))
@@ -1096,6 +1097,11 @@ FEATURES_REQUIRED += $(filter cpu_core_%,$(FEATURES_PROVIDED))
 # don't use idle thread if architecture has needed support
 FEATURES_OPTIONAL += no_idle_thread
 
+ifneq (,$(filter libstdcpp,$(FEATURES_USED)))
+  # Also use C++ if libstdc++ is used
+  FEATURES_REQUIRED += cpp
+endif
+
 ifneq (,$(filter ecc_%,$(USEMODULE)))
   USEMODULE += ecc
 endif

cpu/arm7_common/Makefile.features

@@ -5,6 +5,7 @@ FEATURES_PROVIDED += arch_32bit
 FEATURES_PROVIDED += arch_arm
 FEATURES_PROVIDED += arch_arm7
 FEATURES_PROVIDED += cpp
+FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += periph_pm
 FEATURES_PROVIDED += puf_sram
 FEATURES_PROVIDED += ssp

cpu/cortexm_common/Kconfig

@@ -31,6 +31,7 @@ config CPU_CORE_CORTEX_M
     select HAS_CPU_CORE_CORTEXM
     select HAS_PERIPH_PM
     select HAS_CPP
+    select HAS_LIBSTDCPP
     select HAS_CPU_CHECK_ADDRESS
     select HAS_SSP
     select HAS_CORTEXM_SVC

cpu/cortexm_common/Makefile.features

@@ -1,10 +1,11 @@
 FEATURES_PROVIDED += arch_32bit
 FEATURES_PROVIDED += arch_arm
-FEATURES_PROVIDED += cpu_core_cortexm
-FEATURES_PROVIDED += periph_pm
 FEATURES_PROVIDED += cortexm_svc
 FEATURES_PROVIDED += cpp
 FEATURES_PROVIDED += cpu_check_address
+FEATURES_PROVIDED += cpu_core_cortexm
+FEATURES_PROVIDED += libstdcpp
+FEATURES_PROVIDED += periph_pm
 FEATURES_PROVIDED += ssp
 
 # cortex-m4f and cortex-m7 provide FPU support

cpu/esp_common/Kconfig

@@ -15,6 +15,7 @@ config CPU_COMMON_ESP
     select HAS_ESP_NOW
     select HAS_ESP_SPIFFS
     select HAS_ESP_WIFI
+    select HAS_LIBSTDCPP
     select HAS_PERIPH_CPUID
     select HAS_PERIPH_HWRNG
     select HAS_PERIPH_PM

cpu/esp_common/Makefile.features

@@ -8,6 +8,7 @@ FEATURES_PROVIDED += cpp
 FEATURES_PROVIDED += esp_now
 FEATURES_PROVIDED += esp_spiffs
 FEATURES_PROVIDED += esp_wifi
+FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += periph_cpuid
 FEATURES_PROVIDED += periph_hwrng
 FEATURES_PROVIDED += periph_pm

cpu/fe310/Kconfig

@@ -24,6 +24,7 @@ config CPU_FAM_FE310
     select HAS_PERIPH_PM
     select HAS_PERIPH_WDT
     select HAS_CPP
+    select HAS_LIBSTDCPP
     select HAS_SSP
 
 config CPU_MODEL_FE310_G000

cpu/fe310/Makefile.features

@@ -1,6 +1,7 @@
 FEATURES_PROVIDED += arch_32bit
 FEATURES_PROVIDED += arch_riscv
 FEATURES_PROVIDED += cpp
+FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += periph_cpuid
 FEATURES_PROVIDED += periph_gpio periph_gpio_irq
 FEATURES_PROVIDED += periph_pm

cpu/mips32r2_common/Makefile.features

@@ -3,4 +3,5 @@ CPU_ARCH = mips32r2
 FEATURES_PROVIDED += arch_32bit
 FEATURES_PROVIDED += arch_mips32r2
 FEATURES_PROVIDED += cpp
+FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += periph_pm

cpu/native/Makefile.features

@@ -1,6 +1,15 @@
+ifeq (FreeBSD,$(OS))
+  DISABLE_LIBSTDCPP ?= 1
+endif
+
 FEATURES_PROVIDED += arch_32bit
 FEATURES_PROVIDED += arch_native
 FEATURES_PROVIDED += cpp
+ifneq ($(DISABLE_LIBSTDCPP),1)
+  # libstdc++ on FreeBSD is broken (does not work with -m32)
+  # Override with "export DISABLE_LIBSTDCPP=0"
+  FEATURES_PROVIDED += libstdcpp
+endif
 FEATURES_PROVIDED += periph_cpuid
 FEATURES_PROVIDED += periph_eeprom
 FEATURES_PROVIDED += periph_hwrng

doc/doxygen/riot.doxyfile

@@ -770,6 +770,7 @@ INPUT                  = ../../doc.txt \
                          ../../tests/README.md \
                          src/build-system-basics.md \
                          src/kconfig/kconfig.md \
+                         src/using-cpp.md \
                          src/advanced-build-system-tricks.md \
                          src/changelog.md \
                          ../../LOSTANDFOUND.md

doc/doxygen/src/using-cpp.md

@@ -0,0 +1,50 @@
+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++. 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}
+========
+
+@ref sys_c11_atomics_cpp_compat, @ref cpp11-compat

kconfigs/Kconfig.features

@@ -67,6 +67,11 @@ config HAS_ETHERNET
     help
         Indicates that Ethernet connectivity is present.
 
+config HAS_LIBSTDCPP
+    bool
+    help
+        Indicates that in addition to C++ support an libstdc++ is available.
+
 config HAS_NO_IDLE_THREAD
     bool
     help

tests/cpp_exclude/Makefile

@@ -1,6 +1,6 @@
 include ../Makefile.tests_common
 
-FEATURES_REQUIRED += cpp
+FEATURES_REQUIRED += cpp libstdcpp
 
 USEMODULE += module_exclude
 EXTERNAL_MODULE_DIRS += $(CURDIR)/module_exclude

tests/cpp_ext/Makefile

@@ -1,6 +1,6 @@
 include ../Makefile.tests_common
 
-FEATURES_REQUIRED += cpp
+FEATURES_REQUIRED += cpp libstdcpp
 
 USEMODULE += module
 EXTERNAL_MODULE_DIRS += $(CURDIR)/module