1.. _module-pw_minimal_cpp_stdlib: 2 3===================== 4pw_minimal_cpp_stdlib 5===================== 6.. admonition:: �� Stop �� 7 8 **Do not use this module** unless you have consulted with the Pigweed team. 9 10----------- 11Maintenance 12----------- 13If you discovered this module because of a build failure in a 14``pw_strict_host_clang_size_optimized_minimal_cpp_stdlib`` or similar target, 15the important thing to know is that a small set of Pigweed targets are expected 16to compile using a limited set of C++ Standard Library features and headers 17that have been polyfilled by this module in order to support environments 18without a C++ stdlib. 19 20Failed ``#include`` lines should be solved by either eliminating the dependency 21from the target (strongly preferred) or by adding a (minimal) polyfill of the 22relevant C++ header to this module. 23 24Polyfills may assume a C++17 (or greater) compiler but with only a C (not C++) 25stdlib. As this target does not support tests, polyfills can only be checked for 26compilation; this can be done by building the root 27``build_with_pw_minimal_cpp_stdlib group`` 28(e.g. ``ninja -C out build_with_pw_minimal_cpp_stdlib``). 29 30------- 31Purpose 32------- 33The ``pw_minimal_cpp_stdlib`` module provides an extremely limited, incomplete 34implementation of the C++ Standard Library. This module is only intended for 35testing and development when compiling with C++17 or newer, but without access 36to the C++ Standard Library (``-nostdinc++``). 37 38Production code should use a real C++ Standard Library implementation, such as 39`libc++ <https://libcxx.llvm.org/>`_ or `libstdc++ 40<https://gcc.gnu.org/onlinedocs/libstdc++/>`_. 41 42.. warning:: 43 44 ``pw_minimal_cpp_stdlib`` was created for a very specific purpose. It is NOT a 45 general purpose C++ Standard Library implementation and should not be used as 46 one. 47 48 - Many library features are **missing**. 49 - Many features are **non-functioning stubs**. 50 - Some features **do not match the C++ standard**. 51 - Test coverage is **extremely limited**. 52 53----------------- 54Build integration 55----------------- 56The top-level ``build_with_minimal_cpp_stdlib`` GN group builds a few supported 57modules with ``pw_minimal_cpp_stdlib`` swapped in for the C++ library at the 58toolchain level. Notably, ``pw_minimal_cpp_stdlib`` does not support 59``pw_unit_test``, so this group does NOT run any tests. 60 61----------- 62Code layout 63----------- 64The C++ Standard Library headers (e.g. ``<cstdint>`` and ``<type_traits>``) are 65defined in ``public/``. These files are symlinks to their implementations in 66``public/internal/``. 67 68.. tip:: 69 70 You can automatically recreate the symlinks in ``public/`` by executing the 71 following Bash code from ``pw_minimal_cpp_stdlib/public/``. 72 73 .. code-block:: bash 74 75 for f in $(ls pw_minimal_cpp_stdlib/internal/); do ln -s pw_minimal_cpp_stdlib/internal/$f ${f%.h}; done 76 77------------ 78Requirements 79------------ 80- C++17 81- gcc or clang 82- The C Standard Library 83