1.. _module-pw_polyfill: 2 3=========== 4pw_polyfill 5=========== 6The ``pw_polyfill`` module backports new C++ features to C++14. 7 8------------------------------------------------ 9Backport new C++ features to older C++ standards 10------------------------------------------------ 11The main purpose of ``pw_polyfill`` is to bring new C++ library and language 12features to older C++ standards. No additional ``#include`` statements are 13required to use these features; simply write code assuming that the features are 14available. This implicit feature backporting is provided through the 15``overrides`` library in the ``pw_polyfill`` module. GN automatically adds this 16library as a dependency in ``pw_source_set``. 17 18``pw_polyfill`` backports C++ library features by wrapping the standard C++ and 19C headers. The wrapper headers include the original header using 20`#include_next <https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then 21add missing features. The backported features are only defined if they aren't 22provided by the standard header, so ``pw_polyfill`` is safe to use when 23compiling with any standard C++14 or newer. 24 25The wrapper headers are in ``public_overrides``. These are provided through the 26``"$dir_pw_polyfill"`` libraries, which the GN build adds as a 27dependency for all targets: 28 29* ``$dir_pw_polyfill:bit`` 30* ``$dir_pw_polyfill:cstddef`` 31* ``$dir_pw_polyfill:iterator`` 32* ``$dir_pw_polyfill:span`` 33* ``$dir_pw_polyfill:type_traits`` 34 35To apply overrides in Bazel or CMake, depend on the targets you need such as 36``//pw_polyfill:span`` or ``pw_polyfill.span`` as an example. 37 38Backported features 39=================== 40================== ================================ =============================== ======================================== 41Header Feature Level of support Feature test macro 42================== ================================ =============================== ======================================== 43<bit> std::endian full __cpp_lib_endian 44<cstdlib> std::byte full __cpp_lib_byte 45<iterator> std::data, std::size full __cpp_lib_nonmember_container_access 46<type_traits> std::bool_constant full __cpp_lib_bool_constant 47<type_traits> std::negation, etc. full __cpp_lib_logical_traits 48================== ================================ =============================== ======================================== 49 50---------------------------------------------------- 51Adapt code to compile with different versions of C++ 52---------------------------------------------------- 53 ``pw_polyfill`` provides features for adapting to different C++ standards when 54 ``pw_polyfill:overrides``'s automatic backporting is insufficient: 55 56 - ``pw_polyfill/standard.h`` -- provides a macro for checking the C++ standard 57 - ``pw_polyfill/language_feature_macros.h`` -- provides macros for adapting 58 code to work with or without newer language features 59 60Language feature macros 61======================= 62====================== ================================ ======================================== ========================== 63Macro Feature Description Feature test macro 64====================== ================================ ======================================== ========================== 65PW_INLINE_VARIABLE inline variables inline if supported by the compiler __cpp_inline_variables 66PW_CONSTEXPR_CPP20 constexpr in C++20 constexpr if compiling for C++20 __cplusplus >= 202002L 67PW_CONSTEVAL consteval consteval if supported by the compiler __cpp_consteval 68PW_CONSTINIT constinit constinit in clang and GCC 10+ __cpp_constinit 69====================== ================================ ======================================== ========================== 70 71In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``, 72or ``pw_polyfill``, respectively, to access these features. In other build 73systems, add ``pw_polyfill/standard_library_public`` and 74``pw_polyfill/public_overrides`` as include paths. 75 76------------- 77Compatibility 78------------- 79C++14 80 81Zephyr 82====== 83To enable ``pw_polyfill`` for Zephyr add ``CONFIG_PIGWEED_POLYFILL=y`` to the 84project's configuration. Similarly, to enable ``pw_polyfill.overrides``, add 85``CONFIG_PIGWEED_POLYFILL_OVERRIDES=y`` to the project's configuration. 86