mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-20 13:51:05 +00:00
c66851d9ee
This change avoids polyfilling the constinit and constexpr keywords, which requires implicit polyfilling. Instead, this introduces a macro that is straightforward to use and portable. - Remove consteval and constinit language feature polyfills. - Provide PW_CONSTINIT macro that uses the constinit keyword or compiler attributes to guarantee constant initialization. - Update PW_CONSTEVAL so it always marks functions constexpr. Change-Id: I8b582b69a54717017bd30d4a33ae148f3a754095 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/50360 Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com> Reviewed-by: Keir Mierle <keir@google.com> Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
87 lines
5.4 KiB
ReStructuredText
87 lines
5.4 KiB
ReStructuredText
.. _module-pw_polyfill:
|
|
|
|
===========
|
|
pw_polyfill
|
|
===========
|
|
The ``pw_polyfill`` module backports new C++ features to older C++ standards.
|
|
When possible, features are adapted to work with in standards as old as C++11.
|
|
Pigweed does not support C++ standards older than C++11.
|
|
|
|
------------------------------------------------
|
|
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++11 or newer.
|
|
|
|
Language features are backported or stubbed via the
|
|
``pw_polyfill/language_features.h`` header. This header is included in files
|
|
that depend on ``pw_polyfill`` with GCC's ``-include`` option so that no
|
|
``#include`` statement is required.
|
|
|
|
The wrapper headers are in ``public_overrides``. These are provided through the
|
|
``"$dir_pw_polyfill:overrides"`` library, which the GN build adds as a
|
|
dependency for all targets. To apply overrides in Bazel or CMake, depend on the
|
|
``//pw_polyfill:overrides`` or ``pw_polyfill.overrides`` targets. In other build
|
|
systems, add ``pw_polyfill/standard_library_public`` and
|
|
``pw_polyfill/public_overrides`` as include paths, and add a ``-include`` option
|
|
for the ``language_features.h`` header.
|
|
|
|
Backported features
|
|
===================
|
|
================== ================================ ============================================ ========================================
|
|
Header Feature Level of support Feature test macro
|
|
================== ================================ ============================================ ========================================
|
|
<array> std::to_array full __cpp_lib_to_array
|
|
<bit> std::endian full __cpp_lib_endian
|
|
<cstdlib> std::byte full; some operators not constexpr in C++11 __cpp_lib_byte
|
|
<iterator> std::data, std::size full __cpp_lib_nonmember_container_access
|
|
<type_traits> \*_t trait aliases partial (can expand as needed) __cpp_lib_transformation_trait_aliases
|
|
<type_traits> std::is_null_pointer full __cpp_lib_is_null_pointer
|
|
<utilty> std::integer_sequence & helpers full __cpp_lib_integer_sequence
|
|
(language feature) static_assert with no message full __cpp_static_assert
|
|
================== ================================ ============================================ ========================================
|
|
|
|
----------------------------------------------------
|
|
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_FUNCTION relaxed constexpr function rules constexpr if relaxed rules are supported __cpp_constexpr >= 201304L
|
|
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++11
|