C++ Language Support
C++ is a general-purpose object-oriented programming language that is based on the C language.
Enabling C++ Support
Zephyr supports applications written in both C and C++. However, to use C++ in
an application you must configure Zephyr to include C++ support by selecting
the CONFIG_CPP in the application configuration file.
To enable C++ support, the compiler toolchain must also include a C++ compiler and the included compiler must be supported by the Zephyr build system. The Zephyr SDK, which includes the GNU C++ Compiler (part of GCC), is supported by Zephyr, and the features and their availability documented here assume the use of the Zephyr SDK.
The default C++ standard level (i.e. the language enforced by the
compiler flags passed) for Zephyr apps is C++11. Other standards are
available via kconfig choice, for example
CONFIG_STD_CPP98. The oldest standard supported and
tested in Zephyr is C++98.
When compiling a source file, the build system selects the C++ compiler based
on the suffix (extension) of the files. Files identified with either a cpp
or a cxx suffix are compiled using the C++ compiler. For example,
myCplusplusApp.cpp is compiled using C++.
The C++ standard requires the main() function to have the return type of
int. Your main() must be defined as int main(void) or
int main(int, char **). To use main with arguments the CONFIG_BOOTARGS option
has to be selected. Zephyr ignores the return value from main, so applications
should not return status information and should, instead, return zero.
Note
Do not use C++ for kernel, driver, or system initialization code.
Language Features
Zephyr currently provides only a subset of C++ functionality. The following features are not supported:
Static global object destruction
OS-specific C++ standard library classes (e.g.
std::thread,std::mutex)
While not an exhaustive list, support for the following functionality is included:
Inheritance
Virtual functions
Virtual tables
Static global object constructors
Dynamic object management with the new and delete operators
Exceptions
RTTI
Standard Template Library (STL)
Static global object constructors are initialized after the drivers are
initialized but before the application main() function. Therefore,
use of C++ is restricted to application code.
In order to make use of the C++ exceptions, the
CONFIG_CPP_EXCEPTIONS must be selected in the application
configuration file.
Zephyr Minimal C++ Library
Zephyr minimal C++ library (lib/cpp/minimal) provides a minimal subset
of the C++ standard library and application binary interface (ABI) functions to
enable basic C++ language support. This includes:
newanddeleteoperatorsvirtual function stub and vtables
static global initializers for global constructors
The scope of the minimal C++ library is strictly limited to providing the basic C++ language support, and it does not implement any Standard Template Library (STL) classes and functions. For this reason, it is only suitable for use in the applications that implement their own (non-standard) class library and do not rely on the Standard Template Library (STL) components.
Any application that makes use of the Standard Template Library (STL)
components, such as std::string and std::vector, must enable the C++
standard library support.
C++ Standard Library
The C++ Standard Library is a collection of classes and functions that are
part of the ISO C++ standard (std namespace).
Zephyr does not include any C++ standard library implementation in source code form. Instead, it allows configuring the build system to link against the pre-built C++ standard library included in the C++ compiler toolchain.
To enable C++ standard library, select an applicable toolchain-specific C++
standard library type from the CONFIG_LIBCPP_IMPLEMENTATION
in the application configuration file.
For instance, when building with the Zephyr SDK, the build
system can be configured to link against the GNU C++ Library (libstdc++.a),
which is a fully featured C++ standard library that provides all features
required by the ISO C++ standard including the Standard Template Library (STL),
by selecting CONFIG_GLIBCXX_LIBCPP in the application
configuration file.
The following C++ standard libraries are supported by Zephyr:
GNU C++ Library (
CONFIG_GLIBCXX_LIBCPP)ARC MetaWare C++ Library (
CONFIG_ARCMWDT_LIBCPP)
A Zephyr subsystem that requires the features from the full C++ standard
library can select, from its config,
CONFIG_REQUIRES_FULL_LIBCPP, which automatically selects a
compatible C++ standard library unless the Kconfig symbol for a specific C++
standard library is selected.
Header files and incompatibilities between C and C++
To interact with each other, C and C++ must share code through header files: data structures, macros, static functions,… While C and C++ have a large overlap, they’re different languages with known incompatibilities. C is not just a C++ subset. Standard levels (e.g.: “C+11”) add another level of complexity as new features are often inspired by and copied from the other language but many years later and with subtle differences. Making things more complex, compilers often offer early prototypes of features before they become standardized. Standards can have ambiguities interpreted differently by different compilers. Compilers can have bugs and these may need workarounds. To help with this, many projects restrict themselves to a limited number of toolchains. Zephyr does not.
These compatibility issues affect header files dis-proportionally. Not just because they have to be compatible between C and C++, but also because they end up being compiled in a surprisingly high number of other source files due to indirect inclusion and the lack of structure and headers organization that is typical in real-world projects. So, header files are exposed to a much larger variety of toolchains and project configurations. Adding more constraints, the Zephyr project has demanding policies with respect to code style, compiler warnings, static analyzers and standard compliance (e.g.: MISRA).
Put together, all these constraints can make writing header files very challenging. The purpose of this section is to document some best “header practices” and lessons learned in a Zephyr-specific context. While a lot of the information here is not Zephyr-specific, this section is not a substitute for knowledge of C/C++ standards, textbooks and other references.
Testing
Fortunately, the Zephyr project has an extensive test and CI
infrastructure that provides coverage baselines, catches issues early,
enforces policies and maintains such combinatorial explosions under some
control. The tests/lib/cpp/cxx/ are very useful in this context
because their testcase.yaml configuration lets twister iterate
quickly over a range of -std parameters: -std=c++98,
-std=c++11, etc.
Keep in mind unused macros are not compiled.
Designated initializers
Initialization macros are common in header files as they help reduce
boilerplate code. C99 added initialization of struct and union
types by “designated” member names instead of a list of bare
expressions. Some GCC versions support designated initializers even in
their C90 mode.
When used at a simple level, designated initializers are less
error-prone, more readable and more flexible. On the other hand, C99
allowed a surprisingly large and lax set of possibilities: designated
initializers can be out of order, duplicated, “nested” (.a.x =),
various other braces can be omitted, designated initializers and not can
be mixed, etc.
Twenty years later, C++20 added designated initializers to C++ but in
much more restricted way; partly because a C++ struct is actually a
class. As described in the C++ proposal number P0329 (which compares
with C) or in any complete C++ reference, a mix is not allowed and
initializers must be in order (gaps are allowed).
Interestingly, the new restrictions in C++20 can cause gcc -std=c++20
to fail to compile code that successfully compiles with
gcc -std=c++17. For example, gcc -std=c++17 and older allow the
C-style mix of initializers and bare expressions. This fails to compile
with using gcc -std=c++20 with the same GCC version.
Recommendation: to maximize compatibility across different C and C++ toolchains and standards, designated initializers in Zephyr header files should follow all C++20 rules and restrictions. Non-designated, pre-C99 initialization offers more compatibility and is also allowed but designated initialization is the more readable and preferred code style. In any case, both styles must never be mixed in the same initializer.
Warning: successful compilation is not the end of the incompatibility story. For instance, the evaluation order of initializer expressions is unspecified in C99! It is the (expected) left-to-right order in C++20. Other standard revisions may vary. In doubt, do not rely on evaluation order (here and elsewhere).
Anonymous unions
Anonymous unions (a.k.a. “unnamed” unions) seem to have been part of C++
from its very beginning. They were not officially added to C until C11.
As usual, there are differences between C and C++. For instance, C
supports anonymous unions only as a member of an enclosing struct or
union, empty lists { } have always been allowed in C++ but they
require C23, etc.
When initializing anonymous members, the expression can be enclosed in braces or not. It can be either designated or bare. For maximum portability, when initializing anonymous unions:
Do not enclose designated initializers with braces. This is required by C++20 and above which perceive such braces as mixing bare expressions with (other) designated initializers and fails to compile.
Do enclose bare expressions with braces. This is required by C. Maybe because C is laxer and allows many initialization possibilities and variations, so it may need such braces to disambiguate? Note C does allow omitting most braces in initializer expressions - but not in this particular case of initializing anonymous unions with bare expressions.
Some pre-C11 GCC versions support some form of anonymous unions. They
unfortunately require enclosing their designated initializers with
braces which conflicts with this recommendation. This can be solved
with an #ifdef __STDC_VERSION__ as demonstrated in Zephyr commit
c15f029a7108 and
the corresponding code review.