86 lines
4.7 KiB
ReStructuredText
86 lines
4.7 KiB
ReStructuredText
.. _module-pw_polyfill:
|
|
|
|
===========
|
|
pw_polyfill
|
|
===========
|
|
The ``pw_polyfill`` module backports new C++ features to C++14.
|
|
|
|
------------------------------------------------
|
|
Backport new C++ features to older C++ standards
|
|
------------------------------------------------
|
|
The main purpose of ``pw_polyfill`` is to bring new C++ library and language
|
|
features to older C++ standards. No additional ``#include`` statements are
|
|
required to use these features; simply write code assuming that the features are
|
|
available. This implicit feature backporting is provided through the
|
|
``overrides`` library in the ``pw_polyfill`` module. GN automatically adds this
|
|
library as a dependency in ``pw_source_set``.
|
|
|
|
``pw_polyfill`` backports C++ library features by wrapping the standard C++ and
|
|
C headers. The wrapper headers include the original header using
|
|
`#include_next <https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then
|
|
add missing features. The backported features are only defined if they aren't
|
|
provided by the standard header, so ``pw_polyfill`` is safe to use when
|
|
compiling with any standard C++14 or newer.
|
|
|
|
The wrapper headers are in ``public_overrides``. These are provided through the
|
|
``"$dir_pw_polyfill"`` libraries, which the GN build adds as a
|
|
dependency for all targets:
|
|
|
|
* ``$dir_pw_polyfill:bit``
|
|
* ``$dir_pw_polyfill:cstddef``
|
|
* ``$dir_pw_polyfill:iterator``
|
|
* ``$dir_pw_polyfill:span``
|
|
* ``$dir_pw_polyfill:type_traits``
|
|
|
|
To apply overrides in Bazel or CMake, depend on the targets you need such as
|
|
``//pw_polyfill:span`` or ``pw_polyfill.span`` as an example.
|
|
|
|
Backported features
|
|
===================
|
|
================== ================================ =============================== ========================================
|
|
Header Feature Level of support Feature test macro
|
|
================== ================================ =============================== ========================================
|
|
<bit> std::endian full __cpp_lib_endian
|
|
<cstdlib> std::byte full __cpp_lib_byte
|
|
<iterator> std::data, std::size full __cpp_lib_nonmember_container_access
|
|
<type_traits> std::bool_constant full __cpp_lib_bool_constant
|
|
<type_traits> std::negation, etc. full __cpp_lib_logical_traits
|
|
================== ================================ =============================== ========================================
|
|
|
|
----------------------------------------------------
|
|
Adapt code to compile with different versions of C++
|
|
----------------------------------------------------
|
|
``pw_polyfill`` provides features for adapting to different C++ standards when
|
|
``pw_polyfill:overrides``'s automatic backporting is insufficient:
|
|
|
|
- ``pw_polyfill/standard.h`` -- provides a macro for checking the C++ standard
|
|
- ``pw_polyfill/language_feature_macros.h`` -- provides macros for adapting
|
|
code to work with or without newer language features
|
|
|
|
Language feature macros
|
|
=======================
|
|
====================== ================================ ======================================== ==========================
|
|
Macro Feature Description Feature test macro
|
|
====================== ================================ ======================================== ==========================
|
|
PW_INLINE_VARIABLE inline variables inline if supported by the compiler __cpp_inline_variables
|
|
PW_CONSTEXPR_CPP20 constexpr in C++20 constexpr if compiling for C++20 __cplusplus >= 202002L
|
|
PW_CONSTEVAL consteval consteval if supported by the compiler __cpp_consteval
|
|
PW_CONSTINIT constinit constinit in clang and GCC 10+ __cpp_constinit
|
|
====================== ================================ ======================================== ==========================
|
|
|
|
In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``,
|
|
or ``pw_polyfill``, respectively, to access these features. In other build
|
|
systems, add ``pw_polyfill/standard_library_public`` and
|
|
``pw_polyfill/public_overrides`` as include paths.
|
|
|
|
-------------
|
|
Compatibility
|
|
-------------
|
|
C++14
|
|
|
|
Zephyr
|
|
======
|
|
To enable ``pw_polyfill`` for Zephyr add ``CONFIG_PIGWEED_POLYFILL=y`` to the
|
|
project's configuration. Similarly, to enable ``pw_polyfill.overrides``, add
|
|
``CONFIG_PIGWEED_POLYFILL_OVERRIDES=y`` to the project's configuration.
|