Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 1 | .. _chapter-pw-polyfill: |
| 2 | |
| 3 | .. default-domain:: cpp |
| 4 | |
| 5 | .. highlight:: sh |
| 6 | |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 7 | =========== |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 8 | pw_polyfill |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 9 | =========== |
| 10 | The ``pw_polyfill`` module backports new C++ features to older C++ standards. |
| 11 | When possible, features are adapted to work with in standards as old as C++11. |
| 12 | Pigweed does not support C++ standards older than C++11. |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 13 | |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 14 | ------------------------------------------------ |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 15 | Backport new C++ features to older C++ standards |
| 16 | ------------------------------------------------ |
| 17 | The main purpose of ``pw_polyfill`` is to bring new C++ library and language |
| 18 | features to older C++ standards. No additional ``#include`` statements are |
| 19 | required to use these features; simply write code assuming that the features are |
| 20 | available. This implicit feature backporting is provided through the |
| 21 | ``overrides`` library in the ``pw_polyfill`` module. GN automatically adds this |
| 22 | library as a dependency in ``pw_source_set``. |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 23 | |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 24 | ``pw_polyfill`` backports C++ library features by wrapping the standard C++ and |
| 25 | C headers. The wrapper headers include the original header using |
| 26 | `#include_next <https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then |
| 27 | add missing features. The backported features are only defined if they aren't |
| 28 | provided by the standard header, so ``pw_polyfill`` is safe to use when |
| 29 | compiling with any standard C++11 or newer. |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 30 | |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 31 | Language features are backported or stubbed via the |
| 32 | ``pw_polyfill/language_features.h`` header. This header is included in files |
| 33 | that depend on ``pw_polyfill`` with GCC's ``-include`` option so that no |
| 34 | ``#include`` statement is required. |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 35 | |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 36 | The wrapper headers are in ``public_overrides``. These are provided through the |
| 37 | ``"$dir_pw_polyfill:overrides"`` library, which the GN build adds as a |
| 38 | dependency for all targets. To apply overrides in Bazel or CMake, depend on the |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 39 | ``//pw_polyfill:overrides`` or ``pw_polyfill.overrides`` targets. In other build |
| 40 | systems, add ``pw_polyfill/standard_library_public`` and |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 41 | ``pw_polyfill/public_overrides`` as include paths, and add a ``-include`` option |
| 42 | for the ``language_features.h`` header. |
| 43 | |
| 44 | Backported features |
| 45 | =================== |
| 46 | ================== ================================ ============================================ ======================================== |
| 47 | Header Feature Level of support Feature test macro |
| 48 | ================== ================================ ============================================ ======================================== |
| 49 | <array> std::to_array full __cpp_lib_to_array |
| 50 | <cstdlib> std::byte full; some operators not constexpr in C++11 __cpp_lib_byte |
| 51 | <iterator> std::data, std::size full __cpp_lib_nonmember_container_access |
| 52 | <type_traits> \*_t trait aliases partial (can expand as needed) __cpp_lib_transformation_trait_aliases |
| 53 | <type_traits> std::is_null_pointer full __cpp_lib_is_null_pointer |
| 54 | <utilty> std::integer_sequence & helpers full __cpp_lib_integer_sequence |
| 55 | (language feature) consteval keyword ignored (equivalent to constexpr) __cpp_consteval |
| 56 | (language feature) constinit keyword supported in clang; ignored in GCC __cpp_constinit |
| 57 | (language feature) static_assert with no message full __cpp_static_assert |
| 58 | ================== ================================ ============================================ ======================================== |
| 59 | |
| 60 | ---------------------------------------------------- |
| 61 | Adapt code to compile with different versions of C++ |
| 62 | ---------------------------------------------------- |
| 63 | ``pw_polyfill`` provides features for adapting to different C++ standards when |
| 64 | ``pw_polyfill:overrides``'s automatic backporting is insufficient: |
| 65 | |
| 66 | - ``pw_polyfill/standard.h`` -- provides a macro for checking the C++ standard |
| 67 | - ``pw_polyfill/language_feature_macros.h`` -- provides macros for adapting |
| 68 | code to work with or without newer language features |
| 69 | |
| 70 | In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``, |
| 71 | or ``pw_polyfill``, respectively, to access these features. In other build |
| 72 | systems, add ``pw_polyfill/standard_library_public`` and |
Wyatt Hepler | c542a5d | 2020-01-15 15:43:10 -0800 | [diff] [blame] | 73 | ``pw_polyfill/public_overrides`` as include paths. |
Wyatt Hepler | 8e59f4d | 2020-08-27 10:34:21 -0700 | [diff] [blame^] | 74 | |
| 75 | ------------- |
| 76 | Compatibility |
| 77 | ------------- |
| 78 | C++11 |